Submenu desarrolladores

Authentication REST API

A interface do serviço de Autenticação tuidd é especificada abaixo.

O serviço é chamado de tuidd Log-in e é uma ferramenta baseada no padrão OAuth2 OpenID.

 

Discovery

ENDPOINT DE DISCOVERY

Esse terminal retorna as URLs dos terminais para consumir o restante dos serviços do tuidd, de acordo com o número da linha, o país ou a localidade e a operadora de telefone à qual a linha pertence.

Tem o seguinte formato:

POST /{ discovery_endpoint }

Exemplo:

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

 

Requisito

Headers

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

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

Nota : O client_id e o client_secret são aqueles recebidos no momento do registro do aplicativo na plataforma de gerenciamento.

 

Corpo

Field

Digite

Obrigatório

Descrição

Redirect_URL

String

Obrigatório

URL que foi configurado ao registrar o aplicativo na plataforma de administração.

Exemplo: http://myapp.com/callback

MSISDN

String

Opcional

Número da linha do usuário no formato E.164.

Exemplo: +541199993333

 

Responder 200

Header

Content-Type: application/json

Corpo

Field

Digite

Obrigatório

Descrição

ttl

Int

Obrigatório

Tempo de vida da validade da resposta no formato Unix Timestamp.

subscriber_id

String

Opcional

Número da linha do usuário, criptografado com a chave. Pode ser usado no parâmetro login_hint de autenticação.

resposta

JSON

Obrigatório

Informação de resposta

 

resposta

Field

Digite

Obrigatório

Descrição

client_id

String

Opcional

É o identificador do aplicativo. Se for usado para o restante dos serviços de autenticação e serviços adicionais. Atenção! Por motivos de segurança, pode ser diferente do usado nos parâmetros do requisito de descoberta.

client_secret

String

Opcional

É a chave secreta que deve ser usada para consumir o restante dos serviços. Atenção! Por motivos de segurança, pode ser diferente do usado nos parâmetros do requisito de descoberta.

serving_operator

String

Opcional

Nome do operador (MNO)

país

String

Obrigatório

Código do país onde a linha está no formato ISO 3166-1 alpha-2.

 Exemplo: EUA

moeda

String

Obrigatório

Códigos da moeda com a qual opera no formato ISO 4217 alpha-3.

Exemplo: USD

client_name

String

Obrigatório

Nome do aplicativo registrado na plataforma de gerenciamento.

apis

JSON

Obrigatório

Informações sobre terminais de serviço.

apis  

Field

Digite

Obrigatório

Descrição

operator_id

JSON

Obrigatório

Ele contém uma lista de links.

operator_id  

Field

Digite

Obrigatório

Descrição

ligações

JSON

Obrigatório

Contém as informações com as URLs dos pontos de acesso dos serviços do tuidd.

ligações  

Field

Digite

Obrigatório

Descrição

rel

String

Obrigatório

É uma descrição de referência do tipo de nó de extremidade.

Os valores a receber são:

autorização : Ponto final do serviço de autenticação.

token : endpoint do serviço de obtenção de token.

userinfo : endpoint do serviço para obter os dados do usuário.

tuidd_service : Endpoint de serviços adicionais da tuidd

href

String

Obrigatório

URI do ponto final do serviço.  

 

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..."

  }

}

 

Respostas 400, 401, 404

Corpo  

Atributo

Digite

Obrigatório

Descrição

engano

String

Obrigatório

Código de erro.

descrição

String

Obrigatório

Descrição do erro.

 

 

Autenticação

ENDPOINT OF AUTHORIZATION  

Esse terminal retorna um código de autorização do usuário final com dois objetivos:

   -  Autentique o usuário

   -  Obtenha os consentimentos e acessos de você, para obter informações ou para conceder-lhe os diferentes serviços.

Tem o seguinte formato:  

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

Exemplo:  

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 do URI  

Field

Digite

Obrigatório

Descrição

endpoint_tuidd

String

Obrigatório

É a URL do serviço de autenticação da plataforma tuidd.

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

client_id

String

Obrigatório

Que o ID do aplicativo recebeu do serviço de descoberta.

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

response_type

String

Obrigatório

O valor deve ser code obrigatório, para indicar que um código de autenticação é necessário. Também indica que o "access_token" (e "id_token") que é retornado deve ser trocado por este código.

Exemplo: código

escopo

String

Obrigatório

