Documentation

1 - OpenID Connect

1.1 - Historia

OpenID Connect fue ratificado como estándar por sus miembros el 26 de Febrero del 2014. OpenID Connect provee un framework de identidad para interacciones RESTful. Fue desarrollado bajo el alero de OpenID Foundation y tiene sus raíces en OpenID, pero fue influido en gran medida por OAuth 2.0.

El anuncio emitido por la OpenID Foundation referente al lanzamiento del estándar OpenID Connect está disponible en aquí

OpenID, quien sigue los pasos de SAML en 2005, revolucionó la autenticación web. Brad Fitzpatrick, fundador de LiveJournal, indicó. El principio básico tras ambos OpenID y SAML, son los mismos. Ambos pueden ser utilizados para facilitar single sign-on (SSO) y cross-domain identity federation. OpenID mantiene una mayor comunidad, centra mejor al usuario y es descentralizado. Yahoo! incorporó soporte para OpenID en Enero del 2008, MySpace anunció soporte para Julio de ese mismo año, Google uniéndose en Octubre. Para diciembre del 2009, hay más de 1 billon de cuentas de usuario OpenID-Enabled. Fue un tremendo éxito como protocolo SSO Web.

1.2 - Inicio Rápido

¿Cuántos perfiles mantienes hoy en diferentes sitios web?. Quizás tienes una cuenta Yahoo!, una en Facebook, otra en Google, etc. Cada vez que se actualiza un dato personal, teléfono o dirección, tienes que actualizarlo en cada lugar o mantener datos desactualizados. OpenID soluciona este problema de datos de perfil distribuidos por diferentes proveedores. Con OpenID, mantienes tu perfil solamente en tu OpenID provider. Y todos los otros sitios se transforman en OpenID relying parties. Estos “hablan” con tu proveedor OpenID para obtener tu información de perfil.

Cada vez que intentes entrar a un sitio web OpenID relying party; serás redireccionado al OpenID provider. Ahí deberás autenticarte y aprobar el requerimiento de atributos hecho por el relying party. Al aprobar, eres redireccionado de vuelta al sitio del relying party con los atributos del request.

Con SSO, solamente autentificas en el proveedor OpenID. Esto siendo, un relying party te redirecciona por primera vez. Luego de eso, el OpenID provider no vuelve a consultar por credenciales, sino que utiliza la sesión creada previamente. Esta sesión autenticada es mantenida ya sea por una cookie hasta que el browser sea cerrado, o por una cookie persistente.

sequenceDiagram;
    participant Usuario
    participant Relying Party
    participant OpenID Provider
    Usuario->>+Relying Party: Intento de Login
    Relying Party-->>-Usuario: Login link
    Usuario->>Usuario: Click link
    alt auth flow
        Usuario->>+OpenID Provider: Login request
        OpenID Provider-->>-Usuario: Render toma de evidencias
        Usuario->>+OpenID Provider: Proporciona evidencias
    end
    alt consent flow
        OpenID Provider-->>-Usuario: Render toma consentimientos
        Usuario->>+OpenID Provider: Proporciona consentimientos
    end
    OpenID Provider-->>-Usuario: 302 callback url
    Usuario->>Usuario: resuelve 302
    Usuario->>Relying Party: Entrega code
    Relying Party->>OpenID Provider: Intercambio code por tokens
    OpenID Provider->>Relying Party: AccessToken y/o idToken

1.3 - ID Token

El ID Token es la principal adición a OAuth2 que realiza OpenID Connect. Es un JSON web token JWT que transporta información relevante al usuario autenticado desde el servidor de autorización (OpenID provider) hacia la aplicacion cliente (OpenID relaying party). La estructura de un ID Token es definida por la especificación OpenID Connect. A continuación un ejemplo de ID Token:

StandardClaims

{
    "iss": "https://accounts.autentiaplus.id/",
    "sub": "d733edad-4d05-402a-9b66-090b06d40f7a",
    "name": "Luis Ignacio Cisternas Rojas",
    "given_name": "Luis Ignacio",
    "family_name": "Cisternas Rojas",
    "gender": "male",
    "updated_at": 1604416603,
    "aud": "67jjuyuy7JHk12",
    "nonce": "88797jgjg32323",
    "exp": "1416283970",
    "iat": "1416283970",
    "auth_time": ":1311280969",
    "acr": "urn:acr:password",
    "amr": "password",
    "azp": "67jjuyuy7JHk12"
}

