Submenu desarrolladores

  1. Desarrollador

API REST de Autenticación

A continuación se especifica la interfaz del servicio de Autenticación de tuidd.

El servicio se llama tuidd Log-in, y es una herramienta basada en el estándar OAuth2 OpenID.

 

Discovery

ENDPOINT DE DISCOVERY

Este endpoint devuelve las URLs de los endpoints para consumir el resto de los servicios de tuidd, de acuerdo al número de línea, el país o localidad, y el operador telefónico al cual pertenezca la línea.

Tiene el siguiente formato:

POST /{discovery_endpoint}

Ejemplo:

POST /https://idgw.tuidd.com/discovery

 

Requerimiento

Headers

Authentication: Basic base64(<client_id>:<client_secret>)

Content-type: application/x-www-form-urlencoded

Nota : El client_id y client_secret son los recibidos al momento del registro de la aplicación en la plataforma de gestión.

 

Body

Campo

Tipo

Requerido

Descripción

Redirect_URL

String

Obligatorio

URL que se configuró al registrar la aplicación en la plataforma de administración.

Ejemplo: http://myapp.com/callback

MSISDN

String

Opcional

Número de línea del usuario en formato E.164.

Ejemplo: +541199993333

 

Respuesta 200

Header

Content-Type: application/json

Body

Campo

Tipo

Requerido

Descripción

ttl

Int

Obligatorio

Tiempo de vida de la validez de la respuesta en formato Unix Timestamp.

subscriber_id

String

Opcional

Número de línea del usuario, cifrado con la llave. Puede ser utilizado en el parámetro login_hint de la autenticación.

response

JSON

Obligatorio

Información de la respuesta

 

response

Campo

Tipo

Requerido

Descripción

client_id

String

Opcional

Es el identificador de la aplicación. De ser utilizado para el resto de los servicios de autenticación y servicios adicionales. Atención! Por cuestiones de seguridad, puede ser diferente del utilizado en los parámetros del requerimiento de Discovery.

client_secret

String

Opcional

Es la clave secreta que debe utilizarse para consumir el resto de los servicios. Atención! Por cuestiones de seguridad, puede ser diferente del utilizado en los parámetros del requerimiento de Discovery.

serving_operator

String

Opcional

Nombre del operador (MNO)

country

String

Obligatorio

Código del país de donde es la línea en formato ISO 3166-1 alfa-2.

 Ejemplo: US

currency

String

Obligatorio

Código de la moneda con la que opera en formato ISO 4217 alfa-3.

Ejemplo: USD

client_name

String

Obligatorio

Nombre de la aplicación registrada en la plataforma de gestión.

apis

JSON

Obligatorio

Información sobre los endpoints de servicios.

apis  

Campo

Tipo

Requerido

Descripción

operator_id

JSON

Obligatorio

Contiene un listado de links.

operator_id  

Campo

Tipo

Requerido

Descripción

links

JSON

Obligatorio

Contiene la información con las URLs de los enpoints de los servicios de tuidd.

links  

Campo

Tipo

Requerido

Descripción

rel

String

Obligatorio

Es una descripción de referencia del tipo de endpoint.

Los valores a recibir son:

authorization : endpoint del servicio de Autenticación.

token : endpoint del servicio de obtención de tokens.

userinfo : endpoint del servicio de obtención de los datos del usuario.

tuidd_service : endpoint de los servicios adicionales de tuidd

href

String

Obligatorio

URI del endpoint del servicio.  

 

Ejemplo:  

 

  "subscriber_id": null,

  "ttl": 1488452073,

  "response":

    "serving_operator": "Example Operator B",

    "client_secret": "YWIyNmQyYmQtMDMxMi00MTg4LWJjMDgtYTUyN322...",

    "country": "US",

    "apis":

      "operatorid":

        "link":

          {

            "rel": "authorization",

            "href": "https://idgw-operator-b.tuidd.com/authorize"

          },

          {

            "rel": "token",

            "href": "https://idgw-operator-b.tuidd.com/accesstoken"

          },

          {

            "rel": "userinfo",

            "href": "https://idgw-operator-b.tuidd.com/userinfo"

          },         

          {

            "rel": "tuidd_service",

            "href": "https://idgw-operator-b.tuidd.com/service"

          }

        ]

      }

    },

    "currency": "USD",

    "client_name": "TestApp",

     "client_id": "MDQ4MTZmMWYtOTAwMi00YjczLTkyNDAtZWQ2YjZhNWZhY..."

  }

}

 

