GetOAuthV2Info 정책

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

Apigee Edge 문서 보기

정책 아이콘

무엇을

액세스 토큰, 갱신 토큰, 승인 코드, 클라이언트 앱 속성을 가져오고 변수를 이러한 속성의 값으로 채웁니다.

이 정책은 토큰 또는 인증 코드의 값에 따라 동적 조건부 동작을 구성해야 하는 경우에 유용합니다. 토큰 유효성 검사가 수행될 때마다 변수에 토큰 속성 값이 자동으로 입력됩니다. 그러나 토큰 유효성 검사가 수행되지 않은 경우 이 기능을 사용하여 토큰의 속성 값으로 변수를 명시적으로 채울 수 있습니다. 토큰 및 승인 코드 맞춤설정도 참조하세요.

이 정책에 전달하는 액세스 토큰이 유효해야 하며 그렇지 않으면 정책에서 invalid_access_token 오류가 발생합니다.

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

샘플

다음 샘플은 Get OAuth V2 Info 정책을 사용하여 OAuth2 워크플로의 다양한 구성요소에 대한 정보를 검색한 다음 코드 내에서 해당 정보에 액세스합니다.

액세스 토큰

액세스 토큰에 대한 참조를 가져오려면 정책의 <AccessToken> 요소를 사용하세요.

다음 예시에서는 'access_token'이라는 쿼리 매개변수에서 액세스 토큰을 찾습니다(실제 구현 세부정보는 개발자가 결정합니다).

<GetOAuthV2Info name="MyTokenAttrsPolicy">
  <AccessToken ref="request.queryparam.access_token"></AccessToken>
</GetOAuthV2Info>

액세스 토큰이 주어지면 정책은 토큰의 프로필을 조회하고 변수 집합을 프로필 데이터로 채웁니다.

그런 다음 자바스크립트 또는 다른 수단을 사용하여 변수에 액세스할 수 있습니다. 다음 예시에서는 자바스크립트를 사용하여 액세스 토큰과 연결된 범위를 검색합니다.

var scope = context.getVariable('oauthv2accesstoken.MyTokenAttrsPolicy.scope');

코드에서 이러한 변수에 액세스하려면 변수에 'oauthv2accesstoken' 프리픽스를 추가해야 합니다. 액세스 토큰을 통해 사용할 수 있는 변수의 전체 목록은 액세스 토큰 변수를 참조하세요.

인증 코드

승인 코드 속성을 가져오려면 정책에서 <AuthorizationCode> 요소를 사용합니다.

다음 예시에서는 'code'라는 양식 매개변수에서 액세스 토큰을 찾습니다(실제 구현 세부정보는 개발자가 결정합니다).

<GetOAuthV2Info name="MyAuthCodeAttrsPolicy">
  <AuthorizationCode ref="request.formparam.code"></AuthorizationCode>
</GetOAuthV2Info>

인증 코드가 주어지면 정책은 코드 정보를 조회하고 변수 집합을 인증 코드 데이터로 채웁니다.

그런 다음 자바스크립트 또는 다른 수단을 사용하여 변수에 액세스할 수 있습니다. 다음 예시에서는 자바스크립트를 사용하여 승인 코드와 연결된 커스텀 속성을 검색합니다.

var attr = context.getVariable('oauthv2authcode.MyAuthCodeAttrsPolicy.custom_attribute_name');

코드에서 이러한 변수에 액세스하려면 변수에 'oauthv2authcode' 프리픽스를 추가해야 합니다. 인증 코드를 통해 사용할 수 있는 변수의 전체 목록은 승인 코드 변수를 참조하세요.

갱신 토큰

갱신 토큰 속성을 가져오려면 정책의 <RefreshToken> 요소를 사용합니다.

다음 예시에서는 'refresh_token'이라는 쿼리 매개변수에서 액세스 토큰을 찾습니다(실제 구현 세부정보는 개발자가 결정합니다).

<GetOAuthV2Info name="MyRefreshTokenAttrsPolicy">
  <RefreshToken ref="request.queryparam.refresh_token"/>
</GetOAuthV2Info>

갱신 토큰에서 정책은 갱신 토큰의 정보를 조회하고 변수 집합을 갱신 토큰 데이터로 채웁니다.

그런 다음 자바스크립트 또는 다른 수단을 사용하여 변수에 액세스할 수 있습니다. 다음 예시는 자바스크립트를 사용하여 갱신 토큰과 연결된 커스텀 속성을 검색합니다.

var attr = context.getVariable('oauthv2refreshtoken.MyRefreshTokenAttrsPolicy.accesstoken.custom_attribute_name');