L Seqüências de caracteres ASCII - diferencia maiúsculas de minúsculas - com valores de "scope" do padrão OAuth 2.0. De acordo com o padrão, ele deve conter o valor "openid". Outros valores possíveis são: perfil , e-mail , endereço telefone offline_access .

Além disso você pode colocar o scope de serviços adicionais: tuidd_notification , tuidd_advertising , tuidd_survey , tuidd_payment , tuidd_coupon .

Exemplo: publicidade de perfil openid

Veja informações mais detalhadas sobre este parâmetro abaixo.

redirect_uri

String

Obrigatório

O URI de redirecionamento especificado ao registrar o aplicativo no tuidd. A resposta deste serviço será redirecionada para este URI.

Exemplo: https://example.com/sign_in_callback

acr_values

String

Obrigatório

Os valores de LOAs exigidos pela aplicação, em ordem de preferência, de acordo com a ISO / IEC 29115 Cláusula 6 1 , 2 , 3 , 4 representando os níveis LOW, MEDIUM, HIGH e MUITO ALTO. Tenha em mente que o tuidd atualmente suporta apenas os valores 2 e 3. O valor finalmente usado é retornado no campo na autenticação.

Exemplo: 3 2

estado

String

Obrigatório

É um valor indicado pelo provedor para manter uma correspondência entre o requisito e a resposta. Se estiver vinculado ao cookie do navegador, ele também pode ser usado como um mecanismo de segurança para impedir a falsificação de solicitação entre sites.

Exemplo: 3a1d38b154bc-4383-bfc9-a6926fc2644b

nonce

String

Obrigatório

String usada para associar a sessão do cliente ao ID do Token. Ele deve ser passado sem modificação do pedido de autorização para o ID do Token. Deve ser exclusivo por sessão para atenuar os ataques de repetição.

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

exibir

S t r ing

Opção l

String ASCII que especifica a interface do usuário para o fluxo de autenticação e autorização. Os valores podem ser:

  • página : Valor padrão se o parâmetro "display" não for enviado. Nesse caso, a tela apresentada deve ocupar toda a tela do navegador.
  • popup : Deve mostrar uma janela pop-up de 450 px de largura X 500 px de altura.
  • tocar : A tela deve suportar uma interface de usuário - "touch".
  • wap : A tela deve ser compatível com um dispositivo "feature-phone".

Exemplo: página

pronto

String

Opcional

String sensível a maiúsculas e minúsculas ASCII, que especifica se o servidor deve ou não solicitar nova autenticação ou consentimento. Os valores possíveis são:

  • nenhum : Você não deve solicitar nova autenticação ou consentimento do usuário. Se o usuário não foi autenticado anteriormente, ou uma nova autenticação ou consentimento é necessário, um erro é retornado indicando que o login é necessário. Isso pode ser usado como um mecanismo para verificar a existência de autenticação ou consentimento.
  • login : Você deve solicitar ao usuário uma nova autenticação ou consentimento. Se isso não puder ser feito, você deve retornar um erro.
  • consentimento : Você deve mostrar ao usuário a tela de consentimento.
  • select_account : Se o usuário tiver várias contas, você deverá solicitá-las para selecionar uma. Se isso não puder ser feito, um erro deve ser retornado.
  • móvel : A solicitação não deve mostrar nenhuma tela e a ordem deve permanecer aberta até que a autorização seja concluída no dispositivo.

Exemplo: consentimento

max_age

Em t

Obligatori o

Especifica o tempo máximo em segundos que dura a autenticação do usuário. Depois que esse tempo tiver passado, você deverá autenticar novamente. Quando esse parâmetro é usado na solicitação, o ID do Token deve conter o valor de "auth timeâ".

Exemplo: 300

ui_locales

String

Obrigatório

Lista de strings com os idiomas suportados pela interface do usuário, de acordo com RFC5646, separados por espaço. Esse parâmetro é apenas um guia e, caso o idioma preferencial não seja suportado pelo servidor, nenhum erro deverá ser retornado.

Exemplo: es

claims_locales

Strin g

Obligatori o

Lista de string com os idiomas das reivindicações, de acordo com RFC5646. Esse parâmetro é apenas um guia e, caso o idioma preferencial não seja suportado pelo servidor, nenhum erro deverá ser retornado.

Exemplo: es

id_token_hint

String

Condicional

Usado em conjunto com o parâmetro prompt = nenhum e contém o id_token gerada anteriormente, como um sinal para a sessão de autenticação. Se o id_token ainda for válido e o usuário estiver conectado, o servidor deverá responder positivamente. Caso contrário, um erro de autenticação deve ser respondido. Dentro do id_token incluído no id_token_hint , o servidor não precisa ser listado no campo aud.

Exemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6

login_hint

Strin g

Opção l

Diga ao servidor qual ID usar para o login. Pode conter o MSISDN, o MSISDN criptografado ou um PCR de um Token ID previamente obtido:

  • MSISDN : Valor do MSISDN completo com "+" e código do país. Por exemplo: +443523536534.
  • ENCR_MSISDN : Valor obtido do parâmetro subscriber_id no caso de usar a API Discovery da GSMA.
  • PCR : Valor da PCR (Referência do Cliente Pseudo-Anônima) de um processo de autenticação executado anteriormente.

Se não for enviado, a plataforma solicitará que você insira o número da linha ou alias para se autenticar.

Exemplo: ENCR_MSISDN: 23153464dsfghâ

dtbs

Strin g

Opção l

Informações que devem ser criptografadas pela chave privada do usuário final. A informação assinada é devolvida no id_token , no atributo dts do JWT, juntamente com a chave pública para decifrá-lo.

Requisito

Headers

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

Respuesta 302

Headers

Localização: <redirect_url>

 

RESPOSTA AO URL DO REDIRECIONAMENTO

Esse terminal registra os dados que serão enviados para o redirect_uri do aplicativo, após o sucesso ou falha da tentativa de autenticação.

Tem o seguinte formato:

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

Exemplo de URI

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

Parâmetros do URI

Field

Digite

Obrigatório

Descrição

estado

Strin g

Obligatori o

A string "state" como foi passado na exigência original.

Exemplo: 12324tsfdsdf

code

String

Obrigatório

O Código de Autorização de uso único, de acordo com o OAuth 2.0. Ele será usado no parâmetro code do requisito Token.

Exemplo: 2d902ae7

engano

String

Obrigatório

Se houvesse um erro, este parâmetro apareceria e o parâmetro code não

Exemplo: invalid_id

error_description

String

Obrigatório

Em caso de erro, uma descrição de qual foi o erro.

Exemplo: o ID do cliente é inválido.

 

O parâmetro "scope"

Os valores de scope Atualmente aceitos são:

Valor

Digite

Obrigatório

Descrição

openid

Strin g

Obrigatório

Necessário de acordo com o padrão, para indicar que é uma solicitação de autenticação OpenId. Este escopo somente concede acesso de autenticação. Não concede acesso a qualquer informação ou serviço adicional.

profile

String

Opcional

Conceda a permissão do provedor para acessar os seguintes atributos do usuário: name , family_name , given_name , middle_name , nickname , preferred_username , profile , picture , website , gender , birthdate , zoneinfo , locale , updated_at .

Tenha em mente que pode ser que nem todas as informações estejam disponíveis no perfil do usuário.

email

String

Opcional

Conceder permissão para obter o email do usuário e, opcionalmente, se ele for verificado. Atributos: email , email_verified

address

String

Opcional

Conceda permissão para obter o endereço do usuário. Atributo: address

phone

String

Opcional

Conceder permissão para obter o telefone do usuário. Atributos: phone_number , phone_number_verified

offline_access

String

Opcional

Conceder permissão para o usuário refresh_token para obter acesso ao UserInfo, caso o usuário não esteja logado no site.

tuidd_advertising

String

Opcional

Conceda ao provedor permissão para enviar anúncios ao usuário, de acordo com a quantidade e a frequência definidas pelo mesmo.

tuidd_survey

String

Opcional

Conceda permissão ao provedor para enviar pesquisas ao usuário, de acordo com a quantidade e a frequência definidas pelo mesmo.

tuidd_payment

String

Opcional

Conceda ao provedor permissão para enviar pagamentos ao usuário, de acordo com a quantidade e a frequência definidas pelo mesmo.

tuidd_coupon

String

Opcional

Conceda ao provedor permissão para enviar cupons de benefícios ao usuário, de acordo com a quantidade e a frequência configurada pelo mesmo.

 

Você pode solicitar mais de um scope na solicitação de autorização, que retornará toda a união de todos os atributos associados ao invocar o UserInfo.

 

Token de Acesso

ENDPOINT DE TOKEN

Depois de fazer uma solicitação bem-sucedida ao endpoint de Autorização e receber o "código". Por meio do redirect_url, esse código pode ser trocado no terminal Token, por um access_token e um id_token assinado. O id_token também contém os tokens de acesso para serviços adicionais do Tuidd.

Tem o seguinte formato:

POST /{op_token_endpoint}

