topo
Início da Busca
Campo de busca
Fim da Busca
Início do contéudo da página

Introdução

A ANS adotou o padrão OAuth 2 para autenticação e controle dos acessos as suas APIs.

O OAuth 2 é um protocolo de autorização que permite que aplicativos obtenham acesso limitado a contas de usuários em um serviço HTTP sem a necessidade de enviar seu usuário e senha. Basicamente, o usuário delega, a um determinado aplicativo, acesso aos seus dados em um determinado serviço ou API.

Este guia informativo é destinado a desenvolvedores de sistemas das Operadoras e fornece uma visão geral de como integrar seu aplicativo às APIs da ANS utilizando o padrão OAuth 2.

Não é objetivo deste documento ser referência de conteúdo instrucional sobre o OAuth 2. Pressupomos que a equipe técnica de desenvolvedores já possua conhecimento suficiente para utilização deste padrão de autenticação. Para mais informações sobre o OAuth 2, sugerimos a leitura do artigo https://oauth.net/2/


Implementação OAuth 2 pela ANS

Vamos alinhar o conhecimento da implementação OAuth 2 pela ANS.

O OAuth 2, sendo uma especificação, descreve alguns papéis envolvidos em uma comunicação que utiliza o protocolo:

  • Resource Owner: (Usuário) A entidade capaz de controlar o acesso aos recursos protegidos. Como o nome diz, é o “dono do recurso”. Neste caso é representado pela Operadora através do seu Registro ANS;
  • Resource Server: Servidor que hospeda os recursos a serem acessados. É quem recebe as requisições. É quem expõe a API a ser acessada;
  • Client: (Cliente OAuth) Aplicativo (web, mobile, etc) que solicita acesso aos recursos protegidos do Resource Owner;
  • Authorization Server: Servidor de autorização que gera tokens de acesso e permite que o Client acesse os recursos autorizados pelo Resource Owner.

Não vamos detalhar todos os fluxos de autenticação suportados pelo o OAuth 2, mas apenas os fluxos suportados pela ANS. Até este momento, é suportado apenas o Client Credentials.

No fluxo Client Credentials o aplicativo, representado por um Cliente OAuth, solicita um token de acesso enviando suas credenciais: cliente ID e cliente secret ao Servidor de Autorização. Se as credenciais do aplicativo estiverem corretas, o servidor de autorização retornará um Token de Acesso (Access Token). Agora, o aplicativo está autorizado a utilizar o recurso!

Uma vez que o aplicativo possua o Token de acesso, ele pode usá-lo para acessar os dados do Resource Owner através da API, limitado ao escopo de acesso, até que o token expire ou seja revogado.

Importante: Só utilizamos este fluxo quando o Cliente OAuth solicitar acesso aos recursos do Resource Owner a qual ele pertence. Ou seja, o aplicativo é de propriedade da própria Operadora.

O parâmetro scope retornado pelo token é um subconjunto de valores que indica quais recursos do Resource Owner o aplicativo deseja obter acesso.

Este subconjunto de valores está definido na documentação de cada API e é associado ao Resource Owner. Ou seja, só se pode solicitar acesso a um escopo em que o Resource Owner tenha autoridade.

Por padrão os Tokens de Acesso da ANS são gerados com a validade de 10 (dez) horas a partir da data de sua emissão, com exceção para Tokens gerados manualmente na “Área do Desenvolvedor”, que possuem validade de 01 (um) ano. Essa informação é retornada junto com o Token de Acesso.

Caso um token de acesso expire, ao utiliza-lo para acessar uma API será retornando um erro de “token inválido". Neste caso, deve ser solicitado um novo Token de acesso.


Requisição REST com OAuth 2

Para que seu aplicativo acesse um serviço REST protegido pelo protocolo OAuth 2, basta enviar o Token de Acesso no parâmetro Authorization no HTTP Header com o prefixo Bearer.

Authorization: Bearer SEU_TOKEN_DE_ACESSO

Exemplo:

curl --request GET \
--url https://apidesejada.com/api \
--header 'authorization: Bearer SEU_TOKEN_AQUI \
--header 'content-type: application/json'

Compartilhe:

 
Fim do contéudo da página
Início do rodapé
ANS no Twitter
ANS no YouTube
ANS no Facebook
ANS no Likedin
RSS
ANS no Instagram
Acesso à Informação
Marca do Governo Federal
Fim do rodapé

ANS - Agência Nacional de Saúde Suplementar - Av. Augusto Severo, 84 - Glória Rio de Janeiro/RJ - CEP: 20021-040

Ir para o topo da página