JWT를 사용하여 사용자 인증

이 페이지에서는 API 게이트웨이에서 사용자 인증을 지원하는 방법을 설명합니다.

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

API 게이트웨이는 JWT 발급자의 JSON 웹 키 집합(JWKS)을 사용해서 효율적인 방법으로 JWT를 검증합니다. JWKS 위치는 게이트웨이 API 구성의 x-google-jwks_uri 필드에 지정되어 있습니다. API 게이트웨이는 JWKS를 5분 동안 캐시에 저장하고 5분 간격으로 새로고침합니다.

시작하기 전에

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

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

클라이언트 인증을 지원하도록 API 게이트웨이 구성

서명된 JWT의 클레임을 확인하려면 API 게이트웨이의 API 구성에 보안 요구사항 객체와 보안 정의 객체가 있어야 합니다.

JWT 인증을 지원하려면 다음 안내를 따르세요.

OpenAPI 2.0 보안 스킴에 따라 API 구성의 보안 정의에 다음을 추가합니다.

 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"

보안 섹션을 API 수준에서 추가하여 전체 API에 적용하거나 메서드 수준에서 추가하여 특정 메서드에 적용합니다.
```
 security:
   - your_custom_auth_id: []
```

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

x-google-audiences 필드는 필수가 아닙니다. API 게이트웨이는 aud 클레임에 https://SERVICE_NAME 형식의 백엔드 서비스 이름이 포함된 모든 JWT를 수락합니다.

참고: API 게이트웨이는 aud 클레임에서 다음 URI 유형을 수락하지 않습니다.

내부 주소
IPv4 또는 IPv6 주소

백엔드 서비스에 액세스하도록 추가 클라이언트 ID를 허용하려면 허용된 클라이언트 ID를 쉼표로 구분된 값을 사용하여 x-google-audiences 필드에 입력합니다. 그러면 API 게이트웨이가 aud 클레임에서 지정된 클라이언트 ID가 있는 JWT를 수락합니다.

x-google-jwks_uri 필드는 필수입니다. API 게이트웨이는 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로 설정합니다.

참고: API 게이트웨이가 x-google-jwks_uri에 요청을 전송할 때 요청에는 x-forwarded-proto 헤더가 포함됩니다.

API 게이트웨이 API에 인증된 호출 수행

인증 토큰을 사용하여 요청을 보낼 때는 토큰을 Authorization:Bearer 헤더에 두는 것이 좋습니다. 예를 들면 다음과 같습니다.

curl --request POST \
  --header "Authorization: Bearer ${TOKEN}" \
  "${GATEWAY_URL}/echo"

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

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

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

API에서 인증 결과 수신

API 게이트웨이는 수신하는 모든 헤더를 전달합니다. 하지만 API 구성에서 백엔드 주소가 x-google-backend로 지정된 경우 원래 Authorization 헤더를 재정의합니다.

API 게이트웨이는 X-Apigateway-Api-Userinfo의 인증 결과를 백엔드 API에 전송합니다. 원래 Authorization 헤더 대신 이 헤더를 사용하는 것이 좋습니다. 이 헤더는 base64url로 인코딩되며 JWT 페이로드를 포함합니다.

다음 단계

서비스 간 인증