securityDefinitions:your_custom_auth_id:authorizationUrl:""flow:"implicit"type:"oauth2"#Thevaluebelowshouldbeuniquex-google-issuer:"issuer of the token"x-google-jwks_uri:"url to the public key"#Optional.ReplaceYOUR-CLIENT-IDwithyourclientIDx-google-audiences:"YOUR-CLIENT-ID"
在 API 層級新增安全性區段，套用至整個 API，或是在方法層級新增安全性區段，套用至特定方法。
security:
- your_custom_auth_id: []
您可以在 API 設定中定義多項安全定義，但每項定義必須要有不同的發布者。如果您在 API 層級與方法層級使用安全性區段，方法層級的相關設定會覆寫 API 層級的設定。
[[["容易理解","easyToUnderstand","thumb-up"],["確實解決了我的問題","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["難以理解","hardToUnderstand","thumb-down"],["資訊或程式碼範例有誤","incorrectInformationOrSampleCode","thumb-down"],["缺少我需要的資訊/範例","missingTheInformationSamplesINeed","thumb-down"],["翻譯問題","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["上次更新時間：2025-09-03 (世界標準時間)。"],[[["\u003cp\u003eAPI Gateway validates user authentication by processing JSON Web Tokens (JWTs) sent in the authorization header of HTTP requests, eliminating the need for custom authentication code in your API.\u003c/p\u003e\n"],["\u003cp\u003eThe API config must include a security definitions object and a security requirement object to enable API Gateway to validate the signed JWT claims.\u003c/p\u003e\n"],["\u003cp\u003eAPI Gateway utilizes the JWT issuer's JSON Web Key Set (JWKS) specified in the \u003ccode\u003ex-google-jwks_uri\u003c/code\u003e field of the API config for JWT validation, caching it for five minutes and refreshing it afterwards.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003ex-google-audiences\u003c/code\u003e field in the API config can be used to specify allowed client IDs, and multiple security definitions can be used with each one having a unique issuer.\u003c/p\u003e\n"],["\u003cp\u003eClient applications should include specific JWT claims in the authorization header, and API Gateway will forward the authentication results to the backend API via the \u003ccode\u003eX-Apigateway-Api-Userinfo\u003c/code\u003e header.\u003c/p\u003e\n"]]],[],null,["# Using JWT to authenticate users\n===============================\n\nThis page describes how to support user authentication in API Gateway.\n\nTo authenticate a user, a client application must send a\n[JSON Web Token (JWT)](https://jwt.io/) in the authorization header of the\nHTTP request to your backend API. API Gateway\nvalidates the token on behalf of your API, so you don't have to add any code in\nyour API to process the authentication. However, you do need to configure the\nAPI config for your gateway to support your chosen authentication methods.\n\nAPI Gateway validates a JWT in a performant way by using the JWT\nissuer's [JSON Web Key Set (JWKS)](https://tools.ietf.org/html/rfc7517). The location of the JWKS is specified in the `x-google-jwks_uri` field of the gateway's API config. API Gateway caches the JWKS for five\nminutes and refreshes it every five minutes.\n\nBefore you begin\n----------------\n\n- Add authentication code to your client application, following the authentication provider's documentation.\n\n\n- When your client application sends an HTTP request, the authorization header in the request must contain the following JWT claims:\n - `iss` (issuer)\n - `sub` (subject)\n - `aud` (audience)\n - `iat` (issued at)\n - `exp` (expiration time)\n\n\u003cbr /\u003e\n\nConfiguring API Gateway to support client authentication\n--------------------------------------------------------\n\n\nYou must have a [security\nrequirement object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityRequirementObject) and a [security\ndefinitions object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#securityDefinitionsObject) in your API config for API Gateway to\nvalidate the claims in the signed JWT.\n\n\u003cbr /\u003e\n\nTo support JWT authentication:\n\n1. Add the following to the security definition in your API config, which follows the [OpenAPI 2.0 security scheme](https://swagger.io/specification/v2/#securityDefinitionsObject):\n\n securityDefinitions:\n your_custom_auth_id:\n authorizationUrl: \"\"\n flow: \"implicit\"\n type: \"oauth2\"\n # The value below should be unique\n x-google-issuer: \"issuer of the token\"\n x-google-jwks_uri: \"url to the public key\"\n # Optional. Replace YOUR-CLIENT-ID with your client ID\n x-google-audiences: \"YOUR-CLIENT-ID\"\n\n2. Add a security section at either the API level to apply to the entire\n API, or at the method level to apply to a specific method.\n\n security:\n - your_custom_auth_id: []\n\n\nYou can define multiple security definitions in the API config, but each\ndefinition must have a different issuer. If you use security sections at both\nthe API level and at the method level, the method-level settings override the\nAPI-level settings.\n\n\u003cbr /\u003e\n\n\nThe `x-google-audiences` field is *not* required. API Gateway\naccepts all JWTs with the backend service name in the form of\n`https://`\u003cvar translate=\"no\"\u003eSERVICE_NAME\u003c/var\u003e in the `aud` claim.\n| **Note** : API Gateway does not accept the following URI types in the `aud` claim:\n|\n| - Internal addresses\n| - IPv4 or IPv6 addresses\n\nTo allow additional client IDs to access the backend service, you can specify the\nallowed client IDs in the `x-google-audiences` field by using\ncomma-separated values. API Gateway then accepts the JWTs with any of the\nspecified client IDs in the `aud` claim.\n\n\u003cbr /\u003e\n\n\nThe `x-google-jwks_uri` field *is* required.\nAPI Gateway supports two asymmetric public key formats defined\nby the `x-google-jwks_uri` OpenAPI extension:\n\n- [JWK set format](https://tools.ietf.org/html/rfc7517#section-5). For example: \n\n ```\n x-google-jwks_uri: \"https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json\"\n ```\n- [X509](https://tools.ietf.org/html/rfc5280). For example: \n\n ```\n x-google-jwks_uri: \"https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com\"\n ```\n\n\nIf you are using a symmetric key format, set `x-google-jwks_uri` to\nthe URI of a file that contains the base64url-encoded key string.\n| **Note** : When API Gateway sends requests to the `x-google-jwks_uri`, the request will contain the `x-forwarded-proto` header.\n\n\u003cbr /\u003e\n\nMaking an authenticated call to an API Gateway API\n--------------------------------------------------\n\nWhen you send a request using an authentication token, we\nrecommend that you put the token in the `Authorization:Bearer` header. For\nexample: \n\n```\ncurl --request POST \\\n --header \"Authorization: Bearer ${TOKEN}\" \\\n \"${GATEWAY_URL}/echo\"\n```\n\nHere, `GATEWAY_URL` and `TOKEN` are environment variables containing your\ndeployed gateway URL and authentication token, respectively. See\n[Making an authenticated request to an API Gateway API](/api-gateway/docs/authenticate-service-account#making_an_authenticated_request) for sample code that sends a request using the `Authorization:Bearer` header.\n\nIf you cannot use the header when sending the request, you can put the\nauthentication token in a query parameter called `access_token`. For example: \n\n curl \"${GATEWAY_URL}/echo?access_token=${TOKEN}\"\n\nReceiving authenticated results in your API\n-------------------------------------------\n\n\nAPI Gateway usually forwards all headers it receives. However, it overrides the\noriginal `Authorization` header when the backend address is specified by\n`x-google-backend` in the API config.\n\n\nAPI Gateway will send the authentication result in the `X-Apigateway-Api-Userinfo`\nto the backend API. It is recommended to use this header instead of the original\n`Authorization` header. This header is `base64url` encoded and contains\nthe JWT payload.\n\n\u003cbr /\u003e\n\nWhat's next\n-----------\n\n- [Authentication between services](/api-gateway/docs/authenticate-service-account)"]]
