OAUTH 2.0
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.
-
Os papéis no OAuth 2
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.
-
Fluxo de autenticação
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.
-
O Scope (Escopo)
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.
-
O Token de Acesso
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'