1.4 - Authorization Request

curl --location --request GET 'https://accounts.autentiaplus.id/oauth2/auth? \
      response_type=code&
      scope=openid&
      client_id=eacd29ca-1bcf-418d-8b39-63c22b75bcf7
      redirect_uri=https://localhost:3000/callback&
      response_mode=query&
      nonce=aXK2rXuApo&
      state=8KHUzRUxtZ&
      display=page&
      prompt=login&
      max_age=24h&
      ui_locales=es-CL&
      id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c&
      login_hint=16182517-4&
      acr_values=urn:acr:facial'

1.5 - Scope

(StandardClaims)[https://openid.net/specs/openid-connect-basic-1_0.html#StandardClaims]

1.6 - Credential

Credential Payload

{
  "sub": "16182517-4",
  "country": "CHL",
  "typ": "rut",
  "iss": "srcei"
}

1.7 - Authentication Context Reference

Strategy ACR’s

2FA ACR

1.8 - Librerías

Movil

• AppAuth Android
• AppAuth iOS

Frontend

• AppAuth JS
• OpenID TypeScript
• AngularOIDC

Backend

• GO-OIDC
• Caos OIDC
• SpringBoot
• PyOIDC
• Apache MOD
• Ruby OpenIDConnect
• phpOIDC

2 - Movil

2.1 - SDK

Bienvenido a AutentiaSDK

El SDK de Autentia contiene varias funcionalidades, las cuales serán descritas en el contenido de éste documento.

Tabla de contenido

1. Integración
2. Credenciales
3. Requisitos
4. H+
5. Parámetros
6. Resultados

Integración

Siga las siguientes instrucciones para el correcto uso del SDK:

1. Abrir el archivo build.gradle a nivel de aplicación.
2. Ubicar zona de dependencies.
3. Agregar la siguiente línea de comando.

implementation('id.autentiaplus:sdk:x.y.z')

Luego, para agregar las dependencias de maven al proyecto sigue los siguientes pasos

1. Abrir el archivo build.gradle a nivel de proyecto.
2. Ubicar la zona de repositorios.
3. Agregar las siguientes líneas de código.

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "https://gitlab.endpoints.autentiax-ctl.cloud.goog/api/v4/projects/251/packages/maven"
            name "Autentia SDK"
            credentials(HttpHeaderCredentials) {
                name = 'Private-Token'
                value = '<<TOKEN_VALUE>>'
            }
            authentication {
                header(HttpHeaderAuthentication)
            }
        }
        maven { url 'https://maven.microblink.com' }
    }
}

Credenciales

Para poder descargar y utilizar el SDK es necesario colocar las credenciales como aparece en el ejemplo anterior.

Debe solicitar las credenciales a su ejecutivo de ventas o jefe de proyecto asignado.

Requisitos

El SDK requiere que el API mínimo de Android sea 25, como se muestra en la pantalla.

android {
        ...
        defaultConfig {
            minSdkVersion 25
            ...
        }
    ...
}

Autentia H+

Descripción

H+ tiene la funcionalidad de poder validar a una persona mediante sus huellas digitales. Con una foto que captura la huella dactilar es posible verificar que una persona sea quien dice ser.

Implementación

Ésta funcionalidad consta de 2 métodos, los cuales iniciarán el flujo H+, la diferencia es la siguiente:

El Método 1 requerirá escribir el OTP_MOVIL mediante una interfaz de usuario ya sea de manera manual o mediante lectura de un código QR.

El Método 2 no lo solicitará, ya que asumirá que viene en la llamada y ejecutará este paso automáticamente.

Método 1 - Kotlin

SdkManager(this).hPlusCaller(REQUEST_CODE)

Método 2 - Kotlin

SdkManager(this).hPlusCaller(OTP_MOVIL,REQUEST_CODE)

Parámetros

OTP_MOVIL: Código numérico de 6 dígitos en formato String.

REQUEST_CODE: Código asignado por el usuario en formato Int para obtener la respuesta de H+ en el método onActivityResult.

Resultados