Respuestas 400, 401, 404

Body  

Atributo

Tipo

Requerido

Descripción

error

String

Obligatorio

Código de error.

description

String

Obligatorio

Descripción del error.

 

 

Autenticación

ENDPOINT DE AUTORIZACIÓN  

Este endpoint devuelve un código de autorización de parte del usuario final que tiene dos objetivos:

   -  Autenticar al usuario

   -  Obtener los consentimientos y accesos de su parte, para obtener información u otorgarle los diferentes servicios.

Tiene el siguiente formato:  

GET /{endpoint_auth}
/{?client_id,client_name,response_type,scope,acr_values,state,nonce,display}

Ejemplo: 

GET /https://idgw.tuidd.com/auth/?client_id=73958620&
      client_name=test_app2&response_type=code&scope=openid mc_authn&
      acr_values=3 2&state=3a1d38b1&nonce=cee18fcb&display=page

 

Parámetros de la URI  

Campo

Tipo

Requerido

Descripción

endpoint_tuidd

String

Obligatorio

Es la URL del servicio de autenticación de la plataforma tuidd.

Ejemplo: https://idgw.tuidd.com/auth/

client_id

String

Obligatorio

Ese el ID de la aplicación recibido del servicio de Discovery.

Ejemplo: 73958620d779-4fdc-bc09-7d521af91278

response_type

String

Obligatorio

El valor debe ser code obligatoriamente, para indicar que se requiere un código de autenticación. También indica que el “access_token” (y “id_token”) que se retorne deberá ser intercambiado por este código.

Ejemplo: code

scope

String

Obligatorio

L ista de strings ASCII “case-sensitive” con valores de “scope” del estándar OAuth 2.0. Según el estándar debe contener el valor “openid”. Otros valores posibles son: profile , email , address ,  phone ,  offline_access .

Además se pueden colocar los “scope” de servicios adicionales: tuidd_notification , tuidd_advertising , tuidd_survey , tuidd_payment , tuidd_coupon .

Ejemplo: openid profile advertising

Ver más abajo información más detallada de este parámetro.

redirect_uri

String

Obligatorio

La URI de redirect que se especificó al registrar la aplicación en tuidd. La respuesta de este servicio sera redirigida a esta URI.

Ejemplo:

https://Ejemplo.com/sign_in_callback

acr_values

String

Obligatorio

Son los valores de LOAs requeridos por la aplicación, en orden de preferencia, de acuerdo a la norma ISO/IEC 29115 Clause 6 – 1 , 2 , 3 , 4 – representando los niveles LOW, MEDIUM, HIGH y VERY HIGH. Tener en cuenta que tuidd actualmente sólo soporta los valores 2 y 3. El valor finalmente utilizado es devuelto en el campo “acr” en la autenticación.

Ejemplo: 3 2

state

String

Obligatorio

Es un valor indicado por el proveedor para mantener una correspondencia entre el requerimiento y la respuesta. Si se vincula con la cookie del navegador, también puede ser usado como mecanismo de seguridad para prevenir Cross-Site Request Forgery.

Ejemplo: 3a1d38b154bc-4383-bfc9-a6926fc2644b

nonce

String

Obligatorio

String usado para asociar la sesión del cliente con el ID Token. Debe ser pasado sin modificación desde el request de Autorización al ID Token. Debe ser único por sesión para mitigar ataques de replay.

Ejemplo: cee18fcbcb3a-46b9-88ec-6ab79d9d0da0

display

S t r ing

Opciona l

String ASCII que especifica la interfaz de usuario para el flujo de autenticación y autorización. Los valores pueden ser:

  • page : Valor por defecto si no se envía el parámetro “display”. En este caso, la pantalla presentada debe ocupar la pantalla completa del navegador.
  • popup : Debe mostrar una ventana popup de 450px de ancho X 500px de alto.
  • touch : La pantalla debe soportar una interfaz de usuario “touch”.
  • wap : La pantalla debe ser compatible con un dispositivo “feature-phone”.

