This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Documentation

1 - OpenID Connect

Un “lightweight framework” para interacciones de Identidad

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 raises 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, revoluciono la autenticacion web. Brad Fitzpatrick, fundador de LiveJournal, indico. 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! incorporo soporte para OpenID en Enero del 2008, MySpace anuncio 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 tú 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. Ahi deberás autenticarte y aprobar el requerimiento de atributos echo por él 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 the eso, él OpenID provider no vuelve a consultar por credenciales, sino que utiliza la session creada previamente. Esta session 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 pa 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"
}
Atributo Descripcion
iss Identifica al emisor del token en formato HTTPS sin ningún parametro o fragmentos.
sub El identificador local del usuario en el OpenID provider.
aud La audiencia del token, Puede ser una lista de identificadores, pero debe contener el OAuth client ID en el; de otra forma el client ID debe ser agregado al parametro azp
nonce Un nuevo parametro que introduce la especificación OpenID Connect al authorization flow. EN adición a los parametros definidos por OAuth 2.0, la aplicacion cliente puede opcionalmente incluir el parametro nonce. Este parametro permite mitigar ataques de “replay”. El servidor de autorización debe rechazar cualquier request si encuentra que dos o mas request con el mismo nonce. Si un nonce esta presente el el request de autenticacion, entonces el servidor de autenticacion debe incluir el mismo valor dentro del ID token. La aplicacion cliente debe validar que el valor de nonce devuelto por el servidor sea el mismo que se envió originalmente.
exp El tiempo de expiración del token en segundos desde 1970-01-01T0:0:0Z (UTC), Unix Epoch.
iat El tiempo de emisión del token en segundos desde 1970-01-01T0:0:0Z (UTC), Unix Epoch.
auth_time El momento en el cual el usuario es autenticado por el OpenID provider. Si el usuario estaba previamente autenticado, entonces el OpenID provider no pedira autenticacion por parte del usuario. Como un OpenID provider maneja la session o el mecanismo de autenticacion esta fuera del alcance de la especificación OpenID Connect. Un usuario podria crear una session entrando a un sitio web diferente a la aplicacion cliente. En ese caso, el OpenID provider debe mantener el tiempo de autenticacion original. Este es el valor de auth_time.
acr Authentication Context Reference o acr. El valor de este parametro debe ser comprendido tanto por la aplicacion cliente como el proveedor de autenticacion. Solicita un nivel de autenticacion para el request.
amr Authentication Method References p amr, Indica como fue autenticado el usuario por el provedor de identidad. Puede ser un array de valores. Tanto la aplicacion cliente como el proveedor de autenticacion deben comprender estos valores.
azp Authorized Party o azp, Es necesario cuando existe una audiencia (aud) y su valor es diferente al OAuth client ID. El valor de azp debe ser el OAuth client ID.

1.4 - Authorization Request

curl --location --request GET 'https://accounts.autentiaplus.id/oauth2/auth? \
      response_type=code&
      scope=openid&
      client_id=EA71B8972236997FDA75D62E41ED6&
      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'


Atributo Descripcion Tipo Requerido
response_type El tipo de token que espera el cliente obtener string *
scope Los scopes o permisos que el cliente requiere del usuario string *
client_id Identificador de la aplicacion cliente string *
redirect_uri URL Publica SSL, donde la aplicacion cliente espera recivir el resultado del flujo string *
response_mode Determina como el authorization server envia los parametros de respuesta string
nonce Mitiga replay attacks. El authorizationserver rechaza cualquier requerimiento si encuentra que dos de ellos contienen el mismo nonce string *pkce
state Mitiga CSRF attacks. El authorizationserver exige este parametro para flujos PKCE string *pkce
display Indica como la aplicacion cliente espera que el authorization server despliegue la pagina de login y consent string
prompt Indica si el cliente requiere desplegar la pagina de login, de consent, ambas o ninguna string
max_age Define la maxima antiguedad que una session anterior podria tener para ser reutilizada string
ui_locales Expresa la localizacion requerida por el cliente string
id_token_hint Un ID Token obtenido previamente por la aplicacion cliente string
login_hint Indica el username que la aplicacion cliente espera autenticar string
acr_values authentication context reference values indica el nivel de autenticacion requerida por el cliente string

1.5 - Scope

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

Scope Claims Requerido
openid Retorna el claim sub, el cual identifica de forma unica al usuario. Adicionalmente, se entregan default claims. ver ID Token *
birthdate Retorna el claim birthdate
profile Retorna el claim profile, birthdate, picture
credential Retorna el claim credential. ver Credential
email Retorna el claim email y email_verified
phone Retorna el claim phone_number y phone_number_verified
offline_access Retorna refresh token

1.6 - Credential

Credential Payload

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

1.7 - Authentication Context Reference

Strategy ACR’s

Valor Descripcion Alias Locales
urn:acr:default Verificacion numero de documento autoidentify es_CL
urn:acr:password Verificacion de password password *
urn:acr:facial:live Verificacion facial CON prueba de vida facial es_CL, es_PE
urn:acr:facial:simple Verificacion facial SIN prueba de vida facialself es_CL, es_PE
urn:acr:facial:live?=sample=true Verificacion facial CON prueba de vida + muestra facial es_CL, es_PE
urn:acr:facial:simple?=sample=true Verificacion facial SIN prueba de vida + muestra facialself es_CL, es_PE
urn:acr:facial:live?=sample=false Verificacion facial CON prueba de vida facial es_CL, es_PE
urn:acr:facial:simple?=sample=false Verificacion facial SIN prueba de vida facialself es_CL, es_PE
urn:acr:finger:reader Verificacion dactilar con lector es_CL, es_PE
urn:acr:finger:picture Verificacion dactilar con camara es_CL, es_PE
urn:acr:finger:reader?=sample=true Verificacion dactilar con lector + muestra es_CL, es_PE
urn:acr:finger:picture?=sample=true Verificacion dactilar con camara + muestra es_CL, es_PE
urn:acr:finger:reader?=sample=false Verificacion dactilar con lector es_CL, es_PE
urn:acr:finger:picture?=sample=false Verificacion dactilar con camara es_CL, es_PE

2FA ACR

Valor
urn:acr:otp:email
urn:acr:otp:phone
urn:acr:otp:email?=recipient=foo@bar.com
urn:acr:otp:phone?=recipient=+56911111111

2 - Movil

SDK Android para interacciones de Identidad

2.1 - SDK

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. La finalidad de este producto como SDK es que pueda ser integrable dentro de la APK de nuestros clientes.

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:0.0.5@aar') { transitive = true }

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 {
        maven {
		    url "https://artifacts.autentia.io/repository/maven-releases/"  
		    credentials {  
		        username "YOUR_USERNAME"  
			    password "YOUR_PASSWORD"  
		    }  
	    } 
	    maven { url 'https://maven.microblink.com' }
        google()
        jcenter()
	    ...
	}
}

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.

YOUR_USERNAME: Nombre de usuario de maven

YOUR_PASSWORD: Contraseña del usuario de maven

Requisitos

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

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

Implementación

Ambos métodos 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:

Código Valor Descripción
399 h_plus_otp_error El OTP es inválido
398 h_plus_cancel_permission El usuario canceló los permisos de la aplicación y aseguró que no quería darle permisos (hay un diálogo de confirmación)
397 h_plus_unexpected_error Error no previsto por el SDK