Para obtener los resultados de H+, se utiliza el método

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {  
    super.onActivityResult(requestCode, resultCode, data)  
    if(requestCode == REQUEST_CODE){  
        when (resultCode){  
            Activity.RESULT_OK -> {  
                if(data!=null){  
                    if(data.hasExtra("autentia_sdk_error")){  
                        val sdk_error = data.getStringExtra("autentia_sdk_error")
                        //do something with sdk_error  
                    }  
                    if(data.hasExtra("h_plus_response")){  
                        val sdk_response = data.getBooleanExtra("h_plus_response",false)  
                        //do something with sdk_response 
                    }
                    if(data.hasExtra("autentia_sdk_code")){  
                        val sdk_code = data.getIntExtra("autentia_sdk_code",-1)
                        //do something with sdk_code 
                    }  
                }  
            }  
            Activity.RESULT_CANCELED -> {  
                 //do something with result
            }  
        }  
    }  
}

Posibles respuestas de RESULT_OK

Este resultado se da cuando el SDK termina el flujo completo de manera natural.

autentia_sdk_error: Nombre del error tipo String.

autentia_sdk_code: Código del error ocurrido, tipo Int.

h_plus_response: Indica si la verificación fue exitosa o no, tipo boolean.

Cuando el resultado es exitoso, autentia_sdk_code tendrá valor 0 y h_plus_response puede tomar valor true o false.

El valor true se retorna cuando la validación de identificación fue exitosa.

El valor false se retorna cuando la validación de identificación fue fallida.

Posibles respuestas de RESULT_CANCELED

Este resultado se da cuando el SDK no termina el flujo completo de manera natural, ya que el usuario canceló o cerró el flujo invocado.

H+ maneja los errores de la siguiente manera:

Flujos Registro sin huella dactilar

Descripción

Los flujos de registro son los que tienen la capacidad de registrar usuarios en nuestras bases de datos, utilizando el hardware del dispositivo Android.

Para la captura de los documentos del usuario, Autentia SDK integra dos APIs de lectura de documentos, una nuestra, llamada AUTENTIA API y la otra de MICROBLINK, llamada MICROBLINK API, para ésta última es necesario una llave productiva del producto.

Implementación

Ésta funcionalidad cuenta con dos métodos, los cuales inicializan los flujos de registro, la diferencia de éstos son las siguientes:

El Método 1 debe ser utilizado con AUTENTIA API, para ésto el parámetro APIDEFAULT debe llevar el nombre corespondiente a autentia_api.

El Método 2 debe ser utilizado con MICROBLINK API, para ésto el parámetro APIDEFAULT debe llevar el nombre corespondiente a microblink_api y además el parámetro APYKEY debe ser enviado con la Key de Microblink.

Método 1 - Kotlin

SdkManager(this).docIntentCaller(APIDEFAULT,REQUEST_CODE)

Método 2 - Kotlin

SdkManager(this).docIntentCaller(APIDEFAULT,APIKEY,REQUEST_CODE)

Parámetros

APIDEFAULT: String correspondiente a la api de lectura de documentos que se quiera utilizar, debe tener uno de los siguientes valores : autentia_api o microblink_api

APIKEY: String correspondiente a la llave otorgada por microblink.

REQUEST_CODE: Código asignado por el usuario en formato Int para obtener la respuesta del proceso en el método onActivityResult.

Resultados

Para obtener los resultados del registro de documentos, se utiliza el método onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {  
    super.onActivityResult(requestCode, resultCode, data)  
    if(requestCode == REQUEST_CODE){  
        when (resultCode){  
            Activity.RESULT_OK -> {  
                if(data!=null){  
                    if(data.hasExtra("autentia_sdk_error")){  
                        val sdk_error = data.getStringExtra("autentia_sdk_error")
                        //do something with sdk_error  
                    }                      
                    if(data.hasExtra("autentia_sdk_code")){  
                        val sdk_code = data.getIntExtra("autentia_sdk_code",-1)
                        //do something with sdk_code 
                    }
                    if(data.hasExtra("autentia_token")){
	                    val registry_token = data.getStringExtra("autentia_token")
	                    //do something with registry_token
	                }
                }  
            }  
            Activity.RESULT_CANCELED -> {  
                 //do something with result
            }  
        }  
    }  
}