Ejemplo: page

prompt

String

Opcional

String ASCII case-sensitive, que especifica si el servidor debe pedir o no re-autenticación o consentimiento. Los valores posibles son:

  • none : No debe pedir re-autenticación ni consentimiento de parte del usuario. Si el usuario no fue autenticado previamente, o se necesita re-autenticación o consentimiento, se devuelve un error que indica que el login es requerido. Esto puede ser utilizado como mecanismo para verificar la existencia de autenticación o consentimiento.
  • login : Debe pedir al usuario re-autenticación o consentimiento. Si no se puede hacer, debe retornar un error.
  • consent : Debe mostrar al usuario la pantalla de consentimiento.
  • select_account : Si el usuario tiene varias cuentas, debe pedirle que seleccione una. Si no se puede hacer debe retornar un error.
  • mobile : El requerimiento no debe mostrar ninguna pantalla, y el pedido debe permanecer abierto hasta que se complete la autorización en el dispositivo.

Ejemplo: consent

max_age

In t

Obligatori o

Especifica el tiempo máximo en segundos que dura la autenticación del usuario. Una vez pasado este tiempo, se debe reautenticar. Cuando se usa este parámetro en el request, el ID Token debe contener el valor de “auth time”.

Ejemplo: 300

ui_locales

String

Obligatorio

Lista de strings con los lenguajes soportados por la UI, de acuerdo a la RFC5646, separados por espacio. Este parámetro es sólo una guía, y en caso de que el lenguaje preferido no sea soportado por el servidor, no debe devolverse ningún error.

Ejemplo: es

claims_locales

Strin g

Obligatori o

Lista de string con los lenguajes de los “claims”, según la RFC5646. Este parámetro es sólo una guía, y en caso de que el lenguaje preferido no sea soportado por el servidor, no debe devolverse ningún error.

Ejemplo: es

id_token_hint

String

Condicional

Usado en conjunto con el parámetro prompt=none , y contiene el id_token previamente generado, como indicio para la sesión de autenticación. Si el id_token todavía es válido, y el usuario está conectado, entonces el servidor deberá responder en forma positiva. En caso contrario, se debe responder un error de autenticación. Dentro del id_token incluido en el id_token_hint , el servidor no tiene que estar listado en el campo aud.

Ejemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6…

login_hint

Strin g

Opciona l

Indica al servidor que ID usar para el login. Puede contener el MSISDN, el MSISDN encriptado o un PCR de un ID Token previamente obtenido:

  • MSISDN : Valor del MSISDN completo con "+" y código de país. Por ejemplo: +443523536534.
  • ENCR_MSISDN : Valor obtenido del parámetro subscriber_id en caso de usar la API de Discovery de la GSMA.
  • PCR : Valor del PCR (Pseudo-anonymous Customer Reference) de un proceso de autenticación previamente ejecutado.

Si no se envía, la plataforma le solicitará que ingrese el número de línea o alias para autenticarse.

Ejemplo: ENCR_MSISDN:23153464dsfgh…

dtbs

Strin g

Opciona l

Información que debe ser cifrada por la llave privada del usuario final. La información firmada es devuelta en el id_token , en el atributo dts del JWT, junto con la llave pública para descifrarlo.

Requerimiento

Headers

Authentication: Basic base64(<client_id>:<client_secret>)

Respuesta 302

Headers

Location: <redirect_url>

 

RESPUESTA A LA URL DE REDIRECT

Este endpoint registra los datos que serán enviados a la redirect_uri de la aplicación, luego del éxito o falla del intento de autenticación.

Tiene el siguiente formato:

GET /{redirect_url}{?state,code,error,error_description}

Ejemplo de URI

GET /https:/ejemplo.com/sign_in_callback?state=12324tsfdsdf&code=2d902ae7&error=error_name&error_description=error description

Parámetros de la URI

Campo

Tipo

Requerido

Descripción

state

Strin g

Obligatori o

El string “state” tal cual fue pasado en el requerimiento original.

Ejemplo: 12324tsfdsdf

code

String

Obligatorio

El Código de Autorización de único uso, según OAuth 2.0. El mismo será usado en el parámetro code del requerimiento de Token.

Ejemplo: 2d902ae7

error

String

Obligatorio

