이 페이지는 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 |
정책의 내부 이름입니다. 원하는 경우 |
해당 사항 없음 | 필수 |
continueOnError |
정책이 실패할 경우 오류가 반환되도록 하려면 정책이 실패해도 흐름 실행이 계속되도록 하려면 |
거짓 | 선택사항 |
enabled |
정책을 시행하려면 정책을 중지하려면 |
참 | 선택사항 |
async |
이 속성은 지원이 중단되었습니다. |
거짓 | 지원 중단됨 |
<DisplayName> 요소
name
속성 외에도 이 요소를 사용하여 관리 UI 프록시 편집기의 정책에 다른 자연어 이름으로 라벨을 지정합니다.
<DisplayName>Policy Display Name</DisplayName>
기본값 |
해당 사항 없음 이 요소를 생략하면 정책 |
---|---|
접속 상태 | 선택사항 |
유형 | 문자열 |
<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>