Para que los usuarios de tu sistema entren con su cuenta de Ciudadanía Digital, integras un proveedor de identidad OpenID Connect que administra la Agencia de Gobierno Electrónico y Tecnologías de Información y Comunicación (AGETIC). El flujo es el estándar authorization code: tu sistema redirige al ciudadano a proveedor.ciudadaniadigital.bo, recibe un código, lo cambia por tokens y pide los datos al endpoint /me. Las pruebas se hacen en el portal developer.ciudadaniadigital.bo y el pase a producción lo aprueba la AGETIC. Quién puede llegar a producción lo define la Ley 1080: las entidades públicas y las privadas que prestan servicios públicos delegados por el Estado.

Quién puede integrarlo

La Ley N° 1080 se aplica a «las entidades públicas y privadas que presten servicios públicos delegados por el Estado, en todos los Órganos y niveles de gobierno» (art. 2). Su artículo 10 obliga a esas instituciones a adaptar sus procesos a los lineamientos de la AGETIC, y permite que las entidades territoriales autónomas incorporen Ciudadanía Digital a sus servicios.

Las reglas técnicas vigentes son los lineamientos versión 5, aprobados con la Resolución Administrativa AGETIC/RA/0114/2024 y modificados con la AGETIC/RA/0120/2024. La RA 0114 los declara de uso obligatorio para el mismo grupo de entidades.

En la práctica hay que distinguir entre probar y llegar a producción:

  • Probar: según el portal developer, el único requisito es tener una cuenta de Ciudadanía Digital activa. La portada dice que se puede integrar «como ciudadano o técnico de una institución».
  • Producción: la entidad firma la Norma Técnica de Adhesión por medio de su máxima autoridad ejecutiva, designa un gestor institucional que habilita a los técnicos y declara qué sistema usará cada mecanismo.

Las normas que revisamos no prevén el caso de una empresa privada que no presta un servicio público delegado. Si ese es tu caso, consulta antes a la AGETIC. Lo habitual es que una empresa de software haga la integración para una entidad pública: la adhesión y las credenciales de producción quedan a nombre de la entidad.

Qué mecanismos hay

La Norma Técnica de Adhesión enumera cuatro:

Mecanismo Qué hace
Autenticación Identifica al ciudadano con usuario, contraseña y doble factor
Aprobación Registra el consentimiento del ciudadano sobre un documento PDF o JSON
Autorización Pide al ciudadano consentimiento para usar ciertos datos suyos
Notificaciones electrónicas Entrega notificaciones con validez desde que llegan al buzón

Para probar la aprobación de documentos, primero hay que tener integrada la autenticación.

El protocolo, según la configuración publicada

El proveedor publica su configuración en /.well-known/openid-configuration. Esto es lo que mostraba la configuración de producción al consultarla el 10 de noviembre de 2026:

Parámetro Valor
issuer en producción https://proveedor.ciudadaniadigital.bo
issuer en el ambiente demo https://proveedor.ciudadania.demo.agetic.gob.bo
response_types_supported solo code
PKCE (code_challenge_methods_supported) solo S256
Firma del ID token PS256, RS256 o ES256
Autenticación del cliente en /token client_secret_basic, client_secret_post o none
Endpoints /auth, /token, /me, /session/end, /token/introspection, /token/revocation, /jwks

Un detalle: la página de terminología de la documentación todavía muestra plain entre los métodos PKCE y /certs como ruta de las llaves, pero la configuración en vivo dice S256 y /jwks. Lee la configuración con una librería OpenID Connect certificada en vez de escribir las URL a mano.

Paso a paso para integrar el login

  1. Entra al portal developer con tu Ciudadanía Digital. En la bandeja Test, crea un proyecto. Te pedirá elegir el sistema cliente, que debe estar registrado en el portal Gob.bo (guía de creación de proyectos).
  2. Agrega el mecanismo de autenticación y elige si es una aplicación web o móvil. Una app móvil queda con el método none y debe usar PKCE.
  3. Registra las URI. Son obligatorias la de redirección al iniciar sesión y la de cierre de sesión. La de política de privacidad es opcional y se muestra la primera vez que el usuario entra a tu sistema.
  4. Elige los scopes y marca cada uno como requerido, opcional o no requerido (registro del mecanismo). El portal te entrega los datos de configuración y usuarios de prueba que puedes descargar.
  5. Genera state y nonce aleatorios (la documentación sugiere al menos 30 caracteres) y guárdalos en la sesión. Redirige a /auth con response_type=code, client_id, redirect_uri, scope, state y nonce (flujo authorization code).
  6. En el callback, comprueba que state y nonce coincidan y cambia el code por tokens con un POST a /token. El código sirve una sola vez.
  7. Valida el ID token (firma, iss, aud, exp y nonce) y pide los datos a /me con el access token.
  8. Para cerrar sesión, redirige a /session/end con id_token_hint y post_logout_redirect_uri (finalizar sesión).
  9. Pide el pase a producción desde el mismo portal. Cargas los parámetros de producción, el personal de la AGETIC los revisa y, si los aprueba, el proyecto pasa a la bandeja Producción (pase a producción).

