OAuthV2 정책

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

Apigee Edge 문서 보기

대상

OAuthV2는 OAuth 2.0 부여 작업을 수행하기 위한 다각적인 정책입니다. Apigee에서 OAuth 2.0 엔드포인트를 구성하는 데 사용되는 기본 정책입니다.

이 정책은 확장 가능한 정책이며, 이 정책을 사용하면 Apigee 라이선스에 따라 비용 또는 사용률이 영향을 받을 수 있습니다. 정책 유형 및 사용 영향에 대한 자세한 내용은 정책 유형을 참조하세요.

Apigee의 OAuth에 대한 자세한 내용은 OAuth 홈페이지를 참조하세요. 리소스, 샘플, 동영상 등의 링크를 제공합니다.

샘플

VerifyAccessToken

이 OAuthV2 정책 구성은 VerifyAccessToken 작업을 통해 Apigee에 제출된 액세스 토큰이 유효한지 확인합니다. 이 정책 작업이 트리거되면 Apigee는 요청에서 유효한 액세스 토큰을 찾습니다. 액세스 토큰이 유효하면 요청은 진행하도록 허용됩니다. 유효하지 않은 경우 모든 처리가 중지되고 응답에서 오류가 반환됩니다.

<OAuthV2 name="OAuthV2-Verify-Access-Token">
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

클라이언트 애플리케이션은 토큰과 함께 요청을 전송해야 합니다. curl 사용 예시는 다음과 같습니다.

$ curl https://API_ENDPOINT/weather/forecastrss?w=12797282 \
  -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z"

여기서 API_ENDPOINT는 Apigee 시스템에 구성된 API에 액세스하는 데 사용되는 도메인입니다.

기본적으로 OAuthV2 정책은 Authorization 헤더에서 액세스 토큰을 추출하고 Bearer 프리픽스를 제거합니다. AccessToken 구성 요소를 사용하여 이 기본 동작을 변경할 수 있습니다.

GenerateAccessToken

액세스 토큰 생성

지원되는 각 부여 유형에 대해 액세스 토큰을 요청하는 방법을 보여주는 예시는 OAuth 2.0 토큰 가져오기를 참조하세요. 이 주제에는 다음 작업의 예시가 포함됩니다.

참고: OAuthV2 정책은 RFC를 준수하지 않는 특정 응답 요소를 반환합니다. 예를 들어 정책은 토큰 속성 "token_type":"BearerToken"을 반환합니다. 여기서 규정을 준수하는 토큰 속성은 "token_type":"Bearer"입니다. 이러한 규정을 준수하지 않는 응답 요소에 대한 자세한 내용은 RFC를 준수하지 않는 동작을 참조하세요.

GenerateAuthorizationCode

승인 코드 생성

승인 코드를 요청하는 방법의 예시는 승인 코드 요청을 참조하세요.

RefreshAccessToken

액세스 토큰 새로고침

갱신 토큰을 사용하여 액세스 토큰을 요청하는 방법을 보여주는 예시는 액세스 토큰 새로고침을 참조하세요.

JWT 액세스 토큰

JWT 액세스 토큰 생성, 확인, 갱신 방법을 보여주는 예시는 JWT 액세스 토큰 사용을 참조하세요.

응답 흐름 토큰

응답 흐름에서 액세스 토큰 생성

응답 흐름에서 액세스 토큰을 생성해야 하는 경우도 있습니다. 예를 들어 백엔드 서비스에서 수행된 몇 가지 커스텀 검증에 대한 응답으로 이 작업을 수행할 수 있습니다. 이 예시의 사용 사례에서는 암시적 부여 유형을 배제하며 액세스 토큰과 갱신 토큰을 모두 필요로 합니다. 이 경우 비밀번호 부여 유형을 사용하여 토큰을 생성합니다. 나중에 볼 수 있듯이 이 작업을 수행하기 위한 비결은 자바스크립트 정책과 함께 승인 요청 헤더를 전달하는 것입니다.

먼저 샘플 정책을 살펴보겠습니다.

<OAuthV2 enabled="true" continueOnError="false" async="false" name="generateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <AppEndUser>Doe</AppEndUser>
    <UserName>jdoe</UserName>
    <PassWord>jdoe</PassWord>
    <GrantType>grant_type</GrantType>
    <ClientId>a_valid_client_id</ClientId>
    <SupportedGrantTypes>
        <GrantType>password</GrantType>
    </SupportedGrantTypes>
</OAuthV2>

응답 흐름에 이 정책을 입력하면 올바른 로그인 매개변수가 정책에 지정되어 있더라도 401 UnAuthorized 오류와 함께 실패합니다. 이 문제를 해결하려면 승인 요청 헤더를 설정해야 합니다.

승인 헤더에는 Base64로 인코딩된 client_id:client_secret이 있는 기본 액세스 스키마가 포함되어야 합니다.

다음과 같이 이 헤더를 OAuthV2 정책 바로 앞에 위치한 자바스크립트 정책으로 추가할 수 있습니다. 'local_clientid' 및 'local_secret' 컨텍스트 변수는 이전 단계의 흐름에서 설정되어 사용할 수 있어야 합니다.

var clientId = context.getVariable("local_clientid");
var clientSecret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+ CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(clientId + ':' + clientSecret)));

기본 사용자 인증 정보 인코딩도 참조하세요.

요소 참조

정책 참조는 OAuthV2 정책의 요소 및 속성을 설명합니다.

아래의 샘플 정책은 여러 가지 가능한 구성 중 하나입니다. 이 샘플은 GenerateAccessToken 작업에 구성된 OAuthV2 정책을 보여줍니다. 필수 요소와 선택적 요소가 포함됩니다. 자세한 내용은 이 섹션의 요소 설명을 참조하세요.

<OAuthV2 name="GenerateAccessToken">
  <!-- This policy generates an OAuth 2.0 access token using the client_credentials grant type -->
  <Operation>GenerateAccessToken</Operation>
  <!-- This is in millseconds, so expire in an hour -->
  <ExpiresIn>3600000</ExpiresIn>
  <SupportedGrantTypes>
    <GrantType>client_credentials</GrantType>
  </SupportedGrantTypes>
  <GrantType>request.queryparam.grant_type</GrantType>
  <GenerateResponse/>
</OAuthV2>

<OAuthV2> 속성

<OAuthV2 async="false" continueOnError="false" enabled="true" name="MyOAuthPolicy">

다음 표는 모든 정책 상위 요소의 공통 속성에 대해 설명합니다.

속성	설명	기본값	Presence
`name`	정책의 내부 이름입니다. `name` 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다. 원하는 경우 `<DisplayName>` 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.	해당 사항 없음	필수
`continueOnError`	정책이 실패할 경우 오류가 반환되도록 하려면 `false`로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다. 정책이 실패해도 흐름 실행이 계속되도록 하려면 `true`로 설정합니다. 참조: 오류 규칙은 오류 상태(continueOnError)에서만 트리거됨 현재 흐름 내에서 오류 처리	false	선택사항
`enabled`	정책을 시행하려면 `true`로 설정합니다. 정책을 중지하려면 `false`로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.	true	선택사항
`async`	이 속성은 지원이 중단되었습니다.	false	지원 중단됨

<DisplayName> 요소

name 속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.

<DisplayName>Policy Display Name</DisplayName>

기본값

기본값	해당 사항 없음 이 요소를 생략하면 정책 `name` 속성 값이 사용됩니다.
Presence	선택사항
유형	문자열

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.

Presence 선택사항

유형 문자열

<AccessToken> 요소

<AccessToken>request.header.access_token</AccessToken>

기본적으로 Operation이 VerifyAccessToken이면 정책은 액세스 토큰이 Authorization 헤더에 Bearer 토큰으로 전송될 것으로 예상합니다. 즉, 프리픽스 'Bearer'와 빈 공백 1개가 뒤에 옵니다. 확인할 액세스 토큰이 포함된 변수의 이름을 지정하여 이 요소를 사용하여 기본값을 변경할 수 있습니다. 이 요소를 사용하면 정책이 기본적으로 변수 콘텐츠에서 프리픽스를 찾지 않습니다. 정책이 프리픽스를 찾도록 지정하려면 AccessTokenPrefix 요소도 사용합니다.

예를 들면 다음과 같습니다.

정책 구성이 다음과 같은 경우:

  <OAuthV2 name="OAuthV2-Verify-Access-Token-in-Header">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.header.access_token</AccessToken>
  </OAuthV2>

curl을 사용하여 토큰을 전달하려면 다음을 사용하면 됩니다.

  curl https://API_ENDPOINT/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"

정책 구성이 다음과 같은 경우:

  <OAuthV2 name="OAuthV2-Verify-Access-Token-in-QueryParam">
      <Operation>VerifyAccessToken</Operation>
      <AccessToken>request.queryparam.token</AccessToken>
  </OAuthV2>

curl을 사용하여 토큰을 전달하려면 다음을 사용하면 됩니다.

  curl "https://API_ENDPOINT/oauth2/validate?token=Rft3dqrs56Blirls56a"

여기서 API_ENDPOINT는 Apigee 시스템에 구성된 API에 액세스하는 데 사용되는 도메인입니다.

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열
유효한 값:	모든 변수 이름
작업과 함께 사용:	VerifyAccessToken

<AccessTokenPrefix> 요소

<AccessTokenPrefix>Prefix</AccessTokenPrefix>

기본적으로 Operation이 VerifyAccessToken이면 정책은 액세스 토큰이 Authorization 헤더에 Bearer 토큰으로 전송될 것으로 예상합니다. 즉, 프리픽스 'Bearer'와 빈 공백 1개가 뒤에 옵니다. AccessToken 요소를 사용하여 수신 액세스 토큰에 다른 위치를 지정하는 경우 이 요소(AccessTokenPrefix)를 사용하여 다른 비표준 프리픽스를 지정할 수도 있습니다.

예를 들어 다음과 같이 지정하는 경우,

<OAuthV2 name="OAuthV2-Verify-Access-Token-Alternative-Header">
    <Operation>VerifyAccessToken</Operation>
    <AccessToken>request.header.token</AccessToken>
    <AccessTokenPrefix>KEY</AccessTokenPrefix>
</OAuthV2>

정책은 token 요청 헤더에서 인바운드 액세스 토큰을 다음과 같이 추출합니다. 이러한 방식으로 헤더가 단어 'KEY'로 시작하고 그 뒤에 공백이 있는 경우 정책은 해당 프리픽스와 공백을 삭제하고 나머지 값을 액세스 토큰으로 해석합니다. 지정된 프리픽스가 헤더에 없으면 정책에서 오류가 발생합니다.

