Okta를 사용하여 사용자 인증

이 페이지에서는 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 문서에 보안 요구사항 객체와 보안 정의 객체가 있어야 합니다.

Google Cloud Endpoints용 Okta 통합 가이드에 설명된 대로 OpenAPI 문서를 다음과 같이 변경합니다.

  1. OpenAPI 문서의 보안 정의에 다음을 추가합니다. YOUR_OKTA_TENANT_NAME을 Okta 테넌트의 이름으로, YOUR_OKTA_CLIENT_ID를 Okta 테넌트에서 만든 클라이언트 ID로 바꿉니다.

          securityDefinitions:
        okta_jwt:
          authorizationUrl: ""
          flow: "implicit"
          type: "oauth2"
          x-google-issuer: "https://YOUR_OKTA_TENANT_NAME.com"
          x-google-jwks_uri: "https://YOUR_OKTA_TENANT_NAME.com/oauth2/v1/keys"
          x-google-audiences: "YOUR_OKTA_CLIENT_ID"

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

      security:
    - okta_jwt: []

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

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

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

다음 단계