JWT OAuth 토큰 사용

이 페이지는 Apigee 및 Apigee Hybrid에 적용됩니다.

Apigee Edge 문서 보기

이 주제에서는 OAuthV2 정책을 사용하여 JWT 액세스 토큰을 생성, 확인, 갱신하는 방법을 설명합니다.

소개

JWT 작업을 사용하면 OAuthV2 정책이 JWT 형식으로 액세스 토큰을 발급하는 방법을 설명하는 표준인 IETF RFC 9068을 준수하는 액세스 토큰을 생성, 확인, 갱신할 수 있습니다. JWT는 일반적으로 연결된 애플리케이션 간의 클레임 또는 어설션을 공유하는 데 사용됩니다. JWT 형식으로 OAuthV2 액세스 토큰을 발급하는 것은 비공개 액세스 토큰을 발급하는 것의 대안입니다.

JWT에 대해 구성된 경우 OAuthV2 정책은 헤더, 페이로드, 점으로 구분된 서명으로 구성된 Base64로 인코딩된 JWT를 생성하고 반환합니다. 예를 들면 다음과 같습니다.

그림 1: 헤더, 페이로드, 점으로 구분된 서명으로 구성된 JWT 직렬화 형식

이러한 요소의 인코딩된 콘텐츠는 OAuthV2 정책을 구성하는 방법에 따라 달라집니다. 정책에서는 서명 알고리즘과 같은 매개변수와 제목 및 이름과 같은 페이로드 요소를 지정합니다. 예를 들어 헤더는 {"alg":"HS256","typ":"at+JWT"}로 디코딩되고 페이로드는 {"sub":"ABC1234567","iat":1516239022}로 디코딩될 수 있습니다.