Posibles respuestas de RESULT_OK

Este resultado se da cuando el SDK termina el flujo completo de manera natural.

autentia_sdk_error: Nombre del error tipo String.

autentia_sdk_code: Código del error ocurrido, tipo Int.

autentia_token: Es un token de registro, devuelto solo en finalización del flujo de registro y se utiliza en caso de que se quiera continuar con un flujo de Login (VER SECCIÓN XXXXXXXXXXXX).

Cuando el resultado es exitoso, autentia_sdk_code tendrá valor 0 y autentia_token contendrá un denominado token de registro, el cuál sirve para realizar un login con nuestros servicios (VER SECCIÓN XXXXXXX).

Posibles respuestas de RESULT_CANCELED

Este resultado se da cuando el SDK no termina el flujo completo de manera natural, ya que el usuario canceló o cerró el flujo invocado.

Tabla de Errores flujos de registro.

Errores Microblink:

Errores Generales:

Flujos Registro con huella dactilar

Descripción

Los flujos de registro con huella dactilar son los que tienen la capacidad de registrar usuarios en nuestras bases de datos, utilizando el hardware del dispositivo Android y dispositivos biométricos.

Para la captura de los documentos del usuario, Autentia SDK integra dos APIs de lectura de documentos, una nuestra, llamada AUTENTIA API y la otra de MICROBLINK, llamada MICROBLINK API, para ésta última es necesario una llave productiva del producto.

Para la captura de las huellas dactilares, es necesario utilizar uno de los huellero Eikon o UareU (DETERMINAR LOS MODELOS Y DEMASES***************).**

Para algunos flujos es necesario que el dispositivo tenga NFC

Implementación

Ésta funcionalidad cuenta con dos métodos, los cuales inicializan los flujos de registro, la diferencia de éstos son las siguientes:

El Método 1 debe ser utilizado con AUTENTIA API, para ésto el parámetro APIDEFAULT debe llevar el nombre corespondiente a autentia_api.

El Método 2 debe ser utilizado con MICROBLINK API, para ésto el parámetro APIDEFAULT debe llevar el nombre corespondiente a microblink_api y además el parámetro APYKEY debe ser enviado con la Key de Microblink.

Método 1 - Kotlin

SdkManager(this).fingerIntentCaller(APIDEFAULT,REQUEST_CODE)

Método 2 - Kotlin

SdkManager(this).fingerIntentCaller(APIDEFAULT,APIKEY,REQUEST_CODE)

Parámetros

APIDEFAULT: String correspondiente a la api de lectura de documentos que se quiera utilizar, debe tener uno de los siguientes valores : autentia_api o microblink_api

APIKEY: String correspondiente a la llave otorgada por microblink.

REQUEST_CODE: Código asignado por el usuario en formato Int para obtener la respuesta del proceso en el método onActivityResult.

Resultados

Para obtener los resultados del registro de documentos, se utiliza el método onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {  
    super.onActivityResult(requestCode, resultCode, data)  
    if(requestCode == REQUEST_CODE){  
        when (resultCode){  
            Activity.RESULT_OK -> {  
                if(data!=null){  
                    if(data.hasExtra("autentia_sdk_error")){  
                        val sdk_error = data.getStringExtra("autentia_sdk_error")
                        //do something with sdk_error  
                    }                      
                    if(data.hasExtra("autentia_sdk_code")){  
                        val sdk_code = data.getIntExtra("autentia_sdk_code",-1)
                        //do something with sdk_code 
                    }
                    if(data.hasExtra("autentia_token")){
	                    val registry_token = data.getStringExtra("autentia_token")
	                    //do something with registry_token
	                }
                }  
            }  
            Activity.RESULT_CANCELED -> {  
                 //do something with result
            }  
        }  
    }  
}

Posibles respuestas de RESULT_OK

Este resultado se da cuando el SDK termina el flujo completo de manera natural.

autentia_sdk_error: Nombre del error tipo String.

autentia_sdk_code: Código del error ocurrido, tipo Int.

autentia_token: Es un token de registro, devuelto solo en finalización del flujo de registro y se utiliza en caso de que se quiera continuar con un flujo de Login (VER SECCIÓN XXXXXXXXXXXX).