Si hubiera un error, aparecería este parámetro, y el parámetro code no.

Ejemplo: invalid_id

error_description

String

Obligatorio

En caso de error, una descripción sobre cuál fue el error.

Ejemplo: El client id es inválido.

 

El parámetro “scope”

Los valores de “scope” actualmente aceptados son:

Valor

Tipo

Requerido

Descripción

openid

Strin g

Obligatorio

Obligatorio según la norma, para indicar que es un pedido de autenticación OpenId. Este scope sólo otorga acceso de autenticación. No otorga acceso a ninguna información o servicio adicional.

profile

String

Opcional

Otorga permiso al proveedor de obtener acceso a los siguientes atributos del usuario: name , family_name , given_name , middle_name , nickname , preferred_username , profile , picture , website , gender , birthdate , zoneinfo , locale , updated_at .

Tener en cuenta que puede ser que no toda la información esté disponible en el perfil del usuario.

email

String

Opcional

Otorga permiso para obtener el email del usuario, y opcionalmente, si el mismo está verificado. Atributos: email , email_verified

address

String

Opcional

Otorga permiso para obtener la dirección del usuario. Atributo: address

phone

String

Opcional

Otorga permiso para obtener el teléfono del usuario. Atributos: phone_number , phone_number_verified

offline_access

String

Opcional

Otorga permiso para user el refresh_token para obtener acceso a UserInfo, en caso de que el usuario no esté logueado al sitio.

tuidd_advertising

String

Opcional

Otorga permiso al proveedor para enviarle avisos publicitarios al usuario, de acuerdo a la cantidad y frecuencia configurada por el mismo.

tuidd_survey

String

Opcional

Otorga permiso al proveedor para enviarle encuestas al usuario, de acuerdo a la cantidad y frecuencia configurada por el mismo.

tuidd_payment

String

Opcional

Otorga permiso al proveedor para enviarle pagos al usuario, de acuerdo a la cantidad y frecuencia configurada por el mismo.

tuidd_coupon

String

Opcional

Otorga permiso al proveedor para enviarle cupones de beneficios al usuario, de acuerdo a la cantidad y frecuencia configurada por el mismo.

 

Se puede solicitar más de un “ scope ” en el requerimiento de autorización, lo que devolverá el conjunto unión de todos los atributos asociados al invocar el UserInfo.

 

Access Token

ENDPOINT DE TOKEN

Luego de hacer un requerimiento exitoso al endpoint de Autorización, y recibir el “code” a través de la redirect_url, este código puede ser intercambiado en el endpoint de Token, por un access_token y un id_token firmado. El id_token contiene además los tokens de acceso a los servicios adicionales de tuidd.

Tiene el siguiente formato:

POST /{op_token_endpoint}

Ejemplo: 

POST /https:/operator.com/oidc/token

Parámetros de la URI

Campo

     

op_token_endpoint

String

Obligatorio

Es el endpoint de Token del operador, que fue devuelto en el proceso de discovery, en el campo   links , con   rel=”token” .

Ejemplo: https://operator.com/oidc/token

 

Requerimiento

Headers

Authentication: Basic base64(<client_id>:<client_secret>)

Content-Type: application/x-www-form-urlencoded

Body

Campo

Tipo

Requerido

Descripción

grant_type

String

Obligatorio

Debe tener el valor “authorization_code”

code

String

Obligatorio

Es el código de autorización recibido en la URL de redirect.

redirect_uri

String

Obligatorio

Usado como mecanismo de seguridad extra. Debe coincidir con la URL de redirect registrada en la plataforma de administración de tuidd. Debe ir en formato URL Encoded.

 

 

Respuesta 200

Body

JSON con los siguientes parámetros:

Campo

Tipo

Requerido

Descripción

access_token

String

Obligatorio

Token de acceso según OAuth 2.0 usado para obtener la información del usuario. Para ello, debe ser enviado en el requerimiento de UserInfo. Puede ser reutilizado para siempre que no expire.

Ejemplo: c333504b-953d-4a2f-b82c-d3584d030f2b

token_type

String

Obligatorio

Debe tener el valor "bearer" según lo definido en la RFC 6749 sección 7.1 y RFC6750.

Ejemplo: bearer

id_token

String