헤더는 JWT에 서명하는 데 사용된 알고리즘을 나타내는 typ 클레임(항상 "at+JWT)과 alg 클레임을 지정합니다. Apigee는 RS(256,384,512) 및 HS(256,384,512)와 같은 RSA 및 HMAC 알고리즘을 지원합니다.

페이로드

페이로드는 항목에 대한 클레임으로 구성됩니다. 일부 클레임은 정책 구성에서 제공해야 하며 다른 클레임은 Apigee 런타임에서 자동으로 생성됩니다. 이 정책은 다음 클레임을 지원합니다.

클레임 설명 제공자
iss 토큰 발급기관입니다. 이 값은 (http|https)://{domain-name-for-proxy}/{proxy-basePath}로 설정됩니다. 예를 들어 https://api.mycompany.com/auth/v2와 같습니다. Apigee
sub 클라이언트 ID 또는 리소스 소유자의 ID입니다(비밀번호 또는 승인 부여 유형의 경우). 요청에 appEndUserId 매개변수가 제공되면 이 값은 리소스 소유자 ID로 사용됩니다. OAuthV2 정책의 <AppEndUser> 요소를 사용하여 이 값이 설정된 위치를 제어할 수 있습니다. API 개발자
jti 토큰을 고유하게 식별하기 위해 UUID 지원 임의 문자열로 표시된 고유 ID입니다. Apigee
exp 만료 시간, 즉 토큰이 유효하지 않은 것으로 간주되어야 하는 시간입니다. 값은 에포크 시간(초)으로 표현됩니다. Apigee
iat 발급 시간, 즉 토큰이 생성된 시간입니다. 값은 에포크 시간(초)으로 표현됩니다. Apigee
client_id 클라이언트 애플리케이션의 고유 식별자입니다. API 개발자
scope 토큰에 할당된 OAuth 범위입니다. OAuth 범위 작업도 참조하세요. API 개발자

서명

서명은 인코딩된 헤더, 페이로드, 보안 비밀/비공개 키, 알고리즘을 사용하여 생성됩니다. 서명은 토큰의 콘텐츠가 조작되지 않았음을 확인하는 데 사용됩니다.

JWT 형식 OAuth 2.0 액세스 토큰에 대한 자세한 내용은 IETF RFC 9068: OAuth 2.0 액세스 토큰용 JSON 웹 토큰(JWT) 프로필을 참조하세요.

기본 요건

이 문서에서는 OAuthV2 정책을 사용하여 OAuthV2 액세스 토큰을 생성하고 확인하는 방법을 이해하고 있다고 가정합니다. JWT 작업 또는 비공개 문자열 토큰을 만드는 기존 작업을 사용하는지에 관계없이 OAuthV2 정책의 기본적인 사용은 동일합니다. 지원되는 모든 OAuthV2 부여 유형과 함께 JWT 액세스 토큰을 사용할 수 있습니다. OAuth 2.0 소개도 참조하세요.

생성 중

GenerateJWTAccessToken 및 GenerateJWTAccessTokenImplicitGrant 작업을 사용하여 OAuthV2 정책으로 JWT 액세스 토큰을 생성합니다. 이러한 작업은 정책의 기존 GenerateAccessToken 및 GenerateAccessTokenImplicitGrant 작업과 유사합니다. 주요 차이점은 JWT 작업은 비공개 문자열 토큰 대신 JWT 형식의 액세스 토큰을 반환한다는 것입니다. OAuth 2.0 토큰 가져오기도 참조하세요.

다음 예시에서는 OAuthV2 정책에서 이러한 작업을 사용하는 방법을 보여줍니다. 이 예시에서는 client_credentials 부여 유형을 사용합니다. 하지만 이러한 작업을 통해 지원되는 부여 유형을 사용할 수 있습니다.

HMAC 알고리즘으로 서명된 JWT 형식 토큰 생성

HMAC(HS256/HS384/HS512) 알고리즘 중 하나로 <Algorithm> 요소를 지정합니다. <SecretKey>도 제공합니다. 다음 예시에서는 지정된 보안 비밀 키를 사용하여 HS512 알고리즘으로 서명된 JWT를 생성하도록 구성된 정책을 보여줍니다. 

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

RSA 알고리즘으로 서명된 JWT 형식 토큰 생성

<Algorithm> 요소에 RSA 알고리즘 중 하나(RS256/RS384/RS512 중 하나)를 지정하고 <PrivateKey> 요소에 비공개 키를 제공합니다. 다음 예시에서는 RS256 알고리즘을 사용하여 RSA 비공개 키로 서명된 JWT를 생성하도록 구성된 정책을 보여줍니다. 

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessToken</Operation>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

암시적 부여 유형으로 JWT 형식 토큰 생성

GenerateJWTAccessTokenImplicitGrant 작업은 암시적 부여 유형을 사용하여 JWT 액세스 토큰을 생성합니다. 토큰에 암시적 부여 유형을 자동으로 부여합니다. 따라서 <SupportedGrantTypes> 요소가 필요하지 않습니다. JWT이므로 <Algorithm> 요소가 필요합니다. 다음 예시는 RS256 알고리즘을 사용하는 방법을 보여줍니다. 따라서 <PrivateKey> 요소가 필요합니다. 암시적 부여 유형 사용도 참조하세요. 

<OAuthV2 name="generate-policy">
  <Operation>GenerateJWTAccessTokenImplicitGrant</Operation>
  <GenerateResponse enabled="true"/>
  <Algorithm>RS256</Algorithm>
  <PrivateKey>
    <Value ref="private.rsa-privatekey-1"/>
  </PrivateKey>
  <ExpiresIn ref="kvm.oauth.expires_in">3600000</ExpiresIn>
</OAuthV2>

확인 중

VerifyJWTAccessToken 작업을 사용하여 OAuthV2 정책으로 JWT 액세스 토큰을 확인합니다. 이 작업은 VerifyAccessToken 작업과 유사합니다. 차이점은 VerifyJWTAccessToken은 JWT 형식의 토큰에 적용되는 반면 VerifyAccessToken은 비공개 토큰에 적용된다는 점입니다.

HMAC 알고리즘으로 서명된 JWT 액세스 토큰 확인

다음 예시에서는 HS512 알고리즘으로 서명된 JWT 토큰을 확인하도록 OAuthV2 정책을 구성하는 방법을 보여줍니다. HMAC 알고리즘으로 VerifyJWTAccessToken 작업을 사용하는 경우 정책 구성은 <SecretKey> 요소를 사용하여 JWT에 서명하는 데 사용된 보안 비밀 키를 지정해야 합니다. 

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>HS512</Algorithm>
  <SecretKey>
    <Value ref="private.mysecretkey"/>
  </SecretKey>
</OAuthV2>

RSA 알고리즘으로 서명된 JWT 액세스 토큰 확인

다음 예시에서는 RS512 알고리즘으로 서명된 JWT 토큰을 확인하도록 OAuthV2 정책을 구성하는 방법을 보여줍니다. RSA 알고리즘으로 VerifyJWTAccessToken 작업을 사용하는 경우 정책 구성은 <PublicKey> 요소를 사용하여 JWT에 서명하는 데 사용된 비공개 키에 해당하는 공개 키를 지정해야 합니다. 

<OAuthV2 name="OAuthV2-verify-jwt">
  <Operation>VerifyJWTAccessToken</Operation>
  <Algorithm>RS512</Algorithm>
  <PublicKey>
    <Value ref="propertyset.non-secrets.rsa-publickey-1"/>
  </PublicKey>
</OAuthV2>

새로고침 중

RefreshJWTAccessToken 작업을 사용하여 JWT 액세스 토큰을 갱신합니다. 이 작업은 정책의 기존 RefreshAccessToken 작업과 유사합니다. 액세스 토큰 갱신도 참조하세요.

HMAC 서명된 액세스 토큰 갱신

다음 정책 샘플은 HMAC 알고리즘으로 서명된 JWT 토큰을 갱신하도록 OAuthV2 정책을 구성하는 방법을 보여줍니다. 이 경우에는 <SecretKey> 및 <Algorithm> 요소가 필요합니다.

갱신 작업의 응답은 새로 생성된 토큰의 응답과 유사합니다. 갱신 작업은 업데이트된 만료 시간이 있는 새 JWT 토큰을 생성하며 다른 클레임은 동일하게 유지합니다. 

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>HS512</Algorithm>
    <SecretKey>
      <Value ref="private.mysecretkey"/>
    </SecretKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

RSA 서명된 JWT 액세스 토큰 갱신

다음 정책 샘플은 RSA 알고리즘으로 서명된 JWT 토큰을 갱신하도록 OAuthV2 정책을 구성하는 방법을 보여줍니다. 액세스 토큰 갱신도 참조하세요. 

<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshJWTAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <Algorithm>RS256</Algorithm>
    <PrivateKey>
      <Value ref="private.rsa-privatekey-1"/>
    </PrivateKey>
    <RefreshTokenExpiresIn ref="kvm.oauth.expires_in">3600000</RefreshTokenExpiresIn>
</OAuthV2>

샘플 토큰 응답

생성 및 갱신 작업 모두 응답 본문은 다음 예시와 유사합니다. access_token은 직렬화된 JWT로 표시되고 갱신 토큰은 기존의 비공개 토큰입니다. 

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImF0K0pXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "token_type": "Bearer",
  "developer.email": "developer@example.org",
  "token_type": "Bearer",
  "issued_at": "1658352381404",
  "expires_in": 1799,
  "refresh_token": "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "refresh_token_issued_at": "1658352381404",
  "refresh_token_expires_in": 86399,
  "refresh_token_status": "Approved",
  "refresh_count": "0",
  "organization_name": "cerruti",
  "api_product_list_json": [ "TestingProduct" ]
}