Exemplo:

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

Parâmetros do URI

Field

     

op_token_endpoint

String

Obrigatório

É o terminal Token do operador, que foi retornado no processo de descoberta, no campo   ligações com   rel = token .

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

 

Requisito

Headers

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

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

Corpo

Field

Digite

Obrigatório

Descrição

grant_type

String

Obrigatório

Deve ter o valor "authorization_code"

code

String

Obrigatório

É o código de autorização recebido no URL de redirecionamento.

redirect_uri

String

Obrigatório

Usado como um mecanismo de segurança extra. Deve corresponder ao URL de redirecionamento registrado na plataforma de administração do tuidd. Deve ir no formato URL Encoded.

 

 

Responder 200

Corpo

JSON com os seguintes parâmetros:

Field

Digite

Obrigatório

Descrição

access_token

String

Obrigatório

Token de acesso de acordo com o OAuth 2.0 usado para obter informações do usuário. Para isso, ele deve ser enviado na solicitação UserInfo. Pode ser reutilizado enquanto não expirar.

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

token_type

String

Obrigatório

Ele deve ter o valor "portador", conforme definido na RFC 6749 seção 7.1 e RFC6750.

Exemplo: portador

id_token

String

Obrigatório

É um token adicional usado no OIDC para fornecer informações de segurança sobre a autenticação do usuário final. Ele também tem os tokens dos serviços adicionais da tuidd. Este id_token tem um formato JSON Web Token (JWT). O formato desse id_token e suas informações são descritos na seção a seguir.

Exemplo: eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJub25jZSI6â

expires_in

Int

Opcional

Um registro de data e hora Unix que representa quando o token de acesso não será mais válido.

Exemplo: 1475744978

refresh_token

Stri ng

Opcional

É o código que pode ser usado para obter um novo access_token usando a mesma autorização de usuário.

Atualmente não é suportado.

O parâmetro id_token

Esse parâmetro é fornecido no formato JWT (JSON Web Token). Consiste em 3 partes separadas por um período (".")

- A primeira parte é o cabeçalho, que contém informações sobre como o token é assinado. Para assinar, você pode usar qualquer um desses algoritmos: HS256, HS512, RS256, RS512.

- A segunda parte contém todos os atributos com as informações no formato JSON. Em seguida, cada um dos atributos é descrito.

- A terceira parte é a assinatura. Usando as informações do cabeçalho, você pode determinar o algoritmo usado na assinatura. Se o hash da primeira e segunda parte corresponder à assinatura, pode-se assegurar que o id_token não foi adulterado.

Cada uma dessas 3 partes é codificada usando o formato “Base64 URL”. Para mais informações sobre o formato JWT, consulte: http://jwt.io

Os atributos recebidos dentro do id_token Eles são:

Field

Digite

Obrigatório

Descrição

iss

String

Obrigatório

URL do servidor que gerou o token.

sub

String

Obrigatório

É o identificador do usuário para o aplicativo que solicitou o token (PCR).

aud

String

Obrigatório

É o client_id do aplicativo para o qual o token é direcionado.

exp

Int

Obrigatório

É o timestamp do Unix que representa a expiração do token.

iat

Int

Obrigatório

É o timestamp do Unix que representa a data de criação do token.

auth_time

Int

Obrigatório

É o registro de data e hora Unix que representa a data em que a autenticação do usuário foi executada.

nonce

String

Obrigatório

String passada pelo provedor de serviços no requisito de autorização, no parâmetro nonce . Permite associar o id_token com a sessão e serve para mitigar os ataques de repetição.

acr

Int

Obrigatório

â € œ Referência de Classe de Contexto de Autenticaçà £ oâ €. É o valor LOA usado na autenticação.

amr

String

Obrigatório

â € œ Referências de mà © todo de autenticaçà £ oâ €. É o nome ou os nomes dos métodos de autenticação usados. Esses métodos dependem do operador. Os valores possíveis são: OK, DEV_PIN, SIM_PIN, UID_PWD, BIOM, HDR, OTP.

 

azp

String

Condicional

É o client_id do provedor de serviços autorizado a usar o token, caso seja diferente do parâmetro aud. Se for a mesma entidade, esse parâmetro é opcional.

at_hash

String

Opcional

É um hash access_token, codificado em Base64URL. O algoritmo de hash está certo dada no momento da inscrição do pedido.

dts

String

Opcional

Informações enviadas no campo dtbs no requisito de autorização, criptografado pela chave privada do usuário final.

upk

String