코드에서 변수에 액세스하려면 변수에 'oauthv2refreshtoken' 프리픽스를 추가해야 합니다. 갱신 토큰을 통해 사용할 수 있는 변수의 전체 목록은 갱신 토큰 변수를 참조하세요.

고정

드문 사례지만 정적으로 구성된 토큰(변수를 통해 액세스할 수 없는 토큰)의 프로필을 가져와야 할 수도 있습니다. 이렇게 하려면 액세스 토큰 값을 요소로 제공하면 됩니다.

<GetOAuthV2Info name="GetTokenAttributes">
  <AccessToken>shTUmeI1geSKin0TODcGLXBNe9vp</AccessToken>
</GetOAuthV2Info>

다른 모든 토큰 유형(클라이언트 ID, 승인 코드, 갱신 토큰)에도 이를 수행할 수 있습니다.

클라이언트 ID

이 예시에서는 클라이언트 ID를 사용하여 클라이언트 앱 정보를 검색하는 방법을 보여줍니다. 실행 후 정책은 변수 집합을 클라이언트 정보로 채웁니다. 이 경우 정책은 client_id라는 쿼리 매개변수에서 클라이언트 ID를 찾습니다. 클라이언트 ID가 주어지면 정책은 클라이언트의 프로필을 조회하고 변수 집합을 프로필 데이터로 채웁니다. 변수에는 oauthv2client. 프리픽스가 추가됩니다.

<GetOAuthV2Info name="GetClientAttributes">
  <ClientId ref="request.queryparam.client_id"></ClientId>
</GetOAuthV2Info>

그런 다음 자바스크립트 또는 다른 수단을 사용하여 변수에 액세스할 수 있습니다. 예를 들어 자바스크립트를 사용하여 클라이언트 앱과 연결된 개발자 앱 이름과 개발자 이메일을 가져오려면 다음 코드를 사용합니다.

context.getVariable("oauthv2client.GetClientAttributes.developer.email");
context.getVariable("oauthv2client.GetClientAttributes.developer.app.name");

요소 참조

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="GetOAuthV2Info-1"
    <DisplayName>Get OAuth v2.0 Info 1</DisplayName>
    <AccessToken ref="variable"></AccessToken>
    <AuthorizationCode ref="variable"></AuthorizationCode>
    <ClientId ref="variable"></ClientId>
    <RefreshToken ref="variable"></RefreshToken>
</GetOAuthV2Info>

<GetOAuthV2Info> 속성

<GetOAuthV2Info async="false" continueOnError="false" enabled="true" name="Get-OAuth-v20-Info-1">

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

속성 설명 기본값 접속 상태
name

정책의 내부 이름입니다. name 속성의 값에는 문자, 숫자, 공백, 하이픈, 밑줄, 마침표가 포함될 수 있습니다. 이 값은 255자(영문 기준)를 초과할 수 없습니다.

원하는 경우 <DisplayName> 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름을 사용하여 정책에 라벨을 지정합니다.

 해당 사항 없음 필수
continueOnError

정책이 실패할 경우 오류가 반환되도록 하려면 false로 설정합니다. 이는 대부분의 정책에서 예상되는 동작입니다.

정책이 실패해도 흐름 실행이 계속되도록 하려면 true로 설정합니다. 참조:

 거짓 선택사항
enabled

정책을 시행하려면 true로 설정합니다.

정책을 중지하려면 false로 설정합니다. 정책이 흐름에 연결되어 있어도 정책이 시행되지 않습니다.

 참 선택사항
async

이 속성은 지원이 중단되었습니다.

 거짓 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본값

해당 사항 없음

이 요소를 생략하면 정책 name 속성 값이 사용됩니다.
접속 상태 선택사항
유형 문자열

<AccessToken> 요소

액세스 토큰의 프로필을 검색합니다. 액세스 코드 문자열 또는 리터럴 토큰 문자열(드문 사례)이 포함된 변수 중 하나를 전달합니다. 이 예시에서는 요청에 전달된 쿼리 매개변수에서 액세스 토큰을 검색합니다. 취소되거나 만료된 토큰에 대한 정보를 반환하려면 <IgnoreAccessTokenStatus> 요소를 사용하세요.

<AccessToken ref="request.queryparam.access_token"></AccessToken>

기본값:

request.formparam.access_token(x-www-form-urlencoded이며 요청 본문에 지정됨)

Presence:

선택사항
유형: 문자열
유효한 값:

액세스 토큰 문자열이 포함된 흐름 변수 또는 리터럴 문자열입니다.

<AuthorizationCode> 요소

