wiki

Number Verification: mudanças entre as edições

← Edição anterior
Santos.paula (discussão | contribs)
editors
254 edições
Santos.paula (discussão | contribs)
editors
254 edições
 
(10 revisões intermediárias pelo mesmo usuário não estão sendo mostradas)
Linha 11: Linha 11:
Dois mecanismos são utilizados para obter as informações:
Dois mecanismos são utilizados para obter as informações:
*Autenticação Baseada em Rede : Mecanismo de autenticação baseado na identificação do celular. Uma operadora de rede sabe a qual assinante o celular conectado à rede pertence e qual é o número de telefone associado.
*Autenticação Baseada em Rede : Mecanismo de autenticação baseado na identificação do celular. Uma operadora de rede sabe a qual assinante o celular conectado à rede pertence e qual é o número de telefone associado.
*Autenticação Baseada em SIM : Mecanismo de autenticação baseado na identificação do SIM do assinante instalado no dispositivo do usuário. Este mecanismo se baseia em tokens temporários fornecidos pela operadora, conforme definido pela GSMA TS.43 e GSMA ASAC .
*Autenticação Baseada em SIM : Mecanismo de autenticação baseado na identificação do SIM do assinante instalado no dispositivo do usuário. Este mecanismo se baseia em tokens temporários fornecidos pela operadora, conforme definido pela [https://www.gsma.com/newsroom/gsma_resources/ts-43-service-entitlement-configuration/ GSMA TS.43] e [https://www.gsma.com/newsroom/gsma_resources/asac-01/ GSMA ASAC].


A API de Verificação de Número é usada pelo consumidor da API para realizar verificações em tempo real do número de telefone de um dispositivo móvel usado para acessar o aplicativo. Essa verificação pode ser feita pelo provedor da API, retornando "true" ou "false", ou pelo aplicativo, comparando o número de telefone retornado pelo provedor da API com o número de telefone do dispositivo que está sendo usado.
A API de Verificação de Número é usada pelo consumidor da API para realizar verificações em tempo real do número de telefone de um dispositivo móvel usado para acessar o aplicativo. Essa verificação pode ser feita pelo provedor da API, retornando "true" ou "false", ou pelo aplicativo, comparando o número de telefone retornado pelo provedor da API com o número de telefone do dispositivo que está sendo usado.
Linha 25: Linha 25:
<br>
<br>


===Casos de uso===
====Casos de uso====
*Integração de aplicativos (aplicativo bancário, mídias sociais, compartilhamento de viagens, carteira móvel, …): O SMS com Senha Única é amplamente utilizado para comprovar que o usuário possui o dispositivo móvel associado ao número de celular usado para o cadastro. No entanto, isso adiciona atrito à jornada do usuário. O aplicativo pode, em vez disso, solicitar uma autenticação contínua do dispositivo móvel por meio da API de Verificação de Número;
*Integração de aplicativos (aplicativo bancário, mídias sociais, compartilhamento de viagens, carteira móvel, …): O SMS com Senha Única é amplamente utilizado para comprovar que o usuário possui o dispositivo móvel associado ao número de celular usado para o cadastro. No entanto, isso adiciona atrito à jornada do usuário. O aplicativo pode, em vez disso, solicitar uma autenticação contínua do dispositivo móvel por meio da API de Verificação de Número;
*Login do aplicativo: em vez de nome de usuário/senha, o aplicativo pode solicitar autenticação contínua do dispositivo móvel;
*Login do aplicativo: em vez de nome de usuário/senha, o aplicativo pode solicitar autenticação contínua do dispositivo móvel;
Linha 49: Linha 49:


====Solicitação de autenticação sem token temporário====
====Solicitação de autenticação sem token temporário====
Se o Consumidor da API não tiver um token temporário TS.43, ele deverá usar o Fluxo de Código de Autorização do OpenId Connect, conforme descrito na versão atual do [[Gerenciamento de Acesso e Consentimento do Usuário das APIs CAMARA]] . Para que esse método de autenticação funcione, o dispositivo deve estar conectado à rede móvel.
Se o Consumidor da API não tiver um token temporário TS.43, ele deverá usar o Fluxo de Código de Autorização do OpenId Connect, conforme descrito na versão atual do [https://github.com/camaraproject/IdentityAndConsentManagement Gerenciamento de Acesso e Consentimento do Usuário das APIs CAMARA] . Para que esse método de autenticação funcione, o dispositivo deve estar conectado à rede móvel.


O Consumidor da API deve usar o parâmetro de solicitação prompt=none na Solicitação de Autenticação, conforme descrito no [[OIDC Connect]] , garantindo que não haja interação do usuário. O Provedor da API implica o parâmetro de solicitação prompt=none na Solicitação de Autenticação para esta API.
O Consumidor da API deve usar o parâmetro de solicitação prompt=none na Solicitação de Autenticação, conforme descrito no [https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest OIDC Connect] , garantindo que não haja interação do usuário. O Provedor da API implica o parâmetro de solicitação prompt=none na Solicitação de Autenticação para esta API.


<br>
<br>


===Funcionalidade da API===
===Funcionalidade da API===
A API define um endpoint de serviço:
A API define dois endpoints de serviço:
<br>
* POST/verify: Verificação de número de telefone - Operação de API para verificar um número de telefone recebido como entrada. Ele pode ser recebido em texto simples ou em formato hash.
*GET/device-phone-number: Compartilhamento de número de telefone - Operação de API para retornar o número de telefone associado ao token de acesso.
<br>
<br>


====POST /verify====
===POST/verify===
Verifica se o número de telefone com hash/texto simples recebido corresponde ao número de telefone associado ao token de acesso.


Verifica se o número de telefone especificado (em texto simples ou em formato hash) corresponde ao que o usuário está usando no momento. Somente um dos formatos simples ou em formato hash deve ser fornecido.


*(1)
* A verificação do número será feita para o usuário que se autenticou via rede móvel
*(2) 
* Retorna verdadeiro/falso dependendo se o número de telefone com hash recebido como entrada corresponde ao usuário autenticado device phone numberassociado ao token de acesso
*(3) 
*(4)
<br>
<br>


====Entradas====
====Entradas====
*Exemplo de '''Request body''':
{
  "phoneNumber": "+123456789"
}


<br>
<br>
*
 
*
====Saídas====
*
Se bem-sucedido, um objeto JSON será retornado contendo os seguintes dados:
*
<br>
<br>


*Exemplo de '''Request body''':
 
<syntaxhighlight lang="json">
*Exemplo de '''Response 200 OK''':
 
{
{
   "ageThreshold": 18,
   "devicePhoneNumberVerified": true
  "phoneNumber": "+34629255833",
  "idDocument": "66666666q",
  "name": "Federica Sanchez Arjona",
  "givenName": "Federica",
  "familyName": "Sanchez Arjona",
  "middleNames": "Sanchez",
  "familyNameAtBirth": "YYYY",
  "birthdate": "1978-08-22",
  "email": "federicaSanchez.Arjona@example.com",
  "includeContentLock": true,
  "includeParentalControl": true
}
}
</syntaxhighlight>


<br>
<br>


====Erros====
<br>
*Se o token de acesso de autenticação não for válido, um '''401 UNAUTHENTICATED''' erro será retornado
*Se a chamada da API contiver um erro de formatação ou qualquer outro erro sintático, um '''400 INVALID_ARGUMENT''' erro será retornado.
*Se a solicitação não pode ser autenticada e uma nova autenticação é necessária, um '''401 UNAUTHENTICATED''' erro será retornado.
*Se o consumidor da API tiver um token de acesso válido que não tenha o escopo necessário para obter informações de verificação de idade para a assinatura de rede especificada, um '''403 PERMISSION_DENIED''' erro será retornado.
<br>
===GET/device-phone-number===
Retorna o número de telefone associado ao token de acesso.
Retorna o número de telefone para que os clientes da API possam verificar o número eles mesmos:
* Será feito para o usuário que se autenticou via rede móvel
* Ele retorna o usuário autenticado device phone numberassociado ao token de acesso
<br>
====Entradas====
*Nesse endpoint o Resquest body é vazio, é feito o envio do token associado na header.
<br>


====Saídas====
====Saídas====
Se bem-sucedido, um objeto JSON será retornado contendo os seguintes dados:
Se bem-sucedido, um objeto JSON será retornado contendo os seguintes dados:
<br>
<br>
*'''ageCheck''': Indique 'true' quando a idade do usuário for igual ou superior ao limite de idade (idade >= limite de idade) e 'false' caso contrário (idade < limite de idade). Caso contrário, 'not_available'.
 
*'''verifiedStatus''': verdadeiro se as informações fornecidas foram verificadas com outra forma de identificação oficial; caso contrário, falso.
*'''identityMatchScore''': A pontuação geral das informações de identidade disponíveis no Operador, informações fornecidas no corpo da solicitação, comparando-as com as que o MNO possui, ou utilizando diretamente informações internas do MNO. É opcional para o Operador retornar a pontuação de correspondência de identidade.
*'''contentLock''': Indica se a assinatura associada ao número de telefone tem algum tipo de bloqueio de conteúdo (ou seja, determinado conteúdo da web bloqueado).
*'''parentalControl''': Indica se a assinatura associada ao número de telefone tem algum tipo de controle parental ativado.
<br>


*Exemplo de '''Response 200 OK''':
*Exemplo de '''Response 200 OK''':
<syntaxhighlight lang="json">
 
{
{
   "ageCheck": "true",
   "devicePhoneNumber": "+123456789"
  "verifiedStatus": true,
  "identityMatchScore": 90,
  "contentLock": "false",
  "parentalControl": "true"
}
}
</syntaxhighlight>


<br>
<br>
Linha 125: Linha 132:
*Se o token de acesso de autenticação não for válido, um '''401 UNAUTHENTICATED''' erro será retornado
*Se o token de acesso de autenticação não for válido, um '''401 UNAUTHENTICATED''' erro será retornado
*Se a chamada da API contiver um erro de formatação ou qualquer outro erro sintático, um '''400 INVALID_ARGUMENT''' erro será retornado.
*Se a chamada da API contiver um erro de formatação ou qualquer outro erro sintático, um '''400 INVALID_ARGUMENT''' erro será retornado.
*Se a assinatura da rede não puder ser identificada a partir dos parâmetros fornecidos (por exemplo, o identificador da assinatura não estiver associado a nenhum cliente do CSP), um '''404 IDENTIFIER_NOT_FOUND''' erro será retornado.
*Se a solicitação não pode ser autenticada e uma nova autenticação é necessária, um '''401 UNAUTHENTICATED''' erro será retornado.
*Se o consumidor da API tiver um token de acesso válido que não tenha o escopo necessário para obter informações de verificação de idade para a assinatura de rede especificada, um '''403 PERMISSION_DENIED''' erro será retornado.
*Se o consumidor da API tiver um token de acesso válido que não tenha o escopo necessário para obter informações de verificação de idade para a assinatura de rede especificada, um '''403 PERMISSION_DENIED''' erro será retornado.
*Outros erros podem ser retornados conforme especificado abaixo.
<br>
<br>

Edição atual tal como às 16h23min de 26 de setembro de 2025

Esta API pode verificar ou recuperar o número de telefone celular atualmente alocado pela operadora de rede ao SIM no dispositivo do usuário final

Number Verification

(Stable CAMARA APIs)


Descrição da API

A API “Verificação de Número” é um serviço que permite que empresas confirmem facilmente a propriedade de um número de telefone celular e recuperem o número diretamente do dispositivo do usuário.

Dois mecanismos são utilizados para obter as informações:

  • Autenticação Baseada em Rede : Mecanismo de autenticação baseado na identificação do celular. Uma operadora de rede sabe a qual assinante o celular conectado à rede pertence e qual é o número de telefone associado.
  • Autenticação Baseada em SIM : Mecanismo de autenticação baseado na identificação do SIM do assinante instalado no dispositivo do usuário. Este mecanismo se baseia em tokens temporários fornecidos pela operadora, conforme definido pela GSMA TS.43 e GSMA ASAC.

A API de Verificação de Número é usada pelo consumidor da API para realizar verificações em tempo real do número de telefone de um dispositivo móvel usado para acessar o aplicativo. Essa verificação pode ser feita pelo provedor da API, retornando "true" ou "false", ou pelo aplicativo, comparando o número de telefone retornado pelo provedor da API com o número de telefone do dispositivo que está sendo usado.

Ele utiliza autenticação silenciosa (autenticação baseada em rede ou autenticação baseada em SIM) para verificar a posse de um número de telefone em segundo plano, sem exigir interação do usuário. Não há necessidade de senhas de uso único (OTP) recebidas por SMS nem downloads de aplicativos autenticadores, o que o torna muito mais simples. Pode ser usado no momento da inscrição, login ou transação para validar se o SIM de um usuário não foi falsificado ou clonado.


Como a API de verificação de número ajuda a facilitar a autenticação?

A API de Verificação de Número utiliza mecanismos de telecomunicações para autenticar usuários perfeitamente com base na conexão de seus dispositivos à rede. Este método contrasta com as soluções de autenticação tradicionais, aumentando a conveniência e a segurança do usuário. Ao contrário de processos manuais ou códigos de texto simples, a validação baseada em rede não requer interação do usuário, reforçando a proteção contra acesso não autorizado.

Esta API verifica se o número de telefone celular fornecido (MSISDN) corresponde ao dispositivo que inicia a comunicação de dados, garantindo que os usuários interajam com serviços digitais de dispositivos autenticados.


Casos de uso

  • Integração de aplicativos (aplicativo bancário, mídias sociais, compartilhamento de viagens, carteira móvel, …): O SMS com Senha Única é amplamente utilizado para comprovar que o usuário possui o dispositivo móvel associado ao número de celular usado para o cadastro. No entanto, isso adiciona atrito à jornada do usuário. O aplicativo pode, em vez disso, solicitar uma autenticação contínua do dispositivo móvel por meio da API de Verificação de Número;
  • Login do aplicativo: em vez de nome de usuário/senha, o aplicativo pode solicitar autenticação contínua do dispositivo móvel;
  • Redefinição de senha do aplicativo: a jornada do usuário geralmente depende de SMS com Senha de Uso Único. Assim como no caso de integração do aplicativo, o aplicativo pode solicitar uma autenticação integrada do dispositivo móvel por meio da API de Verificação de Número;
  • Suporte ao cliente;
  • 2FA;
  • Ligação de dispositivo.


A solicitação de autenticação

Para NumberVerification, o provedor da API garante que não haja interação do usuário. Caso seja necessária interação do usuário, o servidor de autorização retornará um erro. Métodos de autenticação como SMS OTP ou usuário/senha são incompatíveis, pois o objetivo é validar o número de celular que está acessando o aplicativo.


Solicitação de autenticação com um token temporário

Se o Consumidor da API tiver um token temporário TS.43 criado no dispositivo móvel, essa API funcionará em todas as conexões, como Wi-Fi, aproveitando a autenticação baseada em SIM. O Consumidor da API envia o token temporário para seu backend, que:

A maneira como os consumidores da API obtêm um token temporário TS.43 e como esse token é enviado ao backend deles está fora do escopo da definição da API.


Solicitação de autenticação sem token temporário

Se o Consumidor da API não tiver um token temporário TS.43, ele deverá usar o Fluxo de Código de Autorização do OpenId Connect, conforme descrito na versão atual do Gerenciamento de Acesso e Consentimento do Usuário das APIs CAMARA . Para que esse método de autenticação funcione, o dispositivo deve estar conectado à rede móvel.

O Consumidor da API deve usar o parâmetro de solicitação prompt=none na Solicitação de Autenticação, conforme descrito no OIDC Connect , garantindo que não haja interação do usuário. O Provedor da API implica o parâmetro de solicitação prompt=none na Solicitação de Autenticação para esta API.


Funcionalidade da API

A API define dois endpoints de serviço:

  • POST/verify: Verificação de número de telefone - Operação de API para verificar um número de telefone recebido como entrada. Ele pode ser recebido em texto simples ou em formato hash.
  • GET/device-phone-number: Compartilhamento de número de telefone - Operação de API para retornar o número de telefone associado ao token de acesso.


POST/verify

Verifica se o número de telefone com hash/texto simples recebido corresponde ao número de telefone associado ao token de acesso.

Verifica se o número de telefone especificado (em texto simples ou em formato hash) corresponde ao que o usuário está usando no momento. Somente um dos formatos simples ou em formato hash deve ser fornecido.

  • A verificação do número será feita para o usuário que se autenticou via rede móvel
  • Retorna verdadeiro/falso dependendo se o número de telefone com hash recebido como entrada corresponde ao usuário autenticado device phone numberassociado ao token de acesso


Entradas

  • Exemplo de Request body:

{ 

 "phoneNumber": "+123456789"

}


Saídas

Se bem-sucedido, um objeto JSON será retornado contendo os seguintes dados:


  • Exemplo de Response 200 OK:

{ 

 "devicePhoneNumberVerified": true

}


Erros


  • Se o token de acesso de autenticação não for válido, um 401 UNAUTHENTICATED erro será retornado
  • Se a chamada da API contiver um erro de formatação ou qualquer outro erro sintático, um 400 INVALID_ARGUMENT erro será retornado.
  • Se a solicitação não pode ser autenticada e uma nova autenticação é necessária, um 401 UNAUTHENTICATED erro será retornado.
  • Se o consumidor da API tiver um token de acesso válido que não tenha o escopo necessário para obter informações de verificação de idade para a assinatura de rede especificada, um 403 PERMISSION_DENIED erro será retornado.


GET/device-phone-number

Retorna o número de telefone associado ao token de acesso. Retorna o número de telefone para que os clientes da API possam verificar o número eles mesmos:

  • Será feito para o usuário que se autenticou via rede móvel
  • Ele retorna o usuário autenticado device phone numberassociado ao token de acesso


Entradas

  • Nesse endpoint o Resquest body é vazio, é feito o envio do token associado na header.


Saídas

Se bem-sucedido, um objeto JSON será retornado contendo os seguintes dados:


  • Exemplo de Response 200 OK:

{ 

 "devicePhoneNumber": "+123456789"

}


Erros


  • Se o token de acesso de autenticação não for válido, um 401 UNAUTHENTICATED erro será retornado
  • Se a chamada da API contiver um erro de formatação ou qualquer outro erro sintático, um 400 INVALID_ARGUMENT erro será retornado.
  • Se a solicitação não pode ser autenticada e uma nova autenticação é necessária, um 401 UNAUTHENTICATED erro será retornado.
  • Se o consumidor da API tiver um token de acesso válido que não tenha o escopo necessário para obter informações de verificação de idade para a assinatura de rede especificada, um 403 PERMISSION_DENIED erro será retornado.


Disponível em “http://3.143.69.156/wiki/index.php?title=Number_Verification&oldid=94724”