커스텀 방식을 사용하여 사용자 인증

이 페이지에서는 Cloud Endpoints에서 사용자 인증을 지원하는 방법을 설명합니다.

사용자를 인증하려면 클라이언트 애플리케이션이 HTTP 요청의 승인 헤더에 있는 JSON 웹 토큰(JWT)을 백엔드 API로 전송해야 합니다. Extensible Service Proxy(ESP)는 API를 대신하여 토큰의 유효성을 검사하므로 인증을 처리하기 위해 API에 코드를 추가할 필요가 없습니다. 하지만 선택한 인증 방법을 지원하도록 OpenAPI 문서를 구성해야 합니다.

ESP는 JWT 발급자의 공개 키를 사용하여 JWT의 성능을 검사합니다. ESP는 5분 동안 공개 키를 캐시합니다. 또한 ESP는 검사된 JWT를 5분 동안 또는 JWT 만료까지 중 먼저 발생하는 시점까지 캐시합니다.

시작하기 전에

  • 인증 제공업체의 설명서에 따라 클라이언트 애플리케이션에 인증 코드를 추가합니다.

  • 클라이언트 애플리케이션이 HTTP 요청을 전송할 때 요청의 승인 헤더에는 다음 JWT 클레임이 포함되어야 합니다.
    • iss(발급자)
    • sub(제목)
    • aud(대상)
    • iat(발급 시점)
    • exp(만료 시간)

클라이언트 인증을 지원하도록 ESP 구성

ESP가 서명된 JWT의 클레임을 확인하려면 OpenAPI 문서에 보안 요구사항 객체와 보안 정의 객체가 있어야 합니다.

커스텀 인증을 지원하려면 다음을 수행하세요.

  1. 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"

  2. 보안 섹션을 API 수준에서 추가하여 전체 API에 적용하거나 메소드 수준에서 추가하여 특정 메소드에 적용합니다.

     security:
   - your_custom_auth_id: []

OpenAPI 문서에 여러 보안 정의를 정의할 수 있지만 정의마다 발급자가 달라야 합니다. API 및 메서드 수준 모두에 security 섹션을 사용하는 경우에는 메서드 수준 설정이 API 수준 설정을 재정의합니다.

x-google-audiences 필드는 필수가 아닙니다. ESP는 aud 클레임에 https://SERVICE_NAME 형식의 백엔드 서비스 이름이 포함된 모든 JWT를 수락합니다. 백엔드 서비스에 액세스하도록 추가 클라이언트 ID를 허용하려면 허용된 클라이언트 ID를 쉼표로 구분된 값을 사용하여 x-google-audiences 필드에 입력합니다. 그러면 ESP가 aud 클레임에서 지정된 클라이언트 ID가 있는 JWT를 수락합니다.

ESP는 x-google-jwks_uri OpenAPI 확장 프로그램에서 정의한 다음 두 가지 비대칭 공개 키 형식을 지원합니다.

  • JWK 설정 형식 예를 들면 다음과 같습니다. 
    x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. 예를 들면 다음과 같습니다. 
    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

대칭 키 형식을 사용하는 경우 x-google-jwks_uri를 base64url로 인코딩된 키 문자열이 포함된 파일의 URI로 설정합니다.

x-google-jwks_uri를 생략하면 ESP는 OpenID Connect 검색 프로토콜을 사용하여 지정된 OpenID 제공업체의 JWKS URI를 자동으로 검색합니다. ESP는 x-google-issuer/.well-known/openid-configuration에 요청하고 JSON 응답을 파싱하고 최상위 수준 jwks_uri 필드에서 JWKS URI를 읽습니다.

x-google-jwks_uri를 생략하면 시작 시 ESP가 원격 호출을 추가해야 하므로 콜드 스타트 시간이 길어집니다. 따라서 JWKS URI가 자주 변경되는 경우에만 이 필드를 생략하는 것이 좋습니다. 대부분의 인증 OpenID 제공업체(예: Google, Auth0, Okta)는 안정적인 JWKS URI를 보유합니다.

x-google-extensions를 추가하여 JWT 위치를 맞춤설정할 수도 있습니다. 자세한 내용은 openAPI 확장 프로그램을 참조하세요.

Endpoints API에 인증된 호출 실행

인증 토큰을 사용하여 요청을 전송할 경우 보안상의 이유로 Authorization:Bearer 헤더에 인증 토큰을 포함하는 것이 좋습니다. 예를 들면 다음과 같습니다.

curl -H "Authorization: Bearer ${TOKEN}" "${ENDPOINTS_HOST}/echo"

여기서 ENDPOINTS_HOST와 TOKEN은 각각 API 호스트 이름과 인증 토큰을 포함하는 환경 변수입니다. Authorization:Bearer 헤더를 사용하여 요청을 전송하는 샘플 코드는 Endpoints API에 인증된 요청 실행을 참조하세요.

요청 전송 시 헤더를 사용할 수 없으면 access_token이라는 쿼리 매개변수에 인증 토큰을 포함할 수 있습니다. 예를 들면 다음과 같습니다.

curl "${ENDPOINTS_HOST}/echo?access_token=${TOKEN}"

API에서 인증 결과 수신

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 처리를 참조하세요.

다음 단계