승인 코드의 프로필을 검색합니다. 인증 코드 문자열 또는 리터럴 토큰 문자열(드문 사례)이 포함된 변수 중 하나를 전달합니다. 이 예시에서는 요청에 전달된 쿼리 매개변수에서 인증 코드를 가져옵니다. 이 작업으로 채워진 변수의 목록은 '흐름 변수'를 참조하세요. 

<AuthorizationCode ref="request.queryparam.authorization_code"></AuthorizationCode>

기본값:

request.formparam.access_token(x-www-form-urlencoded이며 요청 본문에 지정됨)

Presence:

선택사항
유형: 문자열
유효한 값:

인증 코드 문자열이 포함된 흐름 변수 또는 리터럴 문자열입니다.

<ClientId> 요소

클라이언트 ID와 관련된 정보를 검색합니다. 이 예시에서는 요청에 전달된 쿼리 매개변수에서 클라이언트 ID를 검색합니다. 이 작업으로 채워진 변수의 목록은 '흐름 변수'를 참조하세요. 

<ClientId ref="request.queryparam.client_id"></ClientId>

기본값:

request.formparam.access_token(x-www-form-urlencoded이며 요청 본문에 지정됨)

Presence:

선택사항
유형: 문자열
유효한 값: 인증 코드 문자열이 포함된 흐름 변수 또는 리터럴 문자열입니다.

<IgnoreAccessTokenStatus> 요소

토큰이 만료되거나 취소된 경우에도 토큰 정보를 반환합니다. 이 요소는 액세스 토큰에만 사용할 수 있습니다. 갱신 토큰과 승인 코드와 같은 다른 항목의 정보는 기본적으로 상태와 관계없이 반환됩니다.

<IgnoreAccessTokenStatus>true</IgnoreAccessTokenStatus>

기본값:

거짓

Presence:

선택사항
유형: 부울
유효한 값: true 또는 false

<RefreshToken> 요소

갱신 토큰의 프로필을 검색합니다. 갱신 코드 문자열 또는 리터럴 토큰 문자열(드문 사례)이 포함된 변수 중 하나를 전달합니다. 이 예시에서는 요청에 전달된 쿼리 매개변수에서 갱신 토큰을 검색합니다. 이 작업으로 채워진 변수의 목록은 '흐름 변수'를 참조하세요. 

<RefreshToken ref="request.queryparam.refresh_token"></RefreshToken>

기본값:

request.formparam.access_token(x-www-form-urlencoded이며 요청 본문에 지정됨)

Presence:

선택사항
유형: 문자열
유효한 값:

갱신 토큰 문자열이 포함된 흐름 변수 또는 리터럴 문자열입니다.

흐름 변수

GetOAuthV2Info 정책은 이러한 변수를 채우며, 일반적으로 프로필 데이터가 필요하지만 부여 또는 유효성 검사가 아직 수행되지 않은 경우에는 사용됩니다. .

클라이언트 ID 변수

이러한 변수는 ClientId 요소가 설정되면 채워집니다.

oauthv2client.{policy_name}.client_id
oauthv2client.{policy_name}.client_secret
oauthv2client.{policy_name}.redirection_uris // Note the spelling -- 'redirection_uris'
oauthv2client.{policy_name}.developer.email
oauthv2client.{policy_name}.developer.app.name
oauthv2client.{policy_name}.developer.id
oauthv2client.{policy_name}.{developer_app_custom_attribute_name}

액세스 토큰 변수

이러한 변수는 AccessToken 요소가 설정되면 채워집니다.

oauthv2accesstoken.{policy_name}.developer.id
oauthv2accesstoken.{policy_name}.developer.app.name
oauthv2accesstoken.{policy_name}.developer.app.id
oauthv2accesstoken.{policy_name}.developer.email

oauthv2accesstoken.{policy_name}.organization_name
oauthv2accesstoken.{policy_name}.api_product_list

oauthv2accesstoken.{policy_name}.access_token
oauthv2accesstoken.{policy_name}.scope
oauthv2accesstoken.{policy_name}.expires_in //in seconds
oauthv2accesstoken.{policy_name}.status
oauthv2accesstoken.{policy_name}.client_id
oauthv2accesstoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2accesstoken.{policy_name}.refresh_token
oauthv2accesstoken.{policy_name}.refresh_token_status
oauthv2accesstoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2accesstoken.{policy_name}.refresh_count
oauthv2accesstoken.{policy_name}.refresh_token_issued_at
oauthv2accesstoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

승인 코드 변수

이러한 변수는 AuthorizationCode 요소가 설정되면 채워집니다.

