Client ID e Client Secret, API Key ou usuário e senha

Uma tela de configuração pode pedir uma chave, um segredo ou uma senha, e cada um desses campos alimenta um processo diferente de acesso ao serviço. Conhecer esse processo ajuda a investigar uma falha que aparece horas depois de uma troca de senha ou de uma mudança no portal do fornecedor.

O que cada credencial representa

• API Key: uma chave entregue pelo fornecedor e apresentada da forma definida no contrato, muitas vezes em cada chamada. A chave pode ter prazo de validade, restrições de uso e um procedimento próprio de substituição.
• Client ID: o identificador da aplicação. O Client ID não é secreto e, sozinho, não comprova a identidade de quem chama.
• Client Secret: o segredo que autentica a aplicação, usado junto com o Client ID. Nas integrações com OAuth 2.0, o Client Secret costuma participar da obtenção dos tokens.
• Usuário e senha: os dados de uma conta, que pode ser dedicada à integração. O programa pode trocá-los por um token em uma operação de login ou apresentá-los de outra forma aceita pelo serviço.

Não existe uma regra única para todas as API Keys. Uma chave pode valer até ser revogada ou expirar em uma data, e a geração de uma chave nova pode desativar a anterior na hora ou manter as duas válidas por um período. O nome dos campos também não indica o estilo da API, porque interfaces REST, SOAP e GraphQL podem usar qualquer uma dessas credenciais.

O fluxo client credentials

O OAuth 2.0 define formas diferentes de obter um token, chamadas de fluxos. No fluxo client credentials, a aplicação obtém acesso em nome dela mesma, sem o login de uma pessoa naquela operação. No gateway de pagamento, o integrador do site de vendas segue estes passos:

1. o integrador chama POST /oauth/token com o parâmetro grant_type=client_credentials;
2. o integrador autentica a aplicação da forma prevista pelo fornecedor, como o esquema Basic com o Client ID e o Client Secret, ou com esses dados no corpo da requisição;
3. o serviço de autorização devolve o token no campo access_token, o tipo do token em token_type, a validade em segundos em expires_in e, quando aplicável, os escopos concedidos;
4. o integrador apresenta o token nas chamadas de cobrança, no cabeçalho Authorization, depois da palavra Bearer;
5. o integrador obtém outro token quando o anterior expira, conforme o procedimento do fornecedor.

O Client ID e o Client Secret também aparecem no fluxo de código de autorização, em que uma pessoa autoriza o acesso da aplicação. A presença dos dois campos, portanto, não comprova o fluxo client credentials. O parâmetro grant_type, registrado na chamada ao serviço de autorização, indica o fluxo usado.

O fluxo de senha do usuário, em que a aplicação recebe a senha de uma pessoa e a troca por um token, ainda aparece em integrações antigas. As recomendações atuais de segurança do OAuth desaconselham esse fluxo nas integrações novas.

O token e as mudanças no portal

O programa reutiliza o token enquanto o serviço o aceita e só volta ao serviço de autorização para obter outro. Por isso, a troca da senha ou do segredo no portal do fornecedor pode aparecer só na próxima obtenção do token. Em alguns serviços, a troca revoga na hora os tokens já emitidos. Em outros, os tokens anteriores continuam válidos até expirar, e a documentação de cada fornecedor descreve esse comportamento.

Uma permissão concedida no portal também pode depender de um token novo, quando as permissões ficam gravadas no próprio token, ou valer na hora, quando o serviço consulta as permissões a cada chamada.

Quando uma integração falha horas depois de uma troca de senha, a comparação envolve o horário de emissão do token, a validade informada, o horário da nova obtenção e a resposta dessa tentativa. O intervalo entre a troca e a falha é um indício de que o token anterior continuou válido, e não uma confirmação.

Os erros na obtenção do token

O serviço de autorização do OAuth costuma recusar a obtenção do token com o código 400, ou com o código 401 quando a autenticação da aplicação falha. O corpo da resposta traz o campo error, com um destes valores, entre outros:

• invalid_client: a autenticação da aplicação falhou, por um Client ID desconhecido, um Client Secret errado ou uma forma de autenticação não aceita;
• invalid_grant: a concessão apresentada não é válida, como uma senha de usuário recusada ou um código de autorização vencido;
• unauthorized_client: a aplicação não tem permissão para usar aquele fluxo;
• invalid_scope: o escopo pedido não existe ou não foi concedido à aplicação.

Em uma chamada de negócio, o código 401 aponta outro grupo de causas: o token ausente, expirado ou revogado, ou um token emitido para outro serviço. O código 403 aponta uma recusa de permissão, que um token novo, com as mesmas permissões, não resolve.

As pistas nos registros

Os registros de uma integração costumam trazer sinais do mecanismo de acesso:

• uma chamada a /login com usuário e senha sugere um login próprio do fornecedor;
• uma chamada a /oauth/token com o parâmetro grant_type indica o OAuth e o fluxo usado;
• em uma API GraphQL, a operação de login aparece no corpo da requisição, e não no caminho;
• a palavra Bearer no cabeçalho Authorization mostra um token em uso;
• a palavra Basic no mesmo cabeçalho mostra um usuário e uma senha, ou um Client ID e um Client Secret, codificados;
• um cabeçalho como X-API-Key indica uma chave de API.

Esses sinais dependem do contexto. A primeira obtenção do token pode ter acontecido antes do período registrado no arquivo analisado, e cada fornecedor escolhe os nomes dos próprios caminhos.

Uma credencial exposta

Uma credencial que aparece em um e-mail, em uma captura de tela ou em um log compartilhado precisa ser substituída. A substituição segue o procedimento do fornecedor e inclui a revogação dos tokens emitidos com a credencial antiga, porque a troca do segredo nem sempre invalida esses tokens. Todas as configurações que usam aquela credencial, em cada loja e em cada estação, recebem o valor novo pelo procedimento da integração.

Renovação e rotação

Renovar o acesso é obter um token novo para continuar usando o serviço. Rotacionar a credencial é substituir o segredo ou a chave que autentica a aplicação. Uma rotação pode manter a credencial antiga válida por um período, revogá-la na hora ou seguir uma data programada, e esse comportamento precisa ser conhecido antes da mudança na configuração de várias lojas.

No fluxo client credentials, a obtenção de um token novo repete a autenticação da aplicação com o Client ID e o Client Secret. A especificação do OAuth orienta que esse fluxo não entregue um refresh token, o código usado em outros fluxos para obter um token novo sem repetir o login. Por isso, a existência de um Client Secret não indica, sozinha, uma renovação por refresh token.

Um programa que pede um token novo a cada erro pode entrar em ciclo sem resolver a falha, porque uma recusa de permissão, de contrato ou de negócio não depende da idade do token.