Usar JWT para autenticar utilizadores
Esta página descreve como suportar a autenticação de utilizadores no API Gateway.
Para autenticar um utilizador, uma aplicação cliente tem de enviar um token da Web JSON (JWT) no cabeçalho de autorização do pedido HTTP para a sua API de back-end. O API Gateway valida o token em nome da sua API, pelo que não tem de adicionar código na sua API para processar a autenticação. No entanto, tem de configurar a configuração da API para o seu gateway de modo a suportar os métodos de autenticação escolhidos.
O API Gateway valida um JWT de forma eficiente através do conjunto de chaves Web JSON (JWKS) do emissor do JWT. A localização do JWKS é especificada na configuração da API da gateway. O API Gateway armazena em cache o JWKS durante cinco minutos e atualiza-o a cada cinco minutos.
Antes de começar
- Adicione o código de autenticação à sua aplicação cliente, seguindo a documentação do fornecedor de autenticação.
-
Quando a sua aplicação cliente envia um pedido HTTP, o cabeçalho de autorização no pedido tem de conter as seguintes reivindicações JWT:
iss(emissor)sub(assunto)aud(público-alvo)iat(emitido em)exp(hora de expiração)
Configure o API Gateway para suportar a autenticação de clientes
Tem de ter uma secção de segurança na configuração da API para que o API Gateway valide as reivindicações no JWT assinado. O esquema usado para definir os métodos de segurança depende da versão da especificação OpenAPI que usa.
Para suportar a autenticação JWT:
OpenAPI 2.0
- Adicione o seguinte à configuração da API:
securityDefinitions: your_custom_auth_id: authorizationUrl: "" flow: "implicit" type: "oauth2" # The issuer value should be unique x-google-issuer: "ISSUER" x-google-jwks_uri: "URL_PUBLIC_KEY" # Optional. x-google-audiences: "CLIENT_ID"
Onde:
- ISSUER é o emissor do token.
- URL_PUBLIC_KEY é o URL da chave pública.
- CLIENT_ID é o ID de cliente.
- Adicione uma secção de segurança ao nível da API para aplicar a toda a API ou ao nível do método para aplicar a um método específico.
security: - your_custom_auth_id: []
OpenAPI 3.x
- Adicione o seguinte à configuração da API:
components: securitySchemes: SCHEME_NAME: type: oauth2 flows: implicit: authorizationUrl: "" scopes: {} x-google-auth: issuer: ISSUER jwksUri: URL_PUBLIC_KEY # Optional. Replace CLIENT_ID with your client ID(s) as a list of strings. audiences: - CLIENT_ID jwtLocations: - header: Authorization valuePrefix: "Bearer "
Onde:
- ISSUER é o emissor do token.
- URL_PUBLIC_KEY é o URL da chave pública.
- CLLIENT_ID é uma lista de IDs de clientes como strings.
- Adicione uma secção de segurança ao nível da API para aplicar a toda a API ou ao nível do método para aplicar a um método específico.
security: - SCHEME_NAME: []
Pode definir várias definições de segurança na configuração da API, mas cada definição tem de ter um emissor diferente. Se usar secções de segurança ao nível da API e ao nível do método, as definições ao nível do método substituem as definições ao nível da API.
O campo x-google-audiences (OpenAPI 2.0) ou o campo audiences (OpenAPI 3.x) não é obrigatório. O API Gateway aceita todos os JWTs com o nome do serviço de back-end no formato https://SERVICE_NAME na reivindicação aud.
Para permitir que IDs de cliente adicionais acedam ao serviço de back-end, pode especificar os IDs de cliente permitidos no campo audiences aplicável. São especificados vários públicos-alvo como valores separados por vírgulas no OpenAPI 2.0 e com uma lista no OpenAPI 3.x. através de valores separados por vírgulas. Em seguida, o API Gateway aceita os JWTs com qualquer um dos IDs de cliente especificados na reivindicação aud.
O campo x-google-jwks_uri (OpenAPI 2.0) ou jwksUri (OpenAPI 3.x) é obrigatório.
O gateway da API suporta dois formatos de chave pública assimétricos definidos
por esta extensão OpenAPI:
-
Formato do conjunto JWK.
Por exemplo:
OpenAPI 2.0
x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
OpenAPI 3.x
jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
-
X509. Por exemplo:
OpenAPI 2.0
x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
OpenAPI 3.x
jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"
Se estiver a usar um formato de chave simétrica, defina o x-google-jwks_uri (OpenAPI 2.0) ou o jwksUri (OpenAPI 3.x) para o URI de um ficheiro que contenha a string de chave codificada em base64url.
Faça uma chamada autenticada a uma API do API Gateway
Quando envia um pedido através de um token de autenticação, recomendamos que coloque o token no cabeçalho Authorization:Bearer. Por
exemplo:
curl -H "Authorization: Bearer TOKEN" "GATEWAY_URL/hello"
Aqui, GATEWAY_URL e TOKEN devem ser substituídos pelo URL do gateway implementado e pelo token de autenticação, respetivamente. Consulte o artigo
Fazer um pedido autenticado a uma API do API Gateway para ver um exemplo de código que envia um pedido através do cabeçalho Authorization:Bearer.
Se não puder usar o cabeçalho ao enviar o pedido, pode colocar o token de autenticação num parâmetro de consulta denominado access_token. Por exemplo:
curl "GATEWAY_URL/hello?access_token=TOKEN"Receba resultados autenticados na sua API
Normalmente, o API Gateway encaminha todos os cabeçalhos que recebe. No entanto, substitui o cabeçalho Authorization original quando o endereço do back-end é especificado por x-google-backend na configuração da API.
O API Gateway envia o resultado da autenticação no cabeçalho X-Apigateway-Api-Userinfo para a API de back-end. Recomendamos que use este cabeçalho em vez do cabeçalho Authorization original. Este cabeçalho está codificado em base64url e contém o payload JWT.