oauthv2authcode.{policy_name}.code
oauthv2authcode.{policy_name}.scope       
oauthv2authcode.{policy_name}.redirect_uri 
oauthv2authcode.{policy_name}.client_id
oauthv2authcode.{policy_name}.{auth_code_custom_attribute_name}

갱신 토큰 변수

이러한 변수는 RefreshToken 요소가 설정되면 채워집니다.

oauthv2refreshtoken.{policy_name}.developer.id
oauthv2refreshtoken.{policy_name}.developer.app.name
oauthv2refreshtoken.{policy_name}.developer.app.id
oauthv2refreshtoken.{policy_name}.developer.email
oauthv2refreshtoken.{policy_name}.organization_name
oauthv2refreshtoken.{policy_name}.api_product_list

oauthv2refreshtoken.{policy_name}.access_token
oauthv2refreshtoken.{policy_name}.scope
oauthv2refreshtoken.{policy_name}.expires_in //in seconds

oauthv2refreshtoken.{policy_name}.status
oauthv2refreshtoken.{policy_name}.client_id
oauthv2refreshtoken.{policy_name}.accesstoken.{custom_attribute_name}

oauthv2refreshtoken.{policy_name}.refresh_token
oauthv2refreshtoken.{policy_name}.refresh_token_status
oauthv2refreshtoken.{policy_name}.refresh_token_expires_in //in seconds

oauthv2refreshtoken.{policy_name}.refresh_count
oauthv2refreshtoken.{policy_name}.refresh_token_issued_at
oauthv2refreshtoken.{policy_name}.revoke_reason //Apigee hybrid only with value of REVOKED_BY_APP, REVOKED_BY_ENDUSER, REVOKED_BY_APP_ENDUSER, or TOKEN_REVOKED

스키마

각 정책 유형은 XML 스키마(.xsd)로 정의됩니다. 참고로 GitHub에서 정책 스키마를 사용할 수 있습니다.

오류 참조

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

런타임 오류

이러한 오류는 정책이 실행될 때 발생할 수 있습니다. 아래의 오류 이름은 오류가 발생할 때 fault.name 변수에 할당되는 문자열입니다. 자세한 내용은 아래의 오류 변수 섹션을 참조하세요.

오류 코드 HTTP 상태 원인
steps.oauth.v2.access_token_expired 500 정책에 전송된 액세스 토큰이 만료되었습니다.
steps.oauth.v2.authorization_code_expired 500 정책에 전송된 승인 코드가 만료되었습니다.
steps.oauth.v2.invalid_access_token 500 정책에 전송된 액세스 토큰이 잘못되었습니다.
steps.oauth.v2.invalid_client-invalid_client_id 500 정책에 전송된 클라이언트 ID가 잘못되었습니다.
steps.oauth.v2.invalid_refresh_token 500 정책에 전송된 갱신 토큰이 잘못되었습니다.
steps.oauth.v2.invalid_request-authorization_code_invalid 500 정책에 전송된 승인 코드가 잘못되었습니다.
steps.oauth.v2.InvalidAPICallAsNoApiProductMatchFound 401 이 오류의 문제 해결 방법에 대한 자세한 내용은 Oauth2.0 액세스 토큰 확인에서 'apiproduct matches not apiapi found' 오류 발생을 참조하세요.
steps.oauth.v2.refresh_token_expired 500 정책에 전송된 갱신 토큰이 만료되었습니다.

배포 오류

배포 오류에 대한 자세한 내용은 UI에 보고된 메시지를 참조하세요.

오류 변수

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

변수 장소 예
fault.name="fault_name" fault_name은 위의 런타임 오류 표에 나열된 오류 이름입니다. 오류 이름은 오류 코드의 마지막 부분입니다. fault.name Matches "IPDeniedAccess"
oauthV2.policy_name.failed policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. oauthV2.GetTokenInfo.failed = true
oauthV2.policy_name.fault.name policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. oauthV2.GetToKenInfo.fault.name = invalid_client-invalid_client_id
oauthV2.policy_name.fault.cause policy_name은 오류를 발생시킨 정책의 사용자 지정 이름입니다. oauthV2.GetTokenInfo.cause = ClientID is Invalid

오류 응답 예시

{  
   "fault":{  
      "faultstring":"ClientId is Invalid",
      "detail":{  
         "errorcode":"keymanagement.service.invalid_client-invalid_client_id"
      }
   }
}

오류 규칙 예시

<FaultRule name="OAuthV2 Faults">
    <Step>
        <Name>AM-InvalidClientIdResponse</Name>
    </Step>
    <Condition>(fault.name = "invalid_client-invalid_client_id")</Condition>
</FaultRule>

관련 주제