Si necesitas un refresh token, agrega el scope offline_access y envía prompt=consent. Con prompt=login, el proveedor pide siempre las credenciales, aunque el ciudadano ya tenga sesión abierta.

La documentación exige PKCE solo a las apps móviles. La guía de seguridad de OAuth de la IETF, el RFC 9700, lo recomienda también para los clientes web, y el proveedor lo acepta con S256.

Qué datos entrega

Según la documentación de scopes y la del endpoint /me:

Scope Qué recibes
openid El identificador del ciudadano (sub, un UUID)
profile Número y tipo de documento, nombres, primer y segundo apellido
fecha_nacimiento Fecha en formato DD/MM/AAAA
email Correo electrónico
celular Número de celular
offline_access Un refresh token

Los scopes nombre y documento_identidad figuran como obsoletos: usa profile. La AGETIC repite que pidas la fecha de nacimiento, el correo y el celular «sólo si se hará uso» de ellos en tu sistema. Para identificar a cada persona en tu base de datos, usa sub.

Aprobación de documentos: qué es y qué no es

Con el mecanismo de aprobación, tu sistema envía un PDF o un JSON en Base64, su hash SHA-256, un idTramite en formato UUID v4 y el access token del ciudadano. El ciudadano ve el documento y lo acepta o lo rechaza. Después, tu backend recibe una notificación y el navegador vuelve a tu URL con un enlace de verificación (aprobación individual). También existe la aprobación múltiple. Para registrar el mecanismo debes dar una URL de redirección, una URL de notificación y un token que proteja esa notificación (registro).

La aprobación queda en el registro de orden cronológico e integridad. Según la especificación técnica 1.2 de la AGETIC, ese registro es una cadena de bloques que permite verificar después que el documento enviado no fue alterado. Cualquiera puede comprobar un documento en la página de verificación.

Aprobar no equivale a firmar digitalmente. La Ley 1080 (art. 8) dice que las solicitudes por Ciudadanía Digital no requieren firma digital, «con excepción de los actos de disposición de derechos». Y la Norma Técnica de Adhesión hace a la entidad responsable de decidir qué actos exigen firma digital o presencia física.

Protección de datos y responsabilidades

  • La Ley 1080 (art. 12) permite usar los datos solo para los fines de la normativa. Si una institución pública incumple, hay responsabilidad por la función pública.
  • La Norma Técnica de Adhesión declara confidenciales los datos compartidos con la AGETIC, que no pueden cederse a terceros (art. 7). También obliga a reportar de inmediato cualquier fallo de seguridad (art. 5).
  • La misma norma pone a cargo de la entidad la mala implementación y las fallas de almacenamiento y resguardo. Además, exime a la AGETIC por las interrupciones del servicio.
  • Al 10 de noviembre de 2026 no encontramos publicada una ley general de protección de datos en Bolivia. Revisa qué rige hoy en nuestra guía de datos personales.

Errores comunes

  • La redirect_uri no coincide. Debe ser la misma que registraste en el portal y la misma en /auth y en /token. En la aprobación de documentos, la URL de redirección debe usar https y no llevar query ni fragmento, según la especificación de la AGETIC.
  • Mostrar error_description tal cual al usuario. Es un texto técnico en inglés: muestra un mensaje propio que diga qué hacer.
  • Guardar el client_secret en el navegador o en la app. Los clientes públicos usan none y PKCE.
  • Reutilizar el idTramite. El aprobador responde «Ya existe una solicitud». Si el registro falla (introducido: false), la especificación indica volver a enviar la solicitud.
  • Aprobar con un token vencido. El aprobador responde con el código 412: el ciudadano debe volver a iniciar sesión.

Costo y soporte

En la documentación oficial que revisamos no aparece ninguna tarifa por integrar estos mecanismos. Confírmalo con la AGETIC antes de presupuestar. El soporte de Ciudadanía Digital atiende en soporte@agetic.gob.bo, por WhatsApp al +591 63124081 y por teléfono al (2) 2184026, según el portal developer.