AccessToken 요소를 지정하고 AccessTokenPrefix 요소를 지정하지 않으면 정책은 AccessToken 요소 내에 지정된 변수의 전체 값을 액세스 토큰으로 해석합니다.

이 요소는 AccessToken 요소도 사용되는 경우에만 적용됩니다.

기본값:	-none-
Presence:	선택사항
유형:	문자열
유효한 값:	모든 문자열
작업과 함께 사용:	VerifyAccessToken

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

JWT 액세스 토큰에 서명하는 데 사용되는 암호화 알고리즘을 지정합니다. RSA(RS*) 알고리즘은 공개/보안 비밀 키 쌍을 사용하지만 HMAC(HS*) 알고리즘은 공유 보안 비밀을 사용합니다. 이 요소는 GenerateJWTAccessToken, VerifyJWTAccessToken, RefreshJWTAccessToken 작업에 필요합니다.

기본값	해당 사항 없음
Presence	`GenerateJWTAccessToken`, `VerifyJWTAccessToken`, `RefreshJWTAccessToken` 작업을 사용할 때 필요합니다.
유형	문자열
유효한 값	HS256, HS384, HS512, RS256, RS384, RS512

<AppEndUser> 요소

<AppEndUser>request.queryparam.app_enduser</AppEndUser>

앱 최종 사용자 ID를 승인 서버로 전송해야 하는 경우 이 요소를 사용하면 Apigee에서 최종 사용자 ID를 찾을 위치를 지정할 수 있습니다. 예를 들어 쿼리 매개변수 또는 HTTP 헤더로 전송될 수 있습니다.

예를 들어 request.queryparam.app_enduser는 AppEndUser가 쿼리 매개변수(예: ?app_enduser=ntesla@theramin.com)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 AppEndUser를 요구하려면 이 값을 request.header.app_enduser으로 설정합니다.

이 설정을 제공하면 액세스 토큰에 앱 최종 사용자 ID를 포함할 수 있습니다. 이 기능은 최종 사용자 ID로 OAuth 2.0 액세스 토큰을 검색하거나 취소할 수 있는 경우에 유용합니다. 자세한 내용은 최종 사용자 ID, 앱 ID 또는 둘 다로 OAuth 2.0 액세스 토큰의 검색 및 취소 사용 설정을 참조하세요.

기본값:	해당 사항 없음
Presence:	선택사항
유형:	문자열
유효한 값:	런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:	authorization_code 암시적 비밀번호 client_credentials

<Attributes/Attribute>

<Attributes>
    <Attribute name="attr_name1" ref="flow.variable" display="true|false">value1</Attribute>
    <Attribute name="attr_name2" ref="flow.variable" display="true|false">value2</Attribute>
</Attributes>

이 요소를 사용하여 액세스 토큰 또는 승인 코드에 맞춤 속성을 추가합니다. 예를 들어 런타임 시 추출하고 확인할 수 있는 사용자 ID 또는 세션 식별자를 액세스 토큰에 삽입할 수 있습니다.

이 요소를 사용하면 흐름 변수 또는 리터럴 문자열에서 값을 지정할 수 있습니다. 변수와 문자열을 모두 지정하면 흐름 변수에 지정된 값이 사용됩니다. 변수를 확인할 수 없는 경우 문자열이 기본값입니다.

이 요소 사용에 대한 자세한 내용은 토큰 및 승인 코드 맞춤설정을 참조하세요.

응답에 커스텀 속성 표시 또는 숨기기

이 정책의 GenerateResponse 요소를 true로 설정하면 설정한 모든 맞춤 속성을 포함하여 토큰의 전체 JSON 표현이 반환됩니다. 경우에 따라 맞춤 속성 중 일부 또는 전체를 숨겨 클라이언트 앱에 표시되지 않도록 할 수 있습니다.

기본적으로 커스텀 속성이 응답에 표시됩니다. 이를 숨기려면 display 매개변수를 false로 설정하면 됩니다. 예를 들면 다음과 같습니다.

<Attributes>
    <Attribute name="employee_id" ref="employee.id" display="false"/>
    <Attribute name="employee_name" ref="employee.name" display="false"/>
</Attributes>

display 속성의 값은 유지되지 않습니다. 생성된 응답에서 숨기려는 커스텀 속성이 포함된 액세스 토큰을 생성한다고 가정해 보겠습니다. display=false를 설정하면 이 목표를 달성할 수 있습니다. 하지만 나중에 갱신 토큰을 사용하여 새 액세스 토큰을 생성하면 액세스 토큰의 원래 커스텀 속성이 갱신 토큰 응답에 표시됩니다. 이는 Apigee가 액세스 토큰 생성 정책에서 원래 display 속성이 false로 설정되었음을 기억하지 않기 때문입니다. 커스텀 속성은 단순히 액세스 토큰 메타데이터의 일부입니다.

승인 코드에 맞춤 속성을 추가하면 동일한 동작이 표시됩니다. 해당 코드를 사용하여 액세스 토큰이 생성되면 해당 맞춤 속성이 액세스 토큰 응답에 표시됩니다. 다시 한번 말씀드리지만, 이는 의도한 동작이 아닐 수도 있습니다.

이러한 경우 맞춤 속성을 숨기는 방법은 다음과 같습니다.

갱신 토큰 정책의 맞춤 속성을 명시적으로 재설정하고 display를 false로 설정합니다. 이 경우에는 GetOAuthV2Info 정책을 사용하여 원래 액세스 토큰에서 원래 맞춤 값을 검색해야 할 수 있습니다.
자바스크립트 후처리 정책을 사용하여 응답에서 보고 싶지 않은 맞춤 속성을 수동으로 추출합니다.

토큰 및 승인 코드 맞춤설정도 참조하세요.

기본값:	`N/A`
Presence:	선택사항
유효한 값:	`name` -속성 이름 `ref` - 속성의 값. 흐름 변수에서 가져올 수 있습니다. `display` - (선택사항) 응답에 맞춤 속성이 표시되는지 여부를 지정할 수 있습니다. `true`인 경우 맞춤 속성이 응답에 표시됩니다(`GenerateResponse`도 사용 설정된 경우). `false`이면 맞춤 속성이 응답에 포함되지 않습니다. 기본값은 `true`입니다. 응답에서 맞춤 속성 표시 또는 숨기기를 참조하세요.
부여 유형과 함께 사용:	authorization_code 암시적 비밀번호 client_credentials refresh_token GenerateAuthorizationCode 작업에도 사용할 수 있습니다.

<CacheExpiryInSeconds> 요소

<CacheExpiryInSeconds ref="request.queryparam.cache_expiry">Value 1</CacheExpiryInSeconds>

이 요소는 캐시에 TTL을 적용하여 캐시된 액세스 토큰 만료 기간을 맞춤설정할 수 있습니다. 지원되는 범위는 1~180초입니다. 흐름 변수와 기본 변수를 제공할 수 있습니다. 제공된 경우 흐름 변수 값이 지정된 기본값보다 우선 적용됩니다.

이 요소는 VerifyAccessToken 작업에만 사용할 수 있습니다.

기본값	해당 사항 없음 이 요소를 생략하면 캐시된 액세스 토큰의 기본 만료 기간은 180초입니다.
Presence	선택사항
유형	정수
유효한 값	0이 아닌 양의 정수. 만료 시간을 초 단위로 지정합니다.

속성

다음 표에서는 <CacheExpiryInSeconds> 요소의 속성을 설명합니다.

속성	설명	기본값	Presence
ref	캐시 만료 값을 포함하는 흐름 변수에 대한 참조(초 단위)입니다. 제공된 경우 흐름 변수 값이 지정된 기본값보다 우선 적용됩니다.	해당 사항 없음	선택사항

속성

설명

기본값

Presence

ref

캐시 만료 값을 포함하는 흐름 변수에 대한 참조(초 단위)입니다.

제공된 경우 흐름 변수 값이 지정된 기본값보다 우선 적용됩니다.

해당 사항 없음

선택사항

<ClientId> 요소

<ClientId>request.formparam.client_id</ClientId>