Obligatorio

Es un token adicional usado en OIDC para proveer información de seguridad de sobre la autenticación de el usuario final. Además posee los tokens de los servicios adicionales de tuidd. Este id_token tiene un formato JSON Web Token (JWT). El formato de este id_token y su información están descriptos en la siguiente sección.

Ejemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6…

expires_in

Int

Opcional

Un timestamp Unix que representa cuando el access token dejará de ser válido.

Ejemplo: 1475744978

refresh_token

Stri ng

Opcional

Es el código que se puede usar para obtener un nuevo access_token usando la misma autorización del usuario.

Actualmente no está soportado.

El parámetro id_token

Este parámetro viene en formato JWT (JSON Web Token). Está formado por 3 partes separadas por un punto (“.”)

- La primera parte es el header, que contiene información de cómo está firmado token. Para firmar se puede usar cualquiera de estos algoritmos: HS256, HS512, RS256, RS512.

- La segunda parte contiene todos los atributos con la información en formato JSON. A continuación se describen cada uno de los atributos.

- La tercera parte es la firma. Usando la información del header se puede determinar el algoritmo usado en para la firma. Si el hash de la primera y segunda parte coinciden con la firma, entonces se puede asegurar que el id_token no fue adulterado.

Cada una de estas 3 partes está codificada usando el formato “Base64 URL”. Para más información del formato JWT consultar: http://jwt.io

Los atributos recibidos dentro del id_token son:

Campo

Tipo

Requerido

Descripción

iss

String

Obligatorio

URL del servidor que generó el token.

sub

String

Obligatorio

Es el identificador del usuario para la aplicación que solicitó el token (PCR).

aud

String

Obligatorio

Es el client_id de la aplicación a la cual está dirigido el token.

exp

Int

Obligatorio

Es el timestamp de Unix que representa de expiración del token.

iat

Int

Obligatorio

Es el timestamp de Unix que representa la fecha de creación del token.

auth_time

Int

Obligatorio

Es el timestamp de Unix que representa la fecha en la cual fue realizada la autenticación del usuario.

nonce

String

Obligatorio

String pasado por el proveedor de servicios en el requerimiento de autorización, en el parámetro nonce . Permite asociar el id_token con la sesión y sirve para mitigar ataques de replay.

acr

Int

Obligatorio

“Authentication Context Class Reference”. Es el valor de LOA utilizado en la autenticación.

amr

String

Obligatorio

“Authentication Methods Reference”. Es el nombre o los nombres de los métodos de autenticación utilizados. Estos métodos dependen del operador. Los valores posibles son: OK, DEV_PIN, SIM_PIN, UID_PWD, BIOM, HDR, OTP.

 

azp

String

Condicional

Es el client_id del proveedor de servicios autorizado para usar el token, en caso de que sea diferente del parámetro aud. Si es la misma entidad, entonces este parámetro es opcional.

at_hash

String

Opcional

Es un hash del access_token, codificado en Base64URL. El algoritmo de hash es acor dado al momento del registro de la aplicación.

dts

String

Opcional

Información enviada en el campo dtbs en el requerimiento de autorización, cifrada por la llave privada del usuario final.

upk

String

Opcional

Llave pública del usuario final necesaria para descifrar dts .

dts_time

Int

Opcional

Timestamp de Unix, representando el momento del cifrado de la información en dts .

tuidd_service_tokens

String

Opcional

JSON con la información de los token de servicios adicionales de tuidd, de acuerdo a los permisos solicitados en el scope , en el requerimiento de autorización. Ver a continuación el formato del mismo.

 

El atributo tuidd_service_tokens

Es un JSON con la información de los servicios adicionales de tuidd. El formato depende del tipo de servicio.

Los tokens disponibles son:

- advertising_token

- survey_token

- notification_token

- coupon_token

Cada uno tiene los siguientes atributos:

Campo

Tipo

Requerido

Descripción

token

String

Obligatorio

Valor del token.

exp

Int

Obligatorio

Es el timestamp de Unix que representa de expiración del token.

count

Int

Obligatorio

Cantidad de veces que se puede usar el token, antes de la fecha de expiración.

 

Ejemplo:

{

“ tuidd_service_token ” : {

“ advertising_token ” : {

      “ token ” : “ c333504b-953d-4a2f-b82c-d3584d030f2b ” ,

“ exp ” : “ 1475744978 ” ,

      “ count ” : “ 10 ”

},

“ survey_token ”

      “ token ” : “ 34de514b-657d-7a2a-184a-e344d04567c ” ,

      “ exp ” : “ 1475744932 ” ,

      “ count ” : “ 1 ”

}

}  

 

User Info

ENDPOINT DE USER INFO

User Info permite a la aplicación del proveedor de servicios acceder a la información del usuario final. Qué información puede ser accedida está determinada por el parámetro “ scope ” del requerimiento de autorización original.

El requerimiento tiene el siguiente formato:

POST /{op_userinfo_endpoint}{?token}

Si en el requerimiento de autorización original no se solicitó ninguno de estos “scopes”, el requerimiento de User Info retornará un error (401).

Como en el resto de los endpoints, requiere la autenticación “basic auth” específica del operador.

Ejemplo de URI 

POST /https://idgw.tuidd.com/userinfo?token=d5828439-6ace-4e5c-93ab-d880e8f68d36

Parámetros de la URI

Campo

Tipo

Requerido

Descripción

op_userinfo_endpoint

String

Obligatorio

URL del endpoint de UserInfo, devuelto en el proceso de Discovery., bajo el campo links con rel=”userinfo” 

Ejemplo: https://idgw.tuidd.com/userinfo

token

String

Obligatorio

El access_token recibido del endpoint Token.

Ejemplo: d5828439-6ace-4e5c-93ab-d880e8f68d36

 

Requerimiento

Headers

Authentication: Basic base64(<client_id>:<client_secret>)

Respuesta   200

Body

Atributo

Tipo

Requerido

Descripción

sub

String

Obligatorio

PCR que identifica el usuario en la aplicación

name

String

Opcional

Nombre completo del usuario

given_name

String

Opcional

Primer nombre del usuario

family_name

String

Opcional

Apellido del usuario

middle_name

String

Opcional

Segundo nombre del usuario. Si hubiera un tercero o cuarto irían separados espacio

preferred_username

String

Opcional

Alias del usuario

profile

String

Opcional

URL con la página con la información del perfil del usuario

picture

String

Opcional

URL donde se encuentra la imagen del usuario

website

String

Opcional

URL de una página del usuario, como blog personal o red social.

email

String

Opcional

Email del usuario

email_verified

Boolean

Opcional

Indica TRUE o FALSE si el email está o no chequeado

gender

String

Opcional

Género del usuario. Valores posibles: male, female, other.

birthdate

String

Opcional

Fecha de nacimiento en format YYYY-MM-DD

zoneinfo

String

Opcional

String con la zona horaria del usuario, según: http://www.twinsun.com/tz/tz-link-htm.

locale

String

Opcional

Información del idioma según la RFC5646. El valor son 2 valores alfabéticos en minúsculas para el código de idioma, y 2 valores alfabéticos en mayúsculas para el país, separados por guión.

Ejemplo: en-GB

phone_number

String

Opcional

Número de línea del usuario en format E.164, incluyendo prefijo internacional.

Ejemplo: +541155443322

phone_number_verified

Boolean

Opcional

Indica TRUE o FALSE si el teléfono está o no chequeado

address

JSON

Opcional

JSON con los datos de la dirección del usuario. Ver más abajo.

udpated_at

String

Opcional

Timestamp Unix con la fecha de actualización de la información presentada.

 

El formato del campo address :

Atributo

Tipo

Requerido

Descripción

formatted

String

Opcional

Dirección completa que puede ser mostrada

street_address

String

Opcional

Nombre de la calle, número y número de departamento u oficina.

locality

String

Opcional

Ciudad o localidad

región

String

Opcional

Región, Estado o provincia

postal_code

String

Opcional

Código Postal (ZIP)

country

String

Opcional

Nombre del país

 

Respuesta   401

Body

Atributo

Tipo

Requerido

Descripción

error

String

Obligatorio

Código de error.

error_description

String

Obligatorio

Descripción del error.

 

Ejemplo :

{

  "error": "access_denied",

  "error_description": "the selected scopes do not allow access"

}

 

  • English
  • Portuguese, International

Entity Pager Example