Documentos relacionados
O OAuth 2.0 é padronizado como RFC 6749. Um documento detalhado está disponível em https://oauth.net/2. A Autenticação HTTP básica é definida na seção 2 do RFC 2617.
Visão geral
Normalmente, para fornecer a aplicativos de terceiros acesso a recursos restritos, como detalhes de plano de dados e carteiras, o usuário final (proprietário de recursos) precisa compartilhar suas 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 senhas etc. O OAuth2.0 resolve esses problemas introduzindo uma camada de autorização e, assim, 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 do GTAF. O GTAF usa o token de acesso para acessar os detalhes do plano de dados hospedados pela DPA.
A figura a seguir fornece o fluxo geral de informações:
Figura 1. Fluxo do OAuth abstrato.
Tokens de acesso
Os tokens de acesso são as credenciais usadas pelo GTAF para acessar os 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 o GTAF. Os tokens representam escopos e durações de acesso específicos, concedidos pelo usuário final à operadora e aplicados pelo DPA e pelo servidor OAuth da operadora.
O token de acesso fornece uma camada de abstração, substituindo diferentes construções de autorização (por exemplo, nome de usuário e senha) por um único token entendido pela DPA. Essa abstração permite a emissão de tokens de acesso mais restritos do que a concessão de autorização usada para consegui-los, bem como a remoção da necessidade de DPA&39;para entender uma ampla variedade de métodos de autenticação.
Os tokens de acesso podem ter diferentes formatos, estruturas e métodos de uso (por exemplo, propriedades criptográficas) com base nos requisitos de segurança da operadora. O GTAF só oferece suporte aos tokens de acesso do tipo do portador definidos em [RFC6750].
Autenticação do cliente
O GTAF funciona como um "cliente confidencial" e é capaz de manter senhas seguras. No momento, o GTAF é compatível apenas com a autenticação HTTP básica para se autenticar com a DPA. O identificador de cliente é codificado usando o algoritmo de codificação"application/x-www-form-urlencoded" e o valor codificado é usado como o nome de usuário. A senha é codificada com o mesmo algoritmo e usada como a senha.
Os clientes confidenciais, como o GTAF, que recebem credenciais de clientes, se autenticam com o servidor OAuth da operadora enquanto fazem solicitações ao endpoint do token. A autenticação de cliente é usada para: \
- Recuperar um cliente comprometido desativando o cliente ou alterando as credenciais dele, impedindo que um invasor abuse dos tokens de atualização roubados. Alterar um único conjunto de credenciais de 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 a rotação periódica de credenciais.
O GTAF usa o parâmetro de solicitação "client_id" para se identificar ao enviar solicitações ao endpoint do token.
É importante alternar as credenciais do cliente. O servidor OAuth precisa ser compatível com dois pares de credenciais simultâneos durante a rotação e ter a capacidade de desativá-las. Em uma rotação de credenciais típica:
- A operadora cria novas credenciais no servidor OAuth e as entrega ao gerente técnico de contas de maneira segura.
- O Google testa a nova credencial e muda a configuração do GTAF para usá-la.
- O Google notifica a operadora 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 do token é usado pelo GTAF para receber um token de acesso apresentando o token de concessão ou atualização de autorização. O endpoint do token é usado com cada concessão de autorização, exceto para o tipo de concessão implícita (já que um token de acesso é emitido diretamente).
Veja a seguir alguns pontos a serem considerados ao configurar um endpoint de token:
- O local do endpoint do token deve ser fornecido na documentação do serviço.
- O URI do endpoint pode incluir um componente de consulta com formatação "application/x-www-form-urlencoded" que precisa ser retido ao adicionar outros parâmetros de consulta. O URI do endpoint não pode incluir um componente de fragmento.
- Como as solicitações para o endpoint do token resultam na transmissão de credenciais de texto não criptografado (na solicitação e na resposta HTTP), o servidor OAuth da operadora precisa usar o TLS para enviar solicitações ao endpoint do token.
- O GTAF usa o método HTTP "POST" para solicitar um token de acesso.
- Os parâmetros enviados sem valor precisam ser tratados como omitidos da solicitação. O servidor OAuth precisa ignorar os 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ó é compatível com tokens de acesso do tipo portador.
Escopo do token de acesso
Os endpoints de autorização e do 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ço e diferenciando 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ço, a ordem delas não será importante, e cada string adicionará 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 é compatível com 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 do token de acesso enviada pelo GTAF for válida e autorizada, o servidor OAuth 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 retornará uma resposta de erro, conforme descrito na seção a seguir.
Resposta bem-sucedida
Quando o GTAF envia uma solicitação, o servidor OAuth emite um token de acesso e um token de atualização opcional e constrói a resposta adicionando os seguintes parâmetros ao corpo da entidade da resposta HTTP com um código de status 200 (OK):
- access_token:NECESSÁRIO. O token de acesso emitido pelo servidor OAuth. O GTAF espera que o endpoint do token retorne o token do portador.
- expires_in: OBRIGATÓRIO. A vida útil do token de acesso em segundos. Por exemplo, o valor "quot;3600" indica que o token de acesso expira em uma hora a partir do momento em que a resposta foi gerada. Se omitido, o servidor OAuth precisa informar o prazo de validade por outros meios ou documentar o valor padrão.
- token_type: NECESSÁRIO. O tipo do token emitido. Para mais informações sobre diferentes tipos de tokens, consulte a Seção 7.1 da RFC 6749 (em inglês). O valor não diferencia maiúsculas de minúsculas. O GTAF só oferece suporte a tokens do portador no momento da criação deste documento.
- 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 "application/json" Os parâmetros são serializados em uma estrutura JavaScript Object Notation (JSON), adicionando cada parâmetro no nível de estrutura mais alto. Os nomes dos parâmetros e os valores das strings 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 um valor de "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 um valor de "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"
}
Veja alguns pontos importantes a considerar:
- O GTAF ignora nomes de valores não reconhecidos na resposta.
- Os tamanhos dos tokens e outros valores recebidos do servidor OAuth não são definidos.
- O GTAF deve evitar 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 de cliente estiver ausente ou inválido, o servidor OAuth precisará responder com um código de status HTTP 400 (Solicitação inválida) (a menos que o contrário seja especificado) e deverá incluir pelo menos um dos parâmetros listados na seção Código de resposta de erro e códigos.
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 os 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 POST HTTP e uma 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 passará um escopo vazio se um não estiver configurado.
O GTAF espera que um token de acesso seja retornado com um valor "expires_in" (tempo de vida). O valor expira_in deve ter pelo menos 900 segundos e não deverá demorar mais do que algumas horas. A solicitação de um novo token não pode fazer com que os tokens atuais expirem.
Para mais detalhes sobre vários tipos de concessões, consulte a seção 1.3 da RFC 6749 (em inglês).
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 para uma DPA real precisa ser muito mais segura do que a exibida 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 maneira:
$ echo -n gtaf:password | base64
Z3RhZjpwYXNzd29yZA==
Em seguida, o GTAF faz uma solicitação POST de HTTPS para o servidor OAuth usando essas credenciais, o tipo de concessão de client_credentials e o escopo configurado. Por 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 seguinte formato:
{
"access_token":"<token>",
"token_type": "Bearer",
"expires_in":<expiration time>
}
Veja 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 resposta de erro
Se uma solicitação de autorização do GTAF falhar por qualquer um dos motivos indicados na seção "Error Response", o servidor OAuth precisará responder com um código de status HTTP 400 (Solicitação inválida) (a menos que o contrário seja especificado) 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 seja compatível com as seguintes respostas de erro:
| Código do erro | Resposta | Motivo |
| HTTP 400 (em inglês) | solicitação inválida | A solicitação não tem um parâmetro obrigatório, inclui um valor de parâmetro incompatível (diferente 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á incorreto. |
| HTTP 401 (em inglês) | cliente_inválido | Falha na autenticação do cliente (por exemplo, cliente desconhecido, nenhuma autenticação de cliente incluída ou método de autenticação incompatí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 tentar autenticar usando o campo de cabeçalho de solicitação "Authorization", o servidor OAuth precisará 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 (em inglês) | Falha no servidor OAuth |
Para ver detalhes de outras respostas que podem ser usadas para depuração, consulte a seção 5.2 da RFC 6749.