경우에 따라 클라이언트 앱은 클라이언트 ID를 승인 서버로 전송해야 합니다. 이 요소는 Apigee가 흐름 변수 request.formparam.client_id에서 클라이언트 ID를 찾아야 한다고 지정합니다. ClientId를 다른 변수로 설정하면 지원되지 않습니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.client_id (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	흐름 변수: `request.formparam.client_id`
부여 유형과 함께 사용:	authorization_code 비밀번호 암시적 client_credentials GenerateAuthorizationCode 작업에도 사용할 수 있습니다.

<Code> 요소

<Code>request.queryparam.code</Code>

승인 부여 유형 흐름에서 클라이언트는 승인 코드를 승인 서버(Apigee 서버)에 제출해야 합니다. 이 요소를 사용하면 Apigee가 승인 코드를 찾을 위치를 지정할 수 있습니다. 예를 들어 쿼리 매개변수, HTTP 헤더 또는 양식 매개변수(기본값)로 전송될 수 있습니다.

변수 request.queryparam.auth_code는 승인 코드가 쿼리 매개변수(예: ?auth_code=AfGlvs9)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 승인 코드를 요구하려면 이 값을 request.header.auth_code으로 설정합니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.code (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:	authorization_code

<ExpiresIn> 요소

<ExpiresIn>10000</ExpiresIn>

액세스 토큰 및 승인 코드의 만료 시간을 밀리초 단위로 적용합니다. (갱신 토큰의 경우 <RefreshTokenExpiresIn> 사용) 만료 시간 값은 시스템에서 생성된 값에 <ExpiresIn> 값을 더한 값입니다. <ExpiresIn>이 -1로 설정된 경우 토큰 또는 코드는 최대 OAuth 액세스 토큰 만료에 따라 만료됩니다. <ExpiresIn>을 지정하지 않으면 시스템은 시스템 수준에서 구성된 기본값을 적용합니다.

만료 시간은 하드 코딩된 기본값을 사용하거나 흐름 변수를 참조하여 런타임 시 설정할 수도 있습니다. 예를 들어 키 값 맵에 토큰 만료 값을 저장하고 검색하여 변수에 할당하고 정책에서 참조할 수 있습니다. 예: kvm.oauth.expires_in.

Apigee는 항목이 액세스된 후 180초 이상 다음 항목을 캐시에 보관합니다.

OAuth 액세스 토큰. 즉, OAuth v2 정책의 ExpiresIn 요소는 180초 이내에 액세스 토큰을 만료시킬 수 없습니다.
키 관리 서비스(KMS) 항목(앱, 개발자, API 제품)
OAuth 토큰 및 KMS 항목의 맞춤 속성입니다.

다음 스탠자는 흐름 변수와 기본값을 지정합니다. 흐름 변수 값은 지정된 기본값보다 우선 적용됩니다.

<ExpiresIn ref="kvm.oauth.expires_in">
    3600000 <!--default value in milliseconds-->
</ExpiresIn>

Apigee는 토큰이 생성된 후 강제로 만료시키는 방법을 지원하지 않습니다. 강제로 토큰을 만료시켜야 하는 경우(예: 조건에 따라) 이 Apigee 커뮤니티 게시물에서 가능한 해결책을 확인할 수 있습니다.

기본적으로 만료된 액세스 토큰은 만료 3일 후에 Apigee 시스템에서 자동으로 삭제됩니다. 액세스 토큰 삭제도 참조하세요.

기본값:	지정되지 않은 경우 시스템은 시스템 수준에서 구성된 기본값을 적용합니다.
Presence:	선택사항
유형:	정수
유효한 값:	0이 아닌 양의 정수. 만료 시간을 밀리초로 지정합니다. 이 요소의 값은 밀리초 단위이지만 토큰의 `expires_in` 속성과 `expires_in` 흐름 변수에 설정된 값은 초 단위로 표현됩니다. -1로 설정하면 최대 OAuth 액세스 토큰 만료에 따라 만료됩니다. 참고: 다른 음수 정수 또는 0을 지정하면 배포 오류가 발생합니다.
부여 유형과 함께 사용:	authorization_code 암시적 비밀번호 client_credentials refresh_token GenerateAuthorizationCode 작업에도 사용됩니다.

참고: ExpiresIn이 -1로 설정된 경우 생성된 토큰에 다음 만료 값이 표시됩니다.

"expires_in" :
  "0"

<ExternalAccessToken> 요소

<ExternalAccessToken>request.queryparam.external_access_token</ExternalAccessToken>

외부 액세스 토큰(Apigee에서 생성되지 않은 액세스 토큰)을 찾을 위치를 Apigee에 알려줍니다.

변수 request.queryparam.external_access_token은 외부 액세스 토큰이 쿼리 매개변수(예: ?external_access_token=12345678)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 외부 액세스 토큰을 요구하려면 이 값을 request.header.external_access_token으로 설정합니다. 타사 OAuth 토큰 사용도 참조하세요.

<ExternalAuthorization> 요소

<ExternalAuthorization>true</ExternalAuthorization>

이 요소가 false이거나 존재하지 않는 경우 Apigee는 일반적으로 Apigee 승인 저장소에 대해 client_id 및 client_secret을 확인합니다. 타사 OAuth 토큰으로 작업하려는 경우 이 요소를 사용합니다. 이 요소 사용에 대한 자세한 내용은 타사 OAuth 토큰 사용을 참조하세요.

기본값:	false
Presence:	선택사항
유형:	불리언
유효한 값:	true 또는 false
부여 유형과 함께 사용:	authorization_code 비밀번호 client_credentials

<ExternalAuthorizationCode> 요소

<ExternalAuthorizationCode>request.queryparam.external_auth_code</ExternalAuthorizationCode>

Apigee에 외부 승인 코드(Apigee에서 생성되지 않은 승인 코드)를 찾을 위치를 알려줍니다.

변수 request.queryparam.external_auth_code는 외부 인증 코드가 쿼리 매개변수(예: ?external_auth_code=12345678)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 외부 인증 코드를 요구하려면 이 값을 request.header.external_auth_code로 설정합니다. 타사 OAuth 토큰 사용도 참조하세요.

<ExternalRefreshToken> 요소

<ExternalRefreshToken>request.queryparam.external_refresh_token</ExternalRefreshToken>

Apigee에 외부 갱신 토큰(Apigee에서 생성되지 않은 갱신 토큰)을 찾을 위치를 알립니다.

request.queryparam.external_refresh_token 변수는 외부 갱신 토큰이 쿼리 매개변수(예: ?external_refresh_token=12345678)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 외부 갱신 토큰을 요구하려면 이 값을 request.header.external_refresh_token으로 설정합니다. 타사 OAuth 토큰 사용도 참조하세요.

<GenerateResponse> 요소

<GenerateResponse enabled='true'/>

true로 설정하거나 enabled 속성을 생략하면 정책이 응답을 생성하고 반환합니다. 예를 들어 GenerateAccessToken의 경우 응답은 다음과 같습니다.

{
  "issued_at" : "1467841035013",
  "scope" : "read",
  "application_name" : "e31b8d06-d538-4f6b-9fe3-8796c11dc930",
  "refresh_token_issued_at" : "1467841035013",
  "status" : "approved",
  "refresh_token_status" : "approved",
  "api_product_list" : "[Product1, nhl_product]",
  "expires_in" : "1799",
  "developer.email" : "edward@slalom.org",
  "token_type" : "BearerToken",
  "refresh_token" : "rVSmm3QaNa0xBVFbUISz1NZI15akvgLJ",
  "client_id" : "Adfsdvoc7KX5Gezz9le745UEql5dDmj",
  "access_token" : "AnoHsh2oZ6EFWF4h0KrA0gC5og3a",
  "organization_name" : "cerruti",
  "refresh_token_expires_in" : "0",
  "refresh_count" : "0"
}

false로 설정하거나 <GenerateResponse> 요소를 생략하면 응답이 전송되지 않습니다. 대신 흐름 변수 집합이 정책 함수와 관련된 값으로 채워집니다. 예를 들어 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code라는 흐름 변수는 새로 발급된 인증 코드로 채워집니다. expires_in은 응답에서 초 단위로 표현됩니다.

기본값:	true
Presence:	선택사항
유형:	문자열
유효한 값:	true 또는 false
부여 유형과 함께 사용:	암시적 비밀번호 client_credentials refresh_token GenerateAuthorizationCode 작업에도 사용할 수 있습니다.

<GenerateErrorResponse> 요소

<GenerateErrorResponse enabled='true'/>

true로 설정하면 ContinueOnError 속성이 true로 설정된 경우 정책이 응답을 생성하고 반환합니다. false(기본값)이면 응답이 전송되지 않습니다. 대신 흐름 변수 집합이 정책 함수와 관련된 값으로 채워집니다.

기본값:	false
Presence:	선택사항
유형:	문자열
유효한 값:	true 또는 false
부여 유형과 함께 사용:	암시적 비밀번호 client_credentials refresh_token GenerateAuthorizationCode 작업에도 사용할 수 있습니다.

<GrantType>

<GrantType>request.queryparam.grant_type</GrantType>

요청에 전달되는 권한 부여 매개변수를 찾을 위치를 정책에 알립니다. OAuth 2.0 사양에 따라 부여 유형에는 액세스 토큰 및 승인 코드에 대한 요청이 제공되어야 합니다. 변수는 헤더, 쿼리 매개변수, 양식 매개변수(기본값)일 수 있습니다.

예를 들어 request.queryparam.grant_type은 비밀번호가 쿼리 매개변수(예: ?grant_type=password)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 부여 유형을 요청하려면 이 값을 request.header.grant_type로 설정합니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.grant_type (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	위에 설명된 대로 변수
부여 유형과 함께 사용:	authorization_code 비밀번호 암시적 client_credentials refresh_token

<Operation> 요소

<Operation>GenerateAuthorizationCode</Operation>

정책에 의해 실행되는 OAuth 2.0 작업입니다.

기본값:	`<Operation>`을 지정하지 않으면 Apigee에서 `<SupportedGrantTypes>` 목록을 확인합니다. 이러한 부여 유형에 대한 작업만 성공합니다. 즉, `<SupportedGrantTypes>` 목록에서 `<GrantType>`을 지정하면 `<Operation>`을 생략할 수 있습니다. `<Operation>` 또는 `<SupportedGrantTypes>`도 지정되지 않은 경우 기본 부여 유형은 authorization_code입니다. 즉, 승인 코드 부여 유형 요청은 성공하지만 나머지는 실패합니다.
Presence:	선택사항
유형:	문자열
유효한 값:	`GenerateAccessToken` - 액세스 토큰을 생성합니다. OAuth 2.0 토큰 가져오기도 참조하세요. `GenerateAccessTokenImplicitGrant` - 암시적 부여 유형의 액세스 토큰을 생성합니다. OAuth 2.0 토큰 가져오기도 참조하세요. `GenerateAuthorizationCode` - 인증 코드를 생성합니다. 승인 코드 부여 유형과 함께 사용됩니다. OAuth 2.0 토큰 가져오기도 참조하세요. `RefreshAccessToken` - 갱신 토큰을 새 액세스 토큰으로 교환합니다. OAuth 2.0 토큰 가져오기도 참조하세요. `VerifyAccessToken` - 요청에서 전송된 액세스 토큰이 유효한지 확인합니다. 위의 VerifyAccessToken 샘플 및 액세스 토큰 확인을 참조하세요. `InvalidateToken` - 액세스 토큰을 취소합니다. 토큰이 취소된 후에는 클라이언트가 해당 토큰을 사용하여 보호되는 API를 호출할 수 없습니다. 액세스 토큰 승인 및 취소도 참조하세요. 경고: OAuth 토큰은 3분(180초) 동안 캐시됩니다. 따라서 취소된 토큰은 캐시 한도가 만료될 때까지 최대 3분 동안 성공할 수 있습니다. `ValidateToken` - 이전에 취소된 액세스 토큰을 복원하거나 '승인'합니다. 액세스 토큰 승인 및 취소도 참조하세요. 추가 JWT 액세스 토큰 작업 비공개 문자열 토큰 대신 JWT 액세스 토큰을 사용하려는 경우 다음 작업을 사용하여 JWT 토큰을 생성하고 검증할 수도 있습니다. 자세한 내용은 JWT OAuth 토큰 작업 사용을 참조하세요. `GenerateJWTAccessToken` - 서명된 JWT가 포함된 액세스 토큰을 생성합니다. JWT 액세스 토큰 생성을 참조하세요. `GenerateJWTAccessTokenImplicitGrant` - 암시적 부여 유형에 대해 서명된 JWT가 포함된 액세스 토큰을 생성합니다. JWT 액세스 토큰 생성을 참조하세요. `VerifyJWTAccessToken` - 서명된 JWT 액세스 토큰을 확인합니다. JWT 액세스 토큰 확인도 참조하세요. `RefreshJWTAccessToken` - 갱신 토큰을 새 JWT 액세스 토큰으로 교환합니다. JWT 액세스 토큰 갱신도 참조하세요.

<PassWord> 요소

<PassWord>request.queryparam.password</PassWord>

이 요소는 비밀번호 부여 유형에서만 사용됩니다. 비밀번호 부여 유형을 사용하면 사용자 인증 정보(비밀번호 및 사용자 이름)를 OAuthV2 정책에서 사용할 수 있어야 합니다. <PassWord> 및 <UserName> 요소는 Apigee가 이러한 값을 찾을 수 있는 변수를 지정하는 데 사용됩니다. 이러한 요소가 지정되지 않으면 정책은 기본적으로 username 및 password라는 형식 매개변수에서 값을 찾으려고 합니다. 값을 찾을 수 없으면 정책에서 오류가 발생합니다. <PassWord> 및 <UserName> 요소를 사용하여 사용자 인증 정보가 포함된 모든 흐름 변수를 참조할 수 있습니다.

예를 들어 쿼리 매개변수를 사용하여 토큰 요청에 비밀번호를 전달하고 다음과 같은 요소를 설정할 수 있습니다. <PassWord>request.queryparam.password</PassWord>. HTTP 헤더에서 비밀번호를 요구하려면 이 값을 request.header.password로 설정합니다.

OAuthV2 정책은 이러한 사용자 인증 정보 값으로 어떠한 조치도 취하지 않습니다. Apigee는 단순히 해당 값이 존재하는지 확인만 합니다. 토큰 생성 정책을 실행하기 전에 값 요청을 검색하여 ID 공급업체로 전송하는 것은 API 개발자의 책임입니다.

OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.password (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	런타임에 정책에 사용할 수 있는 흐름 변수입니다.
부여 유형과 함께 사용:	비밀번호

<PrivateKey>/<Value>

<PrivateKey>
  <Value ref="variable-name-here"/>
</PrivateKey>

RSA 알고리즘으로 JWT 형식의 액세스 토큰을 확인하거나 서명하는 데 사용되는 비공개 키를 제공합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다. Algorithm 요소 값이 RS256, RS384, RS512 중 하나인 경우에만 사용합니다. 자세한 내용은 JWT OAuth 토큰 작업 사용을 참조하세요.

기본값	해당 사항 없음
Presence	`Algorithm` 요소 값이 HS256, HS384 또는 HS512 중 하나인 경우 필요합니다.
유형	문자열
유효한 값	PEM 인코딩 RSA 비공개 키 값을 나타내는 문자열을 포함하는 흐름 변수입니다.

<PublicKey>/<Value>

<PublicKey>
   <Value ref="variable-name-here"/>
</PublicKey>

RSA 알고리즘으로 서명된 JWT 형식 액세스 토큰에서 서명을 확인하는 데 사용되는 공개 키 또는 공개 인증서를 지정합니다. ref 속성을 사용하여 흐름 변수의 키/인증서를 전달합니다. Algorithm 요소 값이 RS256, RS384, RS512 중 하나인 경우에만 사용합니다.

기본값	해당 사항 없음
Presence	RSA 알고리즘으로 서명된 JWT를 확인하려면 인증서, JWKS 또는 값 요소를 사용해야 합니다.
유형	문자열
유효한 값	흐름 변수 또는 문자열입니다.

<RedirectUri> 요소

<RedirectUri>request.queryparam.redirect_uri</RedirectUri>

Apigee가 요청에서 redirect_uri 매개변수를 찾아야 하는 위치를 지정합니다.

리디렉션 URI 정보

리디렉션 URI는 승인 코드 및 암시적 부여 유형과 함께 사용됩니다. 리디렉션 URI는 승인 코드(승인 코드 부여 유형의 경우) 또는 액세스 토큰(암시적 부여 유형의 경우)을 보내는 위치를 승인 서버(Apigee)에 알립니다. 이 매개변수가 필요한 경우 언제 선택적인지 및 사용 방법을 이해하는 것이 중요합니다.

(필수사항) 콜백 URL이 요청의 클라이언트 키와 연결된 개발자 앱에 등록되어 있으며 redirect_uri가 요청에 있는 경우 URL과 URI는 정확히 일치해야 합니다. 일치하지 않으면 오류가 반환됩니다. Apigee에 개발자 앱을 등록하고 콜백 URL을 지정하는 방법은 앱 등록 및 API 키 관리를 참조하세요.

참고: Apigee가 '콜백 URL'과 'redirect_uri' (정확히 일치하지 않음) 간의 정확한 일치(전방 일치가 아님)를 확인하려면 조직에서 features.isStrictOAuthUriValidation = true 속성을 설정합니다. 기본값은 false입니다(전방 일치).
이 속성을 사용 설정하려면 Google Cloud Customer Care에 문의하세요.
(선택사항) 콜백 URL이 등록되었고 요청에서 redirect_uri가 누락된 경우 Apigee는 등록된 콜백 URL로 리디렉션됩니다.
(필수사항) 콜백 URL이 등록되지 않은 경우 redirect_uri는 필수입니다. 이 경우 Apigee는 모든 URL을 허용합니다. 이 경우 보안 문제가 발생할 수 있으므로 신뢰할 수 있는 클라이언트 앱에서만 사용해야 합니다. 클라이언트 앱을 신뢰할 수 없는 경우 항상 콜백 URL 등록을 요구하는 것이 좋습니다.

이 매개변수는 쿼리 매개변수 또는 헤더로 전송할 수 있습니다. 변수 request.queryparam.redirect_uri는 RedirectUri가 쿼리 매개변수(예: ?redirect_uri=login.myapp.com)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 RedirectUri를 요구하려면 이 값을 request.header.redirect_uri로 설정합니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.redirect_uri (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:	authorization_code 암시적 GenerateAuthorizationCode 작업에도 사용됩니다.

<RefreshToken> 요소

<RefreshToken>request.queryparam.refreshtoken</RefreshToken>

갱신 토큰을 사용하여 액세스 토큰을 요청할 때는 요청에 갱신 토큰을 제공해야 합니다. 이 요소를 사용하면 Apigee가 갱신 토큰을 찾을 위치를 지정할 수 있습니다. 예를 들어 쿼리 매개변수, HTTP 헤더 또는 양식 매개변수(기본값)로 전송될 수 있습니다.

request.queryparam.refreshtoken 변수는 갱신 토큰이 쿼리 매개변수(예: ?refresh_token=login.myapp.com)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 RefreshToken을 요구하려면 이 값을 request.header.refresh_token로 설정합니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.refresh_token (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:	refresh_token

<RefreshTokenExpiresIn> 요소

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

갱신 토큰 만료 시간을 밀리초 단위로 적용합니다. 만료 시간 값은 시스템에서 생성된 값에 <RefreshTokenExpiresIn> 값을 더한 값입니다. <RefreshTokenExpiresIn>을 -1로 설정하면 최대 OAuth 갱신 토큰 만료에 따라 갱신 토큰이 만료됩니다. <RefreshTokenExpiresIn>을 지정하지 않으면 시스템에서 기본값을 적용합니다.

다음 스탠자는 흐름 변수와 기본값을 지정합니다. 흐름 변수 값은 지정된 기본값보다 우선 적용됩니다.

<RefreshTokenExpiresIn ref="kvm.oauth.expires_in">
    86400000 <!--value in milliseconds-->
</RefreshTokenExpiresIn>

기본값:	2592000000ms(30일)(2023년 5월 31일부터 적용)
Presence:	선택사항
유형:	정수
유효한 값:	0이 아닌 양의 정수. 만료 시간을 밀리초 단위로 지정합니다. -1로 설정하면 최대 OAuth 갱신 토큰 만료에 따라 만료됩니다. 참고: 다른 음수 정수 또는 0을 지정하면 배포 오류가 발생합니다.
부여 유형과 함께 사용:	authorization_code 비밀번호 refresh_token

참고: RefreshTokenExpiresIn이 -1로 설정된 경우 생성된 토큰에 만료 값("refresh_token_expires_in" : "0")이 표시됩니다.

<ResponseType> 요소

<ResponseType>request.queryparam.response_type</ResponseType>

이 요소는 클라이언트 앱이 요청하는 부여 유형을 Apigee에 알리며, 승인 코드 및 암시적 부여 유형 흐름에만 사용됩니다.

기본적으로 Apigee는 response_type 쿼리 매개변수에서 응답 유형 값을 찾습니다. 이 기본 동작을 재정의하려면 <ResponseType> 요소를 사용하여 응답 유형 값이 포함된 흐름 변수를 구성합니다. 예를 들어 이 요소를 request.header.response_type으로 설정하면 Apigee가 요청 헤더에서 전달할 응답 유형을 찾습니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.response_type(x-www-form-url로 인코딩되어 요청 본문에 지정됨)
Presence:	선택사항입니다. 기본 동작을 재정의하려면 이 요소를 사용합니다.
유형:	문자열
유효한 값:	`code`(승인 코드 부여 유형의 경우) 또는 `token`(암시적 부여 유형의 경우)
부여 유형과 함께 사용:	암시적 GenerateAuthorizationCode 작업에도 사용됩니다.

<ReuseRefreshToken> 요소

<ReuseRefreshToken>true</ReuseRefreshToken>

true로 설정하면 기존의 갱신 토큰은 만료될 때까지 재사용됩니다. false인 경우 유효한 갱신 토큰이 제공되면 Apigee에서 새 갱신 토큰을 발급합니다.

기본값:	`false`
Presence:	선택사항
유형:	부울
유효한 값:	`true` 또는 `false`
부여 유형과 함께 사용:	refresh_token

<RFCCompliantRequestResponse> 요소

<RFCCompliantRequestResponse>[true | false]</RFCCompliantRequestResponse>

true일 경우 정책이 RFC6749 표준을 준수하며 다음과 같은 규정 준수 동작을 사용 설정합니다.

오류 및 오류가 아닌 응답에는 RFC2616(Hypertext Transfer Protocol -- HTTP/1.1) 준수를 위해 토큰, 사용자 인증 정보 또는 기타 민감한 정보를 포함하는 응답에서 값이 no-store인 HTTP Cache-Control 응답 헤더 필드와 값이 no-cache인 Pragma 응답 헤더 필드가 포함됩니다.
expires_in 속성은 영숫자 형식입니다. 일관성을 위해 refresh_token_expires_in도 영숫자입니다.
토큰 생성을 위한 OAuthV2 응답에는 BearerToken 대신 RFC를 준수하는 Bearer 헤더 필드가 포함됩니다.
응답 페이로드의 오류 메시지는 갱신 토큰 오류의 경우 {"error" : "xxx", "error_description" :"yyy"} 형식입니다.

기본값:	`false`: 기본적으로 이 정책은 RFC를 준수하지 않는 특정 동작을 허용합니다. 자세한 내용은 RFC를 준수하지 않는 동작을 참조하세요. RFC 규정 준수를 사용 설정하려면 이 요소를 `true`로 설정합니다.
Presence:	선택사항
유형:	불리언
유효한 값:	`true` 또는 `false`
부여 유형과 함께 사용:	전체

<SecretKey>/<Value>

<SecretKey>
  <Value ref="your-variable-name"/>
</SecretKey>

HMAC 알고리즘으로 JWT 형식의 액세스 토큰을 확인하거나 서명하는 데 사용되는 보안 비밀 키를 제공합니다. 알고리즘이 HS256, HS384, HS512 중 하나인 경우에만 사용합니다. ref 속성을 사용하여 흐름 변수의 키를 전달합니다. 자세한 내용은 JWT OAuth 토큰 작업 사용을 참조하세요.

Apigee는 HS256/HS384/HS512 알고리즘에 최소한의 키 안전성을 적용합니다. 최소 키 길이는 HS256의 경우 32바이트, HS384의 경우 48바이트, HS512의 경우 64바이트입니다. 낮은 안정성의 키를 사용하면 런타임 오류가 발생합니다.

기본값	해당 사항 없음
Presence	HMAC 알고리즘에 필요합니다.
유형	문자열
유효한 값	흐름 변수

<Scope> 요소

<Scope>request.queryparam.scope</Scope>

이 요소가 GenerateAccessToken 또는 GenerateAuthorizationCode 정책 중 하나에 있는 경우 이 요소는 토큰 또는 코드를 부여할 범위를 지정하는 데 사용됩니다. 이러한 값은 일반적으로 클라이언트 앱의 요청에 있는 정책에 전달되며, 흐름 변수를 가져오도록 요소를 구성하여 요청에서 범위가 전달되는 방식을 선택할 수 있습니다. 다음 예시에서 request.queryparam.scope는 범위가 쿼리 매개변수(예: ?scope=READ)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 범위을 요구하려면 이 값을 request.header.scope로 설정합니다.

이 요소가 'VerifyAccessToken' 정책에 표시되면 정책이 적용할 범위를 지정하는 데 사용됩니다. 이 유형의 정책에서는 값은 '하드 코딩된' 범위 이름이어야 합니다. 변수는 사용할 수 없습니다. 예를 들면 다음과 같습니다.

<Scope>A B</Scope>

OAuth2 범위 작업 및 OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	범위 없음
Presence:	선택사항
유형:	문자열
유효한 값:	Generate* 정책과 함께 사용되는 경우 흐름 변수입니다. VerifyAccessToken과 함께 사용되는 경우 공백으로 구분된 범위 이름(문자열) 목록입니다.
부여 유형과 함께 사용:	authorization_code 암시적 비밀번호 client_credentials GenerateAuthorizationCode 및 VerifyAccessToken 작업에도 사용할 수 있습니다.

<State> 요소

<State>request.queryparam.state</State>

클라이언트 앱이 승인 서버로 상태 정보를 전송해야 하는 경우 이 요소를 사용하면 Apigee가 상태 값을 찾아야 할 위치를 지정할 수 있습니다. 예를 들어 쿼리 매개변수 또는 HTTP 헤더로 전송될 수 있습니다. 상태 값은 일반적으로 CSRF 공격을 방지하기 위한 보안 절차로 사용됩니다.

예를 들어 request.queryparam.state는 상태가 쿼리 매개변수(예: ?state=HjoiuKJH32)로 존재해야 함을 나타냅니다. 예를 들어 HTTP 헤더의 상태를 요구하려면 이 값을 request.header.state로 설정합니다. OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	상태 없음
Presence:	선택사항
유형:	문자열
유효한 값:	런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:	전체 GenerateAuthorizationCode 작업에도 사용할 수 있습니다.

<StoreToken> 요소

 <StoreToken>true</StoreToken>

<ExternalAuthorization> 요소가 true인 경우 이 요소를 true로 설정합니다. <StoreToken> 요소는 Apigee에 외부 액세스 토큰을 저장하도록 지시합니다. 그렇지 않으면 유지되지 않습니다.

기본값:	false
Presence:	선택사항
유형:	불리언
유효한 값:	true 또는 false
부여 유형과 함께 사용:	authorization_code 비밀번호 client_credentials

<SupportedGrantTypes>/<GrantType> 요소

<SupportedGrantTypes>
    <GrantType>authorization_code</GrantType>
    <GrantType>client_credentials</GrantType>
    <GrantType>implicit</GrantType>
    <GrantType>password</GrantType>
</SupportedGrantTypes>

Apigee에서 OAuth 토큰 엔드포인트가 지원하는 부여 유형을 지정합니다. 엔드포인트는 여러 부여 유형을 지원할 수 있습니다. 즉, 단일 엔드포인트를 구성하여 여러 부여 유형에 대한 액세스 토큰을 배포할 수 있습니다. 엔드포인트에 대한 자세한 내용은 OAuth 엔드포인트 이해를 참조하세요. 부여 유형은 grant_type 매개변수로 토큰 요청에 전달됩니다.

지원되는 부여 유형을 지정하지 않으면 허용되는 유일한 부여 유형은 authorization_code 및 implicit입니다. <GrantType> 요소도 참조하세요. 이 요소는 Apigee가 클라이언트 요청에서 전달된 grant_type 매개변수를 찾아야 하는 위치를 지정하는 데 사용되는 상위 수준 요소입니다. Apigee는 grant_type 매개변수의 값이 지원되는 부여 유형 중 하나와 일치하는지 확인합니다.

기본값:	authorization _code 및 암시적
Presence:	필수
유형:	문자열
유효한 값:	client_credentials authorization_code 비밀번호 암시적

<Tokens>/<Token> 요소

ValidateToken 및 InvalidateToken 작업에 사용됩니다. 액세스 토큰 승인 및 취소도 참조하세요. <Token> 요소는 취소할 토큰의 소스를 정의하는 흐름 변수를 식별합니다. 예를 들어 개발자가 액세스 토큰을 access_token이라는 쿼리 매개변수로 제출해야 하는 경우 request.queryparam.access_token을 사용합니다.

<UserName> 요소

<UserName>request.queryparam.user_name</UserName>

예를 들어 쿼리 매개변수에 사용자 이름을 전달하고 다음과 같이 <UserName> 요소를 설정할 수 있습니다. <UserName>request.queryparam.username</UserName>.HTTP 헤더에 사용자 이름을 요구하려면 이 값을 request.header.username으로 설정합니다.

OAuth 2.0 토큰 가져오기도 참조하세요.

기본값:	request.formparam.username (x-www-form-urlencoded 및 요청 본문에 지정됨)
Presence:	선택사항
유형:	문자열
유효한 값:	모든 변수 설정.
부여 유형과 함께 사용:	비밀번호

액세스 토큰 확인

API 프록시에 대해 토큰 엔드포인트가 설정되면 VerifyAccessToken 작업을 지정하는 해당 OAuthV2 정책은 보호된 리소스를 노출하는 흐름에 연결됩니다.

예를 들어 API에 대한 모든 요청이 승인되도록 다음 정책이 액세스 토큰 확인을 적용합니다.

<OAuthV2 name="VerifyOAuthAccessToken">
  <Operation>VerifyAccessToken</Operation>
</OAuthV2>

보호할 API 리소스에 정책이 연결됩니다. API에 대한 모든 요청이 인증되었는지 확인하려면 다음과 같이 정책을 ProxyEndpoint 요청 PreFlow에 연결합니다.

<PreFlow>
  <Request>
    <Step><Name>VerifyOAuthAccessToken</Name></Step>
  </Request>
</PreFlow>

다음 선택적 요소를 사용하여 VerifyAccessToken 작업의 기본 설정을 재정의할 수 있습니다.

이름 설명

범위

이름	설명
범위	공백으로 구분된 범위 목록입니다. 나열된 범위 중 하나 이상이 액세스 토큰 안에 있으면 인증이 성공합니다. 예를 들어 다음 정책은 액세스 토큰을 검사하여 토큰에 나열된 범위가 하나 이상 포함되어 있는지 확인합니다. READ 또는 WRITE가 있으면 인증이 성공합니다. <OAuthV2 name="ValidateOauthScopePolicy"> <Operation>VerifyAccessToken</Operation> <Scope>READ WRITE</Scope> </OAuthV2>
AccessToken	액세스 토큰이 위치할 것으로 예상되는 변수입니다. 예를 들어 `request.queryparam.accesstoken`입니다. 기본적으로 액세스 토큰은 OAuth 2.0 사양에 따라 앱에서 Authorization HTTP 헤더로 제공되어야 합니다. 액세스 토큰이 비표준 위치(쿼리 매개변수 또는 이름이 Authorization이 아닌 HTTP 헤더의 경우)에 제공될 것으로 예상되면 이 설정을 사용합니다.

공백으로 구분된 범위 목록입니다. 나열된 범위 중 하나 이상이 액세스 토큰 안에 있으면 인증이 성공합니다. 예를 들어 다음 정책은 액세스 토큰을 검사하여 토큰에 나열된 범위가 하나 이상 포함되어 있는지 확인합니다. READ 또는 WRITE가 있으면 인증이 성공합니다.

<OAuthV2 name="ValidateOauthScopePolicy">
  <Operation>VerifyAccessToken</Operation>
  <Scope>READ WRITE</Scope>
</OAuthV2>

AccessToken 액세스 토큰이 위치할 것으로 예상되는 변수입니다. 예를 들어 request.queryparam.accesstoken입니다. 기본적으로 액세스 토큰은 OAuth 2.0 사양에 따라 앱에서 Authorization HTTP 헤더로 제공되어야 합니다. 액세스 토큰이 비표준 위치(쿼리 매개변수 또는 이름이 Authorization이 아닌 HTTP 헤더의 경우)에 제공될 것으로 예상되면 이 설정을 사용합니다.

액세스 토큰 확인 및 OAuth 2.0 토큰 가져오기도 참조하세요.

요청 변수 위치 지정

이 정책은 각 권한 유형에 대해 요청 메시지의 위치 또는 필수 정보에 대한 가정을 합니다. 이러한 가정은 OAuth 2.0 사양을 기반으로 합니다. 앱이 OAuth 2.0 사양에서 벗어나야 하는 경우 각 매개변수의 예상 위치를 지정할 수 있습니다. 예를 들어 승인 코드를 처리할 때 승인 코드, 클라이언트 ID, 리디렉션 URI, 범위의 위치를 지정할 수 있습니다. HTTP 헤더, 쿼리 매개변수 또는 양식 매개변수로 지정할 수 있습니다.

아래 예시에서는 필요한 승인 코드 매개변수의 위치를 HTTP 헤더로 지정하는 방법을 보여줍니다.

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.header.client_id</ClientId>
  <RedirectUri>request.header.redirect_uri</RedirectUri>
  <Scope>request.header.scope</Scope>
  ...

또는 클라이언트 앱 기반을 지원하는 데 필요한 경우 헤더와 쿼리 매개변수를 조합하여 사용할 수 있습니다.

  ...
  <GrantType>request.header.grant_type</GrantType>
  <Code>request.header.code</Code>
  <ClientId>request.queryparam.client_id</ClientId>
  <RedirectUri>request.queryparam.redirect_uri</RedirectUri>
  <Scope>request.queryparam.scope</Scope>
  ...

매개변수당 하나의 위치만 구성할 수 있습니다.

흐름 변수

이 표에 정의된 흐름 변수는 각 OAuth 정책이 실행될 때 채워지며 API 프록시 흐름에서 실행되는 다른 정책 또는 애플리케이션에서 사용할 수 있습니다.

VerifyAccessToken 작업

VerifyAccessToken 작업이 실행되면 프록시의 실행 컨텍스트에서 대량의 흐름 변수가 채워집니다. 이러한 변수는 액세스 토큰, 개발자 앱, 개발자와 관련된 속성을 제공합니다. 예를 들어 AssignMessage 또는 자바스크립트 정책을 사용하여 이러한 변수를 읽고 나중에 흐름에서 필요에 따라 사용할 수 있습니다. 이러한 변수는 디버깅하는 데도 유용할 수 있습니다.

참고: API 제품이 유효한 환경, 프록시, API 리소스(proxy.pathsuffix에서 파생됨)로 구성된 경우 API 제품 변수가 자동으로 채워집니다. flow.resource.name 변수를 명시적으로 설정할 필요는 없습니다.

API 제품이 유효한 환경 및 API 프록시로 구성되지 않은 경우 흐름에서 API 제품 변수를 채우도록 flow.resource.name을 명시적으로 설정해야 합니다. 제품 구성에 대한 자세한 내용은 API 제품 관리를 참조하세요.

토큰별 변수

변수	설명
`organization_name`	프록시가 실행 중인 조직의 이름입니다.
`developer.id`	등록된 클라이언트 앱과 연결된 개발자 또는 AppGroup의 ID입니다.
`developer.app.name`	등록된 클라이언트 앱과 연결된 개발자 또는 AppGroup 앱의 이름입니다.
`client_id`	등록된 클라이언트 앱의 클라이언트 ID입니다.
`grant_type`	요청과 연결된 권한 유형입니다. `VerifyJWTAccessToken` 작업에는 지원되지 않습니다.
`token_type`	요청과 연결된 토큰 유형입니다.
`access_token`	확인되는 액세스 토큰입니다.
`accesstoken.{custom_attribute}`	액세스 토큰에서 이름이 지정된 맞춤 속성입니다.
`issued_at`	Unix 기준시간(밀리초)으로 표현되는 액세스 토큰 발급 날짜입니다.
`expires_in`	액세스 토큰의 만료 시간이며, 초로 표현됩니다. `ExpiresIn` 요소는 만료 시간을 밀리초로 설정하지만 토큰 응답 및 흐름 변수에서는 이 값이 초 단위로 표현됩니다.
`status`	액세스 토큰의 상태(예: 승인됨 또는 취소됨)입니다.
`scope`	액세스 토큰과 연결된 범위입니다(있는 경우).
`apiproduct.<custom_attribute_name>`	등록된 클라이언트 앱과 연결된 API 제품에 대해 이름이 지정된 맞춤 속성입니다.
`apiproduct.name`	등록된 클라이언트 앱과 연결된 API 제품의 이름입니다.
`revoke_reason`	(Apigee Hybrid만 해당) 액세스 토큰이 취소된 이유를 나타냅니다. `VerifyJWTAccessToken` 작업에는 지원되지 않습니다. 값은 `REVOKED_BY_APP`, `REVOKED_BY_ENDUSER`, `REVOKED_BY_APP_ENDUSER`, `TOKEN_REVOKED`일 수 있습니다.

앱별 변수

이러한 변수는 토큰과 관련된 개발자 앱과 연관됩니다.

변수	설명
`app.name`
`app.id`
`app.accessType`
`app.callbackUrl`
`app.status`	승인됨 또는 취소됨
`app.scopes`
`app.appFamily`
`app.apiproducts`
`app.appParentStatus`
`app.appType`	예: 개발자
`app.appParentId`
`app.created_by`
`app.created_at`
`app.last_modified_at`
`app.last_modified_by`
`app.{custom_attributes}`	등록된 클라이언트 앱에 대해 이름이 지정된 커스텀 속성입니다.

AppGroup 관련 변수

토큰의 AppGroup에 대한 정보가 포함된 다음 흐름 변수는 정책으로 채워집니다. 이러한 AppGroup 속성은 verifyapikey.{policy_name}.app.appType이 'AppGroup'인 경우에만 채워집니다.

변수	설명
`appgroup.displayName`	AppGroup 표시 이름입니다.
`appgroup.name`	AppGroup의 이름입니다.
`appgroup.id`	AppGroup ID입니다. 참고: 이 ID는 Apigee에서 내부적으로 생성되며 시간이 지나도 동일하게 유지된다는 보장이 없습니다. 다음 목적으로 `appgroup.id` 변수를 사용하지 마세요. 할당량 식별자 KVM 키 백엔드 비즈니스 로직에서 사용할 대상에 전송되는 식별자
`appOwnerStatus`	앱 소유자의 상태: '활성', '비활성' 또는 'login_lock'
`created_at`	AppGroup이 생성된 날짜/시간 스탬프입니다.
`created_by`	AppGroup을 만든 개발자의 이메일 주소입니다.
`last_modified_at`	AppGroup이 마지막으로 수정된 날짜/시간 스탬프입니다.
`last_modified_by`	AppGroup을 마지막으로 수정한 개발자의 이메일 주소입니다.
`{appgroup_custom_attributes}`	모든 커스텀 AppGroup 속성입니다. 커스텀 속성의 이름을 지정합니다.

개발자별 변수

app.appType이 'Developer'이면 개발자 속성이 채워집니다.

변수	설명
개발자별 변수
`developer.id`
`developer.userName`
`developer.firstName`
`developer.lastName`
`developer.email`
`developer.status`	활성 또는 비활성
`developer.apps`	참고: 앱 수가 10개를 초과하는 경우 이 변수에 액세스하면 지연 시간이 길어집니다.
`developer.created_by`
`developer.created_at`
`developer.last_modified_at`
`developer.last_modified_by`
`developer.{custom_attributes}`	개발자에 대해 이름이 지정된 맞춤 속성입니다.

GenerateAuthorizationCode 작업

이러한 변수는 GenerateAuthorizationCode 작업이 성공적으로 실행될 때 설정됩니다.

프리픽스: oauthv2authcode.{policy_name}.{variable_name}

예: oauthv2authcode.GenerateCodePolicy.code

변수	설명
`code`	정책이 실행될 때 생성되는 승인 코드입니다.
`redirect_uri`	등록된 클라이언트 앱과 연결된 리디렉션 URI입니다.
`scope`	클라이언트 요청에 전달되는 선택적 OAuth 범위입니다.
`client_id`	클라이언트 요청에 전달되는 클라이언트 ID입니다.

GenerateAccessToken 및 RefreshAccessToken 작업

이러한 변수는 GenerateAccessToken 및 RefreshAccessToken 작업이 성공적으로 실행될 때 설정됩니다. 클라이언트 사용자 인증 정보 부여 유형 흐름에는 갱신 토큰 변수가 적용되지 않습니다.

프리픽스: oauthv2accesstoken.{policy_name}.{variable_name}

예: oauthv2accesstoken.GenerateTokenPolicy.access_token

변수 이름	설명
`access_token`	생성된 액세스 토큰입니다.
`client_id`	이 토큰과 연결된 개발자 앱의 클라이언트 ID입니다.
`expires_in`	토큰의 만료 값입니다. 자세한 내용은 <ExpiresIn> 요소를 참조하세요. 응답에서 expires_in은 초로 표현됩니다.
`scope`	토큰에 대해 구성된 사용 가능한 범위의 목록입니다. OAuth2 범위 작업을 참조하세요.
`status`	`approved` 또는 `revoked`.
`token_type`	`BearerToken`으로 설정됩니다.

`developer.email`	토큰과 연결된 개발자 앱을 소유한 등록된 개발자의 이메일 주소입니다.
`organization_name`	프록시가 실행되는 조직입니다.
`api_product_list`	토큰에 해당하는 개발자 앱과 연결된 제품의 목록입니다.

`refresh_count`
`refresh_token`	생성된 갱신 토큰입니다. 클라이언트 사용자 인증 정보 부여 유형에는 갱신 토큰이 생성되지 않습니다.
`refresh_token_expires_in`	새로고침 토큰의 수명(초)입니다.
`refresh_token_issued_at`	이 시간 값은 해당 32비트 타임스탬프 수량의 문자열 표현입니다. 예를 들어 'Wed, 21 Aug 2013 19:16:47 UTC'는 타임스탬프 값 1377112607413에 해당합니다.
`refresh_token_status`	`approved` 또는 `revoked`.

GenerateAccessTokenImplicitGrant

이러한 변수는 암시적 부여 유형 흐름에서 GenerateAccessTokenImplicit 작업이 성공적으로 실행될 때 설정됩니다.

프리픽스: oauthv2accesstoken.{policy_name}.{variable_name}

예: oauthv2accesstoken.RefreshTokenPolicy.access_token

변수	설명
`oauthv2accesstoken.access_token`	정책이 실행될 때 생성되는 액세스 토큰입니다.
`oauthv2accesstoken.{policy_name}.expires_in`	토큰의 만료 값(초)입니다. 자세한 내용은 <ExpiresIn> 요소를 참조하세요.

오류 참조

이 섹션에서는 반환되는 오류 코드 및 오류 메시지와 이 정책이 오류를 트리거할 때 Apigee에서 설정한 오류 변수를 설명합니다. 오류를 처리하기 위해 오류 규칙을 개발 중인 경우, 이 정보는 중요합니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항 및 오류 처리를 참조하세요.

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다.

오류 코드	HTTP 상태	원인	작업에 의해 발생
`steps.oauth.v2.access_token_expired`	`401`	액세스 토큰이 만료되었습니다.	`VerifyAccessToken` `InvalidateToken`
`steps.oauth.v2.access_token_not_approved`	`401`	액세스 토큰이 취소되었습니다.	`VerifyAccessToken`
`steps.oauth.v2.apiresource_doesnot_exist`	`401`	요청한 리소스에 액세스 토큰과 연결된 API 제품이 없습니다.	`VerifyAccessToken`
`steps.oauth.v2.FailedToResolveAccessToken`	`500`	`<AccessToken>` 요소에 지정된 변수에서 액세스 토큰을 찾아야 하는 정책이지만 변수를 확인할 수 없습니다.	`GenerateAccessToken`
`steps.oauth.v2.FailedToResolveAuthorizationCode`	`500`	`<Code>` 요소에 지정된 변수에서 승인 코드를 찾아야 하는 정책이지만 변수를 확인할 수 없습니다.	`GenerateAuthorizationCode`
`steps.oauth.v2.FailedToResolveClientId`	`500`	`<ClientId>` 요소에 지정된 변수에서 클라이언트 ID를 찾아야 하는 정책이지만 변수를 확인할 수 없습니다.	`GenerateAccessToken` `GenerateAuthorizationCode` `GenerateAccessTokenImplicitGrant` `RefreshAccessToken`
`steps.oauth.v2.FailedToResolveRefreshToken`	`500`	`<RefreshToken>` 요소에 지정된 변수에서 갱신 토큰을 찾아야 하는 정책이지만 변수를 확인할 수 없습니다.	`RefreshAccessToken`
`steps.oauth.v2.FailedToResolveToken`	`500`	`<Tokens>` 요소에 지정된 변수에서 토큰을 찾아야 하는 정책이지만 변수를 확인할 수 없습니다.	`ValidateToken` `InvalidateToken`
`steps.oauth.v2.InsufficientScope`	403	요청에 표시된 액세스 토큰에 포함된 범위가 액세스 토큰 확인 정책에 지정된 범위와 일치하지 않습니다. 범위에 대한 자세한 내용은 OAuth2 범위 작업을 참조하세요.	`VerifyAccessToken`
`steps.oauth.v2.invalid_access_token`	`401`	클라이언트에서 보낸 액세스 토큰이 잘못되었습니다.	`VerifyAccessToken`
`steps.oauth.v2.invalid_client`	`401`	이 오류 이름은 정책의 `<GenerateResponse>` 속성이 true로 설정되고 요청에 전송된 클라이언트 ID가 잘못된 경우에 반환됩니다. 프록시와 연결된 개발자 앱에서 올바른 클라이언트 키와 보안 비밀 값을 사용하는지 확인합니다. 일반적으로 이 값은 Base64로 인코딩된 기본 승인 헤더로 전송됩니다. 참고: `invalid_client` 및 `InvalidClientIdentifier` 이름을 모두 포착하도록 기존 오류 규칙 조건을 변경하는 것이 좋습니다.	`GenerateAccessToken` `RefreshAccessToken`
`steps.oauth.v2.invalid_request`	400	이 오류 이름은 일반적으로 요청에서 전송된 매개변수가 누락되거나 잘못된 매개변수에 대해 다양한 종류의 오류에 사용됩니다. `<GenerateResponse>`가 `false`로 설정된 경우 오류 변수(아래 설명 참조)를 사용하여 오류 이름 및 원인 등 오류에 대한 세부정보를 검색합니다.	`GenerateAccessToken` `GenerateAuthorizationCode` `GenerateAccessTokenImplicitGrant` `RefreshAccessToken`
`steps.oauth.v2.InvalidAccessToken`	`401`	승인 헤더에 필요한 `Bearer` 단어가 없습니다. 예를 들어 `Authorization: Bearer your_access_token`입니다.	`VerifyAccessToken`
`steps.oauth.v2.InvalidAPICallAsNo\ ApiProductMatchFound`	`401`	현재 실행 중인 API 프록시 또는 작업이 액세스 토큰과 연결된 제품에 없습니다. 팁: 액세스 토큰과 연결된 제품이 올바르게 구성되었는지 확인하세요. 예를 들어 리소스 경로에 와일드 카드를 사용할 경우 와일드 카드가 올바르게 사용되고 있는지 확인합니다. 자세한 내용은 API 제품 관리를 참조하세요. 이 오류의 원인에 대한 자세한 내용은 Oauth2.0 액세스 토큰 확인에서 'Invalid API call as no apiproduct match found' 오류 발생을 참조하세요.	`VerifyAccessToken`
`steps.oauth.v2.InvalidClientIdentifier`	`500`	이 오류 이름은 정책의 `<GenerateResponse>` 속성이 false로 설정되고 요청에 전송된 클라이언트 ID가 잘못된 경우에 반환됩니다. 프록시와 연결된 개발자 앱에서 올바른 클라이언트 키와 보안 비밀 값을 사용하는지 확인합니다. 일반적으로 이 값은 Base64로 인코딩된 기본 승인 헤더로 전송됩니다. 참고: `invalid_client` 및 `InvalidClientIdentifier` 이름을 모두 포착하도록 기존 오류 규칙 조건을 변경하는 것이 좋습니다.	`GenerateAccessToken` `RefreshAccessToken`
`steps.oauth.v2.InvalidParameter`	`500`	정책은 액세스 토큰이나 승인 코드 중 하나를 지정해야 하며 둘 다 지정할 수는 없습니다.	`GenerateAuthorizationCode` `GenerateAccessTokenImplicitGrant`
`steps.oauth.v2.InvalidTokenType`	`500`	`<Tokens>/<Token>` 요소를 사용하려면 토큰 유형(예: `refreshtoken`)을 지정해야 합니다. 클라이언트가 잘못된 유형을 전달하면 이 오류가 발생합니다.	`ValidateToken` `InvalidateToken`
`steps.oauth.v2.MissingParameter`	`500`	응답 유형이 `token`이지만 권한 유형이 지정되지 않았습니다.	`GenerateAuthorizationCode` `GenerateAccessTokenImplicitGrant`
`steps.oauth.v2.UnSupportedGrantType`	`500`	클라이언트가 정책에서 지원하지 않는 부여 유형을 지정했습니다(`<SupportedGrantTypes>` 요소에 나열되지 않음). 참고: 현재 지원되지 않는 부여 유형 오류가 올바르게 발생하지 않는 버그가 있습니다. 지원되지 않는 부여 유형 오류가 발생하면 프록시는 예상대로 오류 흐름을 시작하지 않습니다.	`GenerateAccessToken` `GenerateAuthorizationCode` `GenerateAccessTokenImplicitGrant` `RefreshAccessToken`

JWT 토큰별 런타임 오류

JWT 인증 토큰 흐름의 런타임 오류 코드 및 설명은 OAuth2 흐름 컨텍스트에 따라 다릅니다.

흐름 컨텍스트가 토큰 생성 또는 새로고침인 경우 아래의 JWT 토큰 생성 및 새로고침 흐름 오류 코드를 참조하세요.
토큰 확인 흐름은 아래의 토큰 확인 흐름 오류 코드를 참조하세요.

JWT 토큰 생성 및 새로고침 흐름 오류 코드

JWT 토큰을 생성하거나 새로 고치는 OAuth2 흐름의 경우 오류 응답은 RFC6749에 지정된 오류 응답을 준수합니다. 자세한 내용은 섹션 5.2 오류 응답을 참조하세요.

토큰 확인 흐름 오류 코드

다음 표에 나열된 오류 코드는 VerifyAccessToken 작업에만 적용됩니다.

오류 코드	HTTP 상태	원인	작업에 의해 발생
`oauth.v2.JWTSigningFailed`	`401`	정책에서 JWT를 서명할 수 없습니다.	`GenerateJWTAccessToken`
`oauth.v2.InvalidValueForJWTAlgorithm`	`401`	이는 JWT 액세스 토큰에 알고리즘이 없거나 값이 지원되지 않는 경우에 발생합니다.	`GenerateJWTAccessToken` `VerifyJWTAccessToken`
`oauth.v2.InsufficientKeyLength`	`401`	JWT 생성 시 HS384 또는 HS512 알고리즘의 최소 크기보다 작은 키일 때 발생합니다.	`GenerateJWTAccessToken` `VerifyJWTAccessToken`
`oauth.v2.JWTAlgorithmMismatch`	`401`	생성 정책에 지정된 알고리즘이 확인 정책에서 예상되는 알고리즘과 일치하지 않습니다. 지정된 알고리즘이 일치해야 합니다.	`VerifyJWTAccessToken`
`oauth.v2.JWTDecodingFailed`	`401`	정책이 JWT를 디코딩할 수 없습니다. JWT가 손상되었을 수 있습니다.	`VerifyJWTAccessToken`
`oauth.v2.MissingMandatoryClaimsInJWT`	`401`	Jwt 액세스 토큰에 필수 클레임이 없는 경우에 발생합니다.	`VerifyJWTAccessToken`
`oauth.v2.InvalidJWTSignature`	`401`	이는 JWT 액세스 토큰의 서명을 확인할 수 없거나 서명이 유효하지 않은 경우에 발생합니다.	`VerifyJWTAccessToken`
`oauth.v2.InvalidTypeInJWTHeader`	`401`	JWT 유형이 `at+Jwt`가 아닌 경우에 발생합니다.	`VerifyJWTAccessToken`

배포 오류

이 오류는 이 정책이 포함된 프록시를 배포할 때 발생할 수 있습니다.

오류 이름	원인
`InvalidValueForExpiresIn`	`<ExpiresIn>` 요소에서 유효한 값은 양의 정수 및 `-1`입니다.
`InvalidValueForRefreshTokenExpiresIn`	`<RefreshTokenExpiresIn>` 요소에서 유효한 값은 양의 정수 및 `-1`입니다.
`InvalidGrantType`	`<SupportedGrantTypes>` 요소에 잘못된 부여 유형이 지정되어 있습니다. 유효한 유형 목록은 정책 참조를 참조하세요.
`ExpiresInNotApplicableForOperation`	`<Operations>` 요소에 지정된 작업이 만료를 지원하는지 확인하세요. 예를 들어 `VerifyToken` 작업은 지원하지 않습니다.
`RefreshTokenExpiresInNotApplicableForOperation`	`<Operations>` 요소에 지정된 작업이 갱신 토큰 만료를 지원하는지 확인합니다. 예를 들어 VerifyToken 작업은 지원하지 않습니다.
`GrantTypesNotApplicableForOperation`	`<SupportedGrantTypes>`에 지정된 부여 유형이 지정된 작업에 지원되는지 확인합니다.
`OperationRequired`	`<Operation>` 요소를 사용하여 이 정책에 작업을 지정해야 합니다. 참고: `<Operation>` 요소가 누락된 경우 UI에서 스키마 유효성 검사 오류가 발생합니다.
`InvalidOperation`	`<Operation>` 요소를 사용하여 이 정책에 유효한 작업을 지정해야 합니다. 참고: `<Operation>` 요소가 잘못된 경우 UI에서 스키마 유효성 검사 오류가 발생합니다.
`TokenValueRequired`	`<Tokens>` 요소에 토큰 `<Token>` 값을 지정해야 합니다.

JWT 토큰별 배포 오류

이러한 배포 오류는 JWT 토큰 작업을 사용하는 정책에만 해당됩니다.

오류 이름	원인
`InvalidValueForAlgorithm`	`<Algorithm>` 요소에 지정된 알고리즘이 사용 가능한 알고리즘 목록에 없거나 존재하지 않습니다.
`MissingKeyConfiguration`	사용되는 알고리즘에 따라 필수 `<SecretKey>`, `<PrivateKey>` 또는 `<PublicKey>` 요소가 누락되었습니다.
`EmptyValueElementForKeyConfiguration`	필수 하위 요소 `<Value>`가 `<PrivateKey>`, `<PublicKey>` 또는 `<SecretKey>` 요소에 정의되어 있지 않습니다.
`InvalidKeyConfiguration`	`<PrivateKey>` 요소가 RSA 계열 알고리즘에 사용되지 않거나 `<SecretKey>` 요소가 HS 계열 알고리즘에 사용되지 않습니다.
`EmptyRefAttributeForKeyconfiguration`	`<PrivateKey>`, `<PublicKey>` 또는 `<SecretKey>` 요소의 `<Value>` 하위 요소에 대한 `ref` 속성이 비어 있습니다.
`InvalidVariableNameForKey`	`<PrivateKey>`, `<PublicKey>` 또는 `<SecretKey>` 요소의 하위 요소 `<Value>`에 있는 `ref` 속성에 지정된 흐름 변수 이름에 `private` 프리픽스가 포함되어 있지 않습니다.

오류 변수

이러한 변수는 이 정책이 런타임 시 오류를 트리거할 때 설정됩니다.

참고: 이러한 변수를 사용하여 오류 규칙 조건을 만들 수 있습니다. 이러한 변수는 <GenerateResponse>가 false로 설정되어 오류가 발생할 때 채워집니다. <GenerateResponse>가 true인 경우 오류가 발생하면 정책이 클라이언트에 즉시 응답을 반환합니다. 오류 흐름은 건너뛰며 이러한 변수는 채워지지 않습니다. 자세한 내용은 정책 오류에 대해 알아야 할 사항을 참조하세요.

변수	장소	예
`fault.name="fault_name"`	`fault_name`은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다.	`fault.name = "invalid_request"`
`oauthV2.policy_name.failed`	`policy_name`은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	`oauthV2.GenerateAccesstoken.failed = true`
`oauthV2.policy_name.fault.name`	`policy_name`은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	`oauthV2.GenerateAccesstoken.fault.name = invalid_request` 참고: `VerifyAccessToken` 작업의 경우 오류 이름에 `keymanagement.service` 서픽스가 포함됩니다. 예를 들어 `keymanagement.service.invalid_access_token`입니다.
`oauthV2.policy_name.fault.cause`	`policy_name`은 오류를 발생시킨 정책의 사용자 지정 이름입니다.	`oauthV2.GenerateAccesstoken.cause = Required param : grant_type`

오류 응답 예시

<GenerateResponse> 요소가 true이면 이러한 응답은 클라이언트로 다시 전송됩니다.

참고: 오류 처리에서 권장사항은 오류 응답의 errorcode 부분을 트래핑하는 것입니다. 변경될 수 있으므로 faultstring의 텍스트에 의존하지 마세요.

<GenerateResponse>가 true이면 정책은 토큰과 코드를 생성하는 작업에 대해 이 형식의 오류를 반환합니다. 전체 목록은 OAuth HTTP 오류 응답 참조를 확인하세요.

{"ErrorCode" : "invalid_client", "Error" :"ClientId is Invalid"}

<GenerateResponse>가 true이면 정책은 확인 및 유효성 검사 작업을 위해 이 형식으로 오류를 반환합니다. 전체 목록은 OAuth HTTP 오류 응답 참조를 확인하세요.

{  
   {  
      "fault":{  
         "faultstring":"Invalid Access Token",
         "detail":{  
            "errorcode":"keymanagement.service.invalid_access_token"
         }
      }
   }

오류 규칙 예시

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientResponse</Name>
        <Condition>(fault.name = "invalid_client") OR (fault.name = "InvalidClientIdentifier")</Condition>
    </Step>
    <Step>
        <Name>AM-InvalidTokenResponse</Name>
        <Condition>(fault.name = "invalid_access_token")</Condition>
    </Step>
    <Condition>(oauthV2.failed = true) </Condition>
</FaultRule>

스토리지의 토큰이 해싱됨

Apigee Hybrid 또는 Apigee를 사용하는 경우 OAuthV2 액세스 토큰 및 갱신 토큰은 런타임 Cassandra 데이터베이스에 저장될 때 기본적으로 해싱됩니다. 해싱은 데이터베이스가 손상된 경우 토큰이 사용되지 못하도록 합니다.

기본 OAuth 구성 작업

Apigee의 각 조직(무료 체험판 조직 포함)은 OAuth 토큰 엔드포인트로 프로비저닝됩니다. 엔드포인트는 oauth라는 API 프록시의 정책으로 사전 구성됩니다. 토큰 엔드포인트는 Apigee에서 계정을 만드는 즉시 사용할 수 있습니다. 자세한 내용은 OAuth 엔드포인트 이해를 참조하세요.

액세스 토큰 삭제

기본적으로 OAuth2 토큰은 액세스 토큰과 갱신 토큰(존재하는 경우)이 모두 만료되고 3일(259,200초) 후에 Apigee 시스템에서 삭제됩니다.

RFC를 준수하지 않는 동작

기본적으로 GenerateAccessToken 작업과 함께 OAuthV2 정책은 RFC를 준수하지 않는 특정 속성이 포함된 토큰 응답을 반환합니다. 다음 표는 OAuthV2 정책에서 반환하는 비준수 속성과 해당 준수 속성을 보여줍니다.

참고: 이러한 요소를 준수해야 하는 경우 RFCCompliantRequestResponse 요소를 true로 설정합니다.

OAuthV2는 다음을 반환합니다.	RFC를 준수하는 속성은 다음과 같습니다.
`"token_type":"BearerToken"`	`"token_type":"Bearer"`
`"expires_in":"3600"`	`"expires_in":3600` (규정 준수 값은 문자열이 아닌 숫자입니다.)

또한 grant_type = refresh_token인 경우 만료된 갱신 토큰에 대한 오류 응답은 다음과 같습니다.

{"ErrorCode" : "invalid_request", "Error" :"Refresh Token expired"}

하지만 RFC를 준수하는 응답은 다음과 같습니다.

{"error" : "invalid_grant", "error_description" :"refresh token expired"}

OAuthV2 정책

대상

샘플

VerifyAccessToken

VerifyAccessToken

GenerateAccessToken

액세스 토큰 생성

GenerateAuthorizationCode

승인 코드 생성

RefreshAccessToken

액세스 토큰 새로고침

JWT 액세스 토큰

JWT 액세스 토큰

응답 흐름 토큰

응답 흐름에서 액세스 토큰 생성

요소 참조

<OAuthV2> 속성

<DisplayName> 요소

<AccessToken> 요소

<AccessTokenPrefix> 요소

<Algorithm>

<AppEndUser> 요소

<Attributes/Attribute>

응답에 커스텀 속성 표시 또는 숨기기

<CacheExpiryInSeconds> 요소

속성

<ClientId> 요소

<Code> 요소

<ExpiresIn> 요소

<ExternalAccessToken> 요소

<ExternalAuthorization> 요소

<ExternalAuthorizationCode> 요소

<ExternalRefreshToken> 요소

<GenerateResponse> 요소

<GenerateErrorResponse> 요소

<GrantType>

<Operation> 요소

<PassWord> 요소

<PrivateKey>/<Value>

<PublicKey>/<Value>

<RedirectUri> 요소

리디렉션 URI 정보

<RefreshToken> 요소

<RefreshTokenExpiresIn> 요소

<ResponseType> 요소

<ReuseRefreshToken> 요소

<RFCCompliantRequestResponse> 요소

<SecretKey>/<Value>

<Scope> 요소

<State> 요소

<StoreToken> 요소

<SupportedGrantTypes>/<GrantType> 요소

<Tokens>/<Token> 요소

<UserName> 요소

액세스 토큰 확인

요청 변수 위치 지정

흐름 변수

VerifyAccessToken 작업

GenerateAuthorizationCode 작업

GenerateAccessToken 및 RefreshAccessToken 작업

GenerateAccessTokenImplicitGrant

오류 참조

런타임 오류

JWT 토큰별 런타임 오류

JWT 토큰 생성 및 새로고침 흐름 오류 코드

토큰 확인 흐름 오류 코드

배포 오류

JWT 토큰별 배포 오류

오류 변수

오류 응답 예시

오류 규칙 예시

스토리지의 토큰이 해싱됨

기본 OAuth 구성 작업

액세스 토큰 삭제

RFC를 준수하지 않는 동작

관련 주제