Documentos relacionados
O OAuth 2.0 é padronizado como RFC 6749. Um documento detalhado está disponível em https://oauth.net/2. A autenticação básica HTTP é definida na seção 2 da RFC 2617.
Visão geral
Normalmente, para dar acesso a aplicativos de terceiros a recursos restritos, como plano de dados e detalhes da carteira, o usuário final (proprietário do recurso) precisa compartilhar as credenciais com o terceiro. Isso cria vários problemas e limitações, como armazenamento de credenciais, autenticação de senha, acesso amplo aos recursos do usuário final, vazamento de senha etc. O OAuth2.0 resolve esses problemas ao introduzir uma camada de autorização, protegendo e limitando o acesso aos recursos protegidos do usuário final.
Em vez de usar as credenciais do usuário final para acessar recursos protegidos, como detalhes do plano de dados, o GTAF recebe um token de acesso. Os tokens de acesso são emitidos para o GTAF em nome das credenciais dele. Em seguida, o GTAF usa o token de acesso para acessar os detalhes do plano de dados hospedados pelo DPA.
A figura a seguir mostra o fluxo de informações de alto nível:
Figura 1. Fluxo abstrato do OAuth.
Tokens de acesso
Os tokens de acesso são as credenciais usadas pelo GTAF para acessar detalhes do plano de dados da DPA da operadora. Um token de acesso é uma string que representa uma autorização emitida para o GTAF. A string geralmente é opaca para a GTAF. Os tokens representam escopos e durações específicos de acesso, concedidos pelo usuário final à operadora e aplicados pela DPA e pelo servidor OAuth da operadora.
O token de acesso fornece uma camada de abstração, substituindo diferentes estruturas de autorização (por exemplo, nome de usuário e senha) por um único token entendido pela DPA. Essa abstração permite emitir tokens de acesso mais restritivos do que a concessão de autorização usada para obtê-los, além de remover a necessidade de o DPA entender uma ampla variedade de métodos de autenticação.
Os tokens de acesso podem ter diferentes formatos, estruturas e métodos de utilização (por exemplo, propriedades criptográficas) com base nos requisitos de segurança da operadora. A GTAF só aceita tokens de acesso do tipo portador definidos na [RFC6750] (link em inglês).
Autenticação do cliente
O GTAF funciona como um "cliente confidencial" e é capaz de manter as senhas seguras. No momento, a GTAF oferece suporte apenas à autenticação básica HTTP para autenticar com a DPA. O identificador do cliente é codificado usando o algoritmo de codificação "application/x-www-form-urlencoded", e o valor codificado é usado como nome de usuário. A senha é codificada usando o mesmo algoritmo e usada como senha.
Clientes confidenciais, como o GTAF, que recebem credenciais de cliente, fazem a autenticação com o servidor OAuth da operadora ao fazer solicitações para o endpoint de token. A autenticação de cliente é usada para: \
- Recuperar um cliente comprometido desativando-o ou mudando as credenciais dele, evitando assim que um invasor abuse de tokens de atualização roubados. Mudar um único conjunto de credenciais do cliente é significativamente mais rápido do que revogar um conjunto inteiro de tokens de atualização.
- Implementar práticas recomendadas de gerenciamento de autenticação, que exigem rotação periódica de credenciais.
A GTAF usa o parâmetro de solicitação "client_id" para se identificar ao enviar solicitações ao endpoint de token.
A capacidade de alternar as credenciais do cliente é especialmente importante. O servidor OAuth precisa ser compatível com dois pares simultâneos de credenciais durante a rotação e ter a capacidade de desativar credenciais. Em uma rotação de credenciais típica:
- A operadora cria novas credenciais no servidor OAuth e as entrega ao gerente de contas técnicas de maneira segura.
- O Google testa a nova credencial e muda a configuração do GTAF para usar a nova credencial.
- O Google notifica a operadora de que as credenciais antigas podem ser desativadas.
- A operadora desativa as credenciais e notifica o Google.
- O Google verifica se as credenciais antigas não estão mais operacionais.
O servidor OAuth precisa ser compatível com o processo de rotação acima.
Endpoint do token
O endpoint de token é usado pela GTAF para receber um token de acesso apresentando a concessão de autorização ou o token de atualização. O endpoint de token é usado com todas as concessões de autorização, exceto o tipo de concessão implícita, já que um token de acesso é emitido diretamente.
Confira alguns pontos a serem considerados ao configurar um endpoint de token:
- A localização do endpoint do token deve ser fornecida na documentação do serviço.
- O URI do endpoint pode incluir um componente de consulta formatado "application/x-www-form-urlencoded", que precisa ser mantido ao adicionar outros parâmetros de consulta. O URI do endpoint não pode incluir um componente de fragmento.
- Como as solicitações ao endpoint de token resultam na transmissão de credenciais de texto simples (na solicitação e resposta HTTP), o servidor OAuth da operadora precisa usar TLS para enviar solicitações ao endpoint de token.
- O GTAF usa o método HTTP "POST" ao fazer solicitações de token de acesso.
- Os parâmetros enviados sem um valor precisam ser tratados como omitidos da solicitação. O servidor OAuth precisa ignorar parâmetros de solicitação não reconhecidos. Os parâmetros de solicitação e resposta não podem ser incluídos mais de uma vez.
- O GTAF só aceita tokens de acesso do tipo portador.
Escopo do token de acesso
Os endpoints de autorização e token permitem que o cliente especifique o escopo da solicitação de acesso usando o parâmetro de solicitação "scope". Por sua vez, o servidor de autorização usa o parâmetro de resposta "scope" para informar ao cliente o escopo do token de acesso emitido.
O valor do parâmetro de escopo é expresso como uma lista de strings delimitadas por espaços e que diferenciam maiúsculas de minúsculas. As strings são definidas pelo servidor de autorização. Se o valor contiver várias strings delimitadas por espaços, a ordem delas não importa, e cada string adiciona um intervalo de acesso extra ao escopo solicitado.
scope = scope-token *( SP scope-token )
scope-token = 1*( %x21 / %x23-5B / %x5D-7E )
O GTAF não exige que o escopo seja implementado, mas oferece suporte a esse recurso. Para mais informações, consulte a Seção 3.3 da RFC 6749.
Como emitir um token de acesso
Se a solicitação de token de acesso enviada pela GTAF for válida e autorizada, o servidor OAuth vai emitir um token de acesso e um token de atualização opcional. Se a solicitação falhar na autenticação do cliente ou for inválida, o servidor OAuth vai retornar uma resposta de erro conforme descrito na seção a seguir.
Resposta de sucesso
Quando o GTAF envia uma solicitação, o servidor OAuth emite um token de acesso e um token de atualização opcional, além de construir a resposta adicionando os seguintes parâmetros ao corpo da entidade da resposta HTTP com um código de status 200 (OK): \
- access_token::obrigatório. O token de acesso emitido pelo servidor OAuth. O GTAF espera que o endpoint de token retorne um token de portador.
- expires_in::obrigatório. A vida útil do token de acesso em segundos. Por exemplo, o valor "3600" indica que o token de acesso vai expirar em uma hora a partir do momento em que a resposta foi gerada. Se omitido, o servidor OAuth precisa fornecer o tempo de expiração por outros meios ou documentar o valor padrão.
- token_type::obrigatório. O tipo do token emitido. Para mais informações sobre diferentes tipos de tokens, consulte a Seção 7.1 da RFC 6749. O valor não diferencia maiúsculas de minúsculas. No momento da redação deste artigo, o GTAF só é compatível com tokens de portador.
- refresh_token::OPCIONAL. O token de atualização, que pode ser usado para receber novos tokens de acesso usando a mesma concessão de autorização.
- scope:OPCIONAL, se implementado e idêntico ao escopo solicitado pelo GTAF. Caso contrário, é obrigatório.
Os parâmetros são incluídos no corpo da entidade da resposta HTTP usando o "application/json". Os parâmetros são serializados em uma estrutura de notação de objetos JavaScript (JSON) adicionando cada parâmetro no nível mais alto da estrutura. Os nomes de parâmetros e valores de string são incluídos como strings JSON. Os valores numéricos são incluídos como números JSON. A ordem dos parâmetros não importa e pode variar.
O servidor de autorização PRECISA incluir o campo de cabeçalho de resposta HTTP "Cache-Control"
com o valor "no-store" em qualquer resposta que contenha tokens, credenciais
ou outras informações sensíveis, bem como o campo de cabeçalho de resposta "Pragma"
com o valor "no-cache".
Por exemplo:
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token":"2YotnFZFEjr1zCsicMWpAA",
"token_type":"Bearer",
"expires_in":3600,
"refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
"example_parameter":"example_value"
}
Confira alguns pontos importantes a serem considerados:
- A GTAF ignora nomes de valores não reconhecidos na resposta.
- Os tamanhos dos tokens e outros valores recebidos do servidor OAuth ficam indefinidos.
- O GTAF precisa evitar fazer suposições sobre tamanhos de valores. O servidor OAuth precisa documentar o tamanho de qualquer valor emitido.
Resposta de erro
Se uma solicitação de autorização falhar por qualquer motivo, como URI de redirecionamento ausente, inválido ou incompatível, ou se o identificador do cliente estiver ausente ou for inválido, o servidor OAuth deverá responder com um código de status HTTP 400 (Solicitação inválida), a menos que especificado de outra forma, e incluir pelo menos um dos parâmetros listados na seção "Códigos e respostas de erro".
Concessão de autorização no GTAF
Uma concessão de autorização é uma credencial que representa a autorização do usuário final (para acessar recursos protegidos, como informações de saldo de dados) usada pelo GTAF para receber um token de acesso.
O GTAF usa o tipo de concessão client_credentials. No tipo de concessão client_credentials, o GTAF solicita um token usando uma solicitação HTTP POST e a autenticação básica HTTP. Todas as solicitações são enviadas por TLS (ou seja, HTTPS), e o GTAF não pode se integrar a um servidor OAuth sem um certificado TLS válido. O GTAF pode transmitir um escopo de token configurável e vai transmitir um escopo vazio se nenhum for configurado.
O GTAF espera que um token de acesso seja retornado com um valor "expires_in" (tempo de vida). O valor de expires_in precisa ser de pelo menos 900 segundos e não pode ser maior que algumas horas. A solicitação de um novo token não pode fazer com que os tokens atuais expirem antes do tempo.
Para mais detalhes sobre vários tipos de concessão, consulte a seção 1.3 da RFC 6749.
Exemplo de solicitação e resposta
Suponha que o GTAF tenha a seguinte configuração para um servidor OAuth:
URL: https://www.example.com/gettoken/
Client ID: gtaf
Client secret: password
Scope: dpa
Observação:a chave secreta do cliente de um DPA real precisa ser muito mais segura do que a mostrada no exemplo.
Para produzir a string de autorização, o ID do cliente, ':' e a senha são concatenados e codificados em base64. Isso pode ser replicado em uma interface de linha de comando da seguinte forma:
$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==
Em seguida, o GTAF faz uma solicitação HTTPS POST ao servidor OAuth usando essas credenciais, o tipo de concessão client_credentials e o escopo configurado. No exemplo, a solicitação do GTAF é semelhante à solicitação gerada por:
$ curl -H 'Authorization: Basic Z3RhZjpwYXNzd29yZA==' -X POST \
-d 'grant_type=client_credentials&scope=dpa' 'https://www.example.com/gettoken/'
Os cabeçalhos usados pelo GTAF não corresponderão aos enviados pelo curl, embora o cabeçalho de autorização seja idêntico.
O GTAF espera uma resposta no formato:
{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}
Confira a seguir um exemplo de resposta válida:
{
"access_token":"YXRudWhhZXVoLGFodWFoaGF1aG9zaHVvYWV1Cg",
"token_type": "Bearer",
"expires_in":3600
}
Observação:a resposta precisa ser um JSON válido.
Códigos e respostas de erro
Se uma solicitação de autorização da GTAF falhar por qualquer um dos motivos declarados na seção "Resposta de erro", o servidor OAuth vai responder com um código de status HTTP 400 (Solicitação inválida), a menos que especificado de outra forma, e incluir um dos seguintes parâmetros com a resposta:
Por exemplo: \
HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"error":"invalid_request"
}
O GTAF espera que o servidor OAuth ofereça suporte às seguintes respostas de erro:
| Código do erro | Resposta | Motivo |
| HTTP 400 | invalid_request | A solicitação não tem um parâmetro obrigatório, inclui um valor de parâmetro não compatível (além do tipo de concessão), repete um parâmetro, inclui várias credenciais, usa mais de um mecanismo para autenticação com o GTAF ou está malformada de outra forma. |
| HTTP 401 | invalid_client | A autenticação do cliente falhou (por exemplo, cliente desconhecido, nenhuma autenticação do cliente incluída ou método de autenticação não compatível). O servidor OAuth pode retornar um código de status HTTP 401 (Não autorizado) para indicar quais esquemas de autenticação HTTP são compatíveis. Se o cliente tentou autenticar usando o campo de cabeçalho de solicitação "Authorization", o servidor OAuth precisa responder com um código de status HTTP 401 (Não autorizado) e incluir o campo de cabeçalho de resposta "WWW-Authenticate" correspondente ao esquema de autenticação usado pelo cliente. |
| HTTP 500 | Falha no servidor OAuth |
Para detalhes de outras respostas que podem ser usadas para depuração, consulte a seção 5.2 da RFC 6749.