Opcional

Chave pública do usuário final necessária para decifrar dts .

dts_time

Int

Opcional

Unix Timestamp, representando o tempo de criptografia de informações em dts .

tuidd_service_tokens

String

Opcional

JSON com as informações do token de serviço adicional do tuidd, de acordo com as permissões solicitadas no escopo , no requisito de autorização. Veja abaixo o formato dele.

 

O atributo tuidd_service_tokens

É um JSON com as informações dos serviços adicionais do tuidd. O formato depende do tipo de serviço.

Os tokens disponíveis são:

- advertising_token

- survey_token

- notification_token

- coupon_token

Cada um tem os seguintes atributos:

Field

Digite

Obrigatório

Descrição

token

String

Obrigatório

Valor do token.

exp

Int

Obrigatório

É o timestamp do Unix que representa a expiração do token.

contar

Int

Obrigatório

Número de vezes que o token pode ser usado antes da data de expiração.

 

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

}

}  

 

Informação do usuário

USER ENDPOINT INFO

Informações do usuário permite a aplicação do provedor de serviços para acessar as informações do usuário final. Qual informação pode ser acessada é determinada pelo parâmetro scope do requisito de autorização original.

O requisito tem o seguinte formato:

POST / {op_userinfo_endpoint} {? token}

Se nenhum desses “escopos” foi solicitado no requisito de autorização original, o requisito de Informações do usuário retornará um erro (401).

Como no resto dos endpoints, requer autenticação - autenticação básica operador específico.

Exemplo de URI

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

Parâmetros do URI

Field

Digite

Obrigatório

Descrição

op_userinfo_endpoint

String

Obrigatório

URL do terminal UserInfo, retornado no processo de descoberta., Sob o campo ligações com rel = "userinfo"

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

token

String

Obrigatório

O access_token recebido do terminal Token.

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

 

Requerimiento

Headers

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

Responder   200

Corpo

Atributo

Digite

Obrigatório

Descrição

sub

String

Obrigatório

PCR que identifica o usuário no aplicativo

nome

String

Opcional

Nome completo do usuário

given_name

String

Opcional

Primeiro nome do usuário

family_name

String

Opcional

Sobrenome do usuário

middle_name

String

Opcional

Segundo nome do usuário. Se houvesse um terceiro ou quarto, eles iriam para o espaço separado

preferred_username

String

Opcional

Alias ​​do usuário

perfil

String

Opcional

URL com a página com as informações do perfil do usuário

imagem

String

Opcional

URL onde a imagem do usuário está localizada

website

String

Opcional

URL da página de um usuário, como um blog pessoal ou uma rede social.

e-mail

String

Opcional

E-mail do usuário

email_verified

Booleano

Opcional

Indica VERDADEIRO ou FALSO se o email estiver marcado ou não

gênero

String

Opcional

Gênero do usuário. Valores possíveis: masculino, feminino, outro.

data de nascimento

String

Opcional

Data de nascimento no formato AAAA-MM-DD

zoneinfo

String

Opcional

String com o fuso horário do usuário, dependendo de: http://www.twinsun.com/tz/tz-link-htm

localidade

String

Opcional

Informação de idioma de acordo com RFC5646. O valor é 2 valores alfabéticos minúsculos para o código de idioma e 2 valores alfabéticos maiúsculos para o país, separados por um hífen.

Exemplo: en-GB

phone_number

String

Opcional

Número da linha do usuário no formato E.164, incluindo o prefixo internacional.

Exemplo: +541155443322

phone_number_verified

Booleano

Opcional

Indica VERDADEIRO ou FALSO se o telefone estiver marcado ou não

endereço

JSON

Opcional

JSON com os dados do endereço do usuário. Veja abaixo

udpated_at

String

Opcional

Timestamp Unix com a data de atualização das informações apresentadas.

 

O formato do campo endereço :

Atributo

Digite

Obrigatório

Descrição

formatado

String

Opcional

Endereço completo que pode ser exibido

street_address

String

Opcional

Nome da rua, número e número do departamento ou escritório.

localidade

String

Opcional

Cidade ou localidade

região

String

Opcional

Região, estado ou província

postal_code

String

Opcional

CEP (ZIP)

país

String

Opcional

Nome do país

 

Responder   401

Corpo

Atributo

Digite

Obrigatório

Descrição

engano

String

Obrigatório

Código de erro.

error_description

String

Obrigatório

Descrição do erro

 

Exemplo :

{

  "error": "access_denied",

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

}

 

Entity Pager Example