Nesta página, você aprende como oferecer suporte à autenticação de usuário no Cloud Endpoints.
Para autenticar um usuário, um aplicativo cliente precisa enviar um token da Web do JSON (JWT, na sigla em inglês) no cabeçalho de autorização da solicitação HTTP para sua API de back-end. O Extensible Service Proxy (ESP) valida o token em nome da API, de modo que não é preciso adicionar nenhum código na API para processar a autenticação. No entanto, você precisa configurar o documento da OpenAPI para oferecer suporte aos métodos de autenticação escolhidos.
O ESP valida um JWT de maneira eficiente usando as chaves públicas do emissor do JWT. O ESP armazena as chaves públicas em cache por cinco minutos. Além disso, o ESP armazena em buffer os JWTs validados por cinco minutos ou até a expiração do JWT, o que ocorrer primeiro.
Antes de começar
- Adicione o código de autenticação ao seu aplicativo cliente, seguindo a documentação do provedor de autenticação.
-
Quando seu aplicativo cliente envia uma solicitação HTTP, o cabeçalho de autorização na solicitação deve conter as seguintes declarações do JWT:
iss
(emissor)sub
(assunto)aud
(público-alvo)iat
(emitido em)exp
(prazo de validade)
Como configurar o ESP para aceitar a autenticação de cliente
É preciso ter um objeto de requisito de segurança e um objeto de definições de segurança (ambos em inglês) no documento da OpenAPI para que o ESP valide as declarações no JWT assinado.
Para aceitar a autenticação personalizada:
Adicione o seguinte à definição de segurança no documento da OpenAPI:
securityDefinitions: your_custom_auth_id: authorizationUrl: "" flow: "implicit" type: "oauth2" # The value below should be unique x-google-issuer: "issuer of the token" x-google-jwks_uri: "url to the public key" # Optional. Replace YOUR-CLIENT-ID with your client ID x-google-audiences: "YOUR-CLIENT-ID"
Adicione uma seção de segurança no nível da API, para ser aplicável a toda a API, ou no nível do método, para ser aplicável a um método específico.
security: - your_custom_auth_id: []
É possível estabelecer várias definições de segurança no documento da OpenAPI, mas cada uma delas precisa ter um emissor diferente. Se você usar seções "security" no nível da API e do método, as configurações no nível do método modificarão as configurações no nível da API.
O campo x-google-audiences
não é obrigatório. O ESP é compatível com todos os JWTs que apresentam o nome do serviço de back-end no formato https://SERVICE_NAME
na declaração aud
. Para permitir outros IDs de cliente na lista de permissões de acesso ao serviço de back-end, especifique os IDs de cliente permitidos no campo x-google-audiences
com valores separados por vírgulas. Em seguida, o ESP aceita os JWTs com qualquer um dos IDs de cliente especificados na declaração aud
.
O ESP suporta dois formatos de chave pública assimétrica definidos pela extensão x-google-jwks_uri
OpenAPI:
-
formato de conjunto JWK.
Exemplo:
x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
-
X509. Exemplo:
x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
Se você estiver usando um formato de chave simétrica, defina x-google-jwks_uri
como o URI de um arquivo que contenha a string de chave codificada por base64url.
Se você omitir x-google-jwks_uri
, o ESP seguirá o protocolo Descoberta do OpenID Connect para descobrir automaticamente o URI JWKS para o provedor OpenID fornecido.
O ESP fará uma solicitação para x-google-issuer/.well-known/openid-configuration
, analisará a resposta JSON e lerá o URI JWKS do campo de nível superior jwks_uri
.
Observe que a omissão de x-google-jwks_uri
resultará em tempos de inicialização a frio mais altos, já que o ESP precisará fazer uma chamada remota extra na inicialização.
Portanto, é recomendável omitir esse campo apenas se o URI de JWKS for alterado com frequência.
A maioria dos provedores OpenID certificados, como Google, Auth0 e Okta, tem URIs JWKS estáveis.
Você também pode personalizar os locais do JWT adicionando x-google-extensions
. Para detalhes, consulte extensões da OpenAPI.
Como fazer uma chamada autenticada para uma Endpoints API
Quando enviar uma solicitação usando um token de autenticação, recomendamos que você coloque o token no cabeçalho Authorization:Bearer
. Exemplo:
curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"
Aqui, ENDPOINTS_HOST
e TOKEN
são variáveis de ambiente contendo o nome do host da API e o token de autenticação, respectivamente. Consulte Como fazer uma solicitação autenticada para uma API Endpoints. Para o código de amostra que envia uma solicitação usando o cabeçalho Authorization:Bearer
.
Se não for possível usar o cabeçalho ao enviar a solicitação, coloque o token de autenticação em um parâmetro de consulta denominado access_token
. Por exemplo:
curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"
Como receber resultados autenticados na API
O ESP geralmente encaminha todos os cabeçalhos recebidos. No entanto, ele substitui o cabeçalho Authorization
original quando o endereço de back-end é especificado por x-google-backend
na especificação OpenAPI ou BackendRule
na configuração do serviço de gRPC.
O ESP enviará o resultado da autenticação no X-Endpoint-API-UserInfo
para a API de back-end. Recomendamos usar este cabeçalho em vez do original
Cabeçalho Authorization
. Esse cabeçalho é uma string em que base64url
codifica
um objeto JSON. O formato de objeto JSON é diferente no ESPv2 e no ESP.
Para o ESPv2, o objeto JSON é exatamente o payload original do JWT. Para o ESP,
o objeto JSON usa nomes de campo diferentes e coloca o payload original do JWT no campo claims
.
Consulte Gerenciar JWTs no serviço de back-end
para mais informações sobre o formato.
A seguir