Cuando el resultado es exitoso, autentia_sdk_code tendrá valor 0 y autentia_token contendrá un denominado token de registro, el cuál sirve para realizar un login con nuestros servicios (VER SECCIÓN XXXXXXX).

Posibles respuestas de RESULT_CANCELED

Este resultado se da cuando el SDK no termina el flujo completo de manera natural, ya que el usuario canceló o cerró el flujo invocado.

Tabla de Errores flujos de registro.

Errores Microblink:

Errores Generales:

Flujos Login Autentia SDK

Descripción

Los flujos de Login de Autentia SDK fueron creados para facilitar la integración de nuestros clientes con el Login de Autentia ID, facilitando la toma de evidencias y la comunicación del usuario desde aplicaciones móviles con nuestros servicios.

Para la captura de los documentos sólo está disponible la api AUTENTIA API, MICROBLINK API no está disponible para ésta funcionalidad.

Se asume que el integrador ha cumplido con todos los pre-requisitos necesarios para el funcionamiento de éste flujo. (VÉASE AQUÍ LOS REQUISITOS+++++++++++++++++++++++++++++++++++++)

Implementación

Ésta funcionalidad cuenta con dos métodos, los cuales inicializan los flujos de registro, la diferencia de éstos son las siguientes:

El Método 1 asume que no se recibirá la URL de Concent Flow, sino que la abre directamente después de terminar el proceso de Autorización.

El Método 2 recibe un parámetro extra RETURN_CONCENT_URL, en el cuál se configura explícitamente qué hacer con la URL de Concent Flow.

Método 1 - Kotlin

SdkManager(this).sendLoginChallenge(LOGIN_CHALLENGE,REQUEST_CODE)

Método 2 - Kotlin

SdkManager(this).sendLoginChallenge(LOGIN_CHALLENGE,RETURN_CONCENT_URL,APIKEY,REQUEST_CODE)

Parámetros

LOGIN_CHALLENGE: String correspondiente al Login Challenge recibido por la aplicación cliente al momento de comenzar un Login Flow. (se recibe a través de deep link pre-configurado.)

RETURN_CONCENT_URL: String correspondiente a la URL del ConcentFlow. ésta debe ser desplegada en un navegador para realizar el flujo de Concent.

REQUEST_CODE: Código asignado por el usuario en formato Int para obtener la respuesta del proceso en el método onActivityResult.

Resultados

Para obtener los resultados del registro de documentos, se utiliza el método onActivityResult:

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {  
    super.onActivityResult(requestCode, resultCode, data)  
    if(requestCode == REQUEST_CODE){  
        when (resultCode){  
            Activity.RESULT_OK -> {  
                if(data!=null){  
                    if(data.hasExtra("autentia_sdk_error")){  
                        val sdk_error = data.getStringExtra("autentia_sdk_error")
                        //do something with sdk_error  
                    }                      
                    if(data.hasExtra("autentia_sdk_code")){  
                        val sdk_code = data.getIntExtra("autentia_sdk_code",-1)
                        //do something with sdk_code 
                    }
                    if(data.hasExtra("autentia_concent_url")){
	                    val concent_url = data.getStringExtra("autentia_concent_url")
	                    //do something with autentia_concent_url
	                }
                }  
            }  
            Activity.RESULT_CANCELED -> {  
                 //do something with result
            }  
        }  
    }  
}

Posibles respuestas de RESULT_OK

Este resultado se da cuando el SDK termina el flujo completo de manera natural.

autentia_sdk_error: Nombre del error tipo String.

autentia_sdk_code: Código del error ocurrido, tipo Int.

autentia_concent_url: Es la URL del registro en formato STRING, debe ser desplegada en el navegador para continuar el flujo de Concent.

Cuando el resultado es exitoso, autentia_sdk_code tendrá valor 0 y dependiendo de si se solicitó el retorno de la Url de concent, ésta volverá en autentia_concent_url.

Sino se solicitó el retorno de la Url de Concent, Autentia SDK abrirá un navegador y comenzará automáticamente el Flujo de Concent.

Posibles respuestas de RESULT_CANCELED

Este resultado se da cuando el SDK no termina el flujo completo de manera natural, ya que el usuario canceló o cerró el flujo invocado.

Tabla de Errores flujos de registro.

Errores Flujo Login:

Errores Generales: