이 페이지에서는 Cloud Endpoints에서 사용자 인증을 지원하는 방법을 설명합니다.
사용자를 인증하려면 클라이언트 애플리케이션이 HTTP 요청의 승인 헤더에 있는 JSON 웹 토큰(JWT)을 백엔드 API로 전송해야 합니다. Extensible Service Proxy(ESP)는 API를 대신하여 토큰의 유효성을 검사하므로 인증을 처리하기 위해 API에 코드를 추가할 필요가 없습니다. 하지만 선택한 인증 방법을 지원하도록 OpenAPI 문서를 구성해야 합니다.
ESP는 JWT 발급자의 공개 키를 사용하여 JWT의 성능을 검사합니다. ESP는 5분 동안 공개 키를 캐시합니다. 또한 ESP는 검사된 JWT를 5분 동안 또는 JWT 만료까지 중 먼저 발생하는 시점까지 캐시합니다.
시작하기 전에
Firebase 인증 설명서에 따라 클라이언트 애플리케이션에 인증 코드를 추가합니다. Firebase는 비밀번호, 전화번호, 인기 ID 제공업체(예: Google, Facebook, Twitter 등)를 통한 인증을 지원합니다.
클라이언트 애플리케이션이 HTTP 요청을 전송할 때 요청의 승인 헤더에는 다음 JWT 클레임이 포함되어야 합니다.
securityDefinitions:firebase:authorizationUrl:""flow:"implicit"type:"oauth2"# Replace YOUR-PROJECT-ID with your project IDx-google-issuer:"https://securetoken.google.com/YOUR-PROJECT-ID"x-google-jwks_uri:"https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"x-google-audiences:"YOUR-PROJECT-ID"
보안 섹션을 API 수준에서 추가하여 전체 API에 적용하거나 메소드 수준에서 추가하여 특정 메소드에 적용합니다.
security:
- firebase: []
OpenAPI 문서에 여러 보안 정의를 정의할 수 있지만 정의마다 발급자가 달라야 합니다. API 및 메서드 수준 모두에 security 섹션을 사용하는 경우에는 메서드 수준 설정이 API 수준 설정을 재정의합니다.
x-google-extensions를 추가하여 JWT 위치를 맞춤설정할 수도 있습니다. 자세한 내용은 openAPI 확장 프로그램을 참조하세요.
Endpoints API에 인증된 호출 실행
인증 토큰을 사용하여 요청을 전송할 경우 보안상의 이유로 Authorization:Bearer 헤더에 인증 토큰을 포함하는 것이 좋습니다. 예를 들면 다음과 같습니다.
ESP는 수신하는 모든 헤더를 전달합니다. 하지만 OpenAPI 사양의 x-google-backend 또는 gRPC 서비스 구성의 BackendRule에서 백엔드 주소를 지정할 때 ESP는 원래 Authorization 헤더를 재정의합니다.
ESP는 X-Endpoint-API-UserInfo의 인증 결과를 백엔드 API에 전송합니다. 원래 Authorization 헤더 대신 이 헤더를 사용하는 것이 좋습니다. 이 헤더는 base64url이 JSON 객체를 인코딩하는 문자열입니다. JSON 객체 형식은 ESPv2와 ESP 간에 다릅니다.
ESPv2의 경우 JSON 객체는 정확히 원래 JWT 페이로드입니다. ESP의 경우 JSON 객체는 서로 다른 필드 이름을 사용하고 원래 JWT 페이로드를 claims 필드에 넣습니다.
형식에 대한 자세한 내용은 백엔드 서비스에서 JWT 처리를 참조하세요.
[[["이해하기 쉬움","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-03-25(UTC)"],[[["\u003cp\u003eCloud Endpoints uses JSON Web Tokens (JWT) for user authentication, validated by the Extensible Service Proxy (ESP) without requiring additional code in your API.\u003c/p\u003e\n"],["\u003cp\u003eThe client application must include specific JWT claims (iss, sub, aud, iat, exp) in the authorization header of HTTP requests for successful authentication.\u003c/p\u003e\n"],["\u003cp\u003eOpenAPI documents need security requirement and definition objects for ESP to validate JWT claims, such as using Firebase authentication with the necessary security settings and project ID.\u003c/p\u003e\n"],["\u003cp\u003eAuthentication tokens can be sent in the \u003ccode\u003eAuthorization:Bearer\u003c/code\u003e header, or alternatively as an \u003ccode\u003eaccess_token\u003c/code\u003e query parameter, for making calls to an Endpoints API.\u003c/p\u003e\n"],["\u003cp\u003eESP forwards the authentication results to the backend API in the \u003ccode\u003eX-Endpoint-API-UserInfo\u003c/code\u003e header, which is a base64url-encoded JSON object containing the JWT payload and is the recommended way of accessing the authentication results.\u003c/p\u003e\n"]]],[],null,["# Using Firebase to authenticate users\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nThis page describes how to support user authentication in Cloud Endpoints.\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. The\n[Extensible Service Proxy (ESP)](/endpoints/docs/glossary#extensible_service_proxy)\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 your\nOpenAPI document to support your chosen authentication methods.\n\nESP validates a JWT in a performant way by using the JWT's\nissuer's public keys. ESP caches the public keys for five\nminutes. In addition, ESP caches validated JWTs for five minutes\nor until JWT expiry, whichever happens first.\n\nBefore you begin\n----------------\n\n- Add authentication code to your client application, following the [Firebase authentication](https://firebase.google.com/docs/auth/), documentation. Firebase supports authentication by using passwords, phone numbers, and popular federated identity providers like Google, Facebook and Twitter.\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 your OpenAPI document\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 OpenAPI document for ESP to\nvalidate the claims in the signed JWT.\n\n\u003cbr /\u003e\n\nTo support Firebase authentication:\n\n1. Add the following to the security definition in your OpenAPI\n document:\n\n securityDefinitions:\n firebase:\n authorizationUrl: \"\"\n flow: \"implicit\"\n type: \"oauth2\"\n # Replace YOUR-PROJECT-ID with your project ID\n x-google-issuer: \"https://securetoken.google.com/YOUR-PROJECT-ID\"\n x-google-jwks_uri: \"https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com\"\n x-google-audiences: \"YOUR-PROJECT-ID\"\n\n | **Note:** When defining security schemes in your OpenAPI document for JWT authentication, you must include the `authorizationUrl` field, even if its value is an empty string (\"\"). This is a requirement of the OpenAPI specification. Although the field is mandatory for the spec, its value is not used by Cloud Endpoints or API Gateway when validating a JWT.\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 - firebase: []\n\n\nYou can define multiple security definitions in the OpenAPI document, 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\nYou may also customize JWT locations by adding `x-google-extensions`. For details, see [openAPI extensions](/endpoints/docs/openapi/openapi-extensions#x-google-jwt-locations).\n\n\u003cbr /\u003e\n\nMaking an authenticated call to an Endpoints API\n------------------------------------------------\n\nWhen you send a request using an authentication token, for security reasons, we\nrecommend that you put the token in the `Authorization:Bearer` header. For\nexample: \n\n curl -H \"Authorization: Bearer ${TOKEN}\" \"${ENDPOINTS_HOST}/echo\"\n\nHere, `ENDPOINTS_HOST` and `TOKEN` are environment variables containing your\nAPI host name and authentication token, respectively. See\n[Making an authenticated request to an Endpoints API](/endpoints/docs/openapi/service-account-authentication#making_an_authenticated_request).\nfor 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 \"${ENDPOINTS_HOST}/echo?access_token=${TOKEN}\"\n\nReceiving authenticated results in your API\n-------------------------------------------\n\n\nESP 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 OpenAPI specification or `BackendRule`\nin gRPC service configuration.\n\n\nESP will send the authentication result in the `X-Endpoint-API-UserInfo`\nto the backend API. We recommend using this header instead of the original\n`Authorization` header. This header is a string that `base64url` encodes\na JSON object. The JSON object format differs between ESPv2 and ESP.\nFor ESPv2, the JSON object is exactly the original JWT payload. For ESP,\nthe JSON object uses different field names and put original JWT payload under `claims` field.\nSee [Handle JWTs in the backend service](/endpoints/docs/openapi/migrate-to-esp-v2#handle-jwt)\nfor more information on the format.\n\n\u003cbr /\u003e\n\nWhat's next\n-----------\n\n\n- [Troubleshooting JWT validation](/endpoints/docs/openapi/troubleshoot-jwt)\n- [Authentication between services](/endpoints/docs/openapi/service-account-authentication)\n\n\u003cbr /\u003e"]]