필수 정책 요소 요약

다음 표에서는 앞의 예시에 사용된 JWT 관련 요소를 설명합니다.

요소 유형 참고
알고리즘 정적 값 토큰에 서명하는 데 사용되는 알고리즘을 지정합니다.
SecretKey 참조된 값 HMAC 알고리즘 HS(256/384/512)로 토큰을 확인하거나 서명하는 데 사용되는 보안 비밀 키를 제공합니다.
PrivateKey 참조된 값 토큰을 생성하는 데 사용된 비공개 키를 제공합니다. R알고리즘이 RSA 알고리즘 RS(256/384/512)인 경우에만 사용합니다.
PublicKey 참조된 값 토큰을 확인하는 데 사용되는 공개 키를 제공합니다. R알고리즘이 RSA 알고리즘 RS(256/384/512)인 경우에만 사용합니다.

지원되지 않는 정책 요소

다음 OAuthV2 정책 요소는 JWT 토큰 구성에서 지원되지 않습니다.

요소 참고
ExternalAuthorization JWT 액세스 토큰을 생성할 때 OAuthV2 정책은 클라이언트 ID 및 보안 비밀의 유효성을 검사합니다.
ExternalAccessToken JWT 액세스 토큰을 생성할 때 토큰은 Apigee에서 서명하며 클레임은 기본적으로 또는 정책 구성을 통해 Apigee에서 제공합니다. 이 정책은 ExternalRefreshToken을 지원하므로 마이그레이션 사용 사례를 지원할 수 있습니다.
RFCCompliantRequestResponse JWT 액세스 토큰의 생성 및 갱신은 기본적으로 RFC를 준수합니다.

사용 참고사항

  • 암호화된 JWT는 지원되지 않습니다.
  • JWT 액세스 토큰 외에도 정책 응답에는 갱신 토큰이 지원되는 부여 유형의 비공개 갱신 토큰이 포함됩니다. 비밀번호와 인증 코드 부여 유형만 갱신 토큰을 지원합니다.
  • OAuthV2 정책이 포함된 프록시로 전송된 요청에 승인 헤더를 포함합니다.
  • JWT 액세스 토큰은 취소할 수 없습니다. 생성된 JWT 토큰은 만료될 때까지 유효합니다. JWT 액세스 토큰과 연결된 갱신 토큰을 취소할 수 있습니다.
  • 액세스 토큰의 생성, 확인, 갱신은 Apigee에서 처리되어야 합니다. 공개 키 또는 보안 비밀 키에 액세스할 수 있는 외부 애플리케이션 또는 게이트웨이는 JWT의 콘텐츠를 디코딩할 수 있지만 외부 애플리케이션에는 client_id 클레임으로 식별되는 API 제품에 대한 정보가 없으므로 API 프록시 승인에서 역할을 수행할 수 없습니다.