OAuthV2 정책

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동
정보

내용

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

팁: Apigee Edge의 OAuth에 대한 자세한 내용은 OAuth 홈페이지를 참조하세요. 리소스, 샘플, 동영상 등의 링크를 제공합니다. 이 정책이 실제 애플리케이션에서 어떻게 사용되는지 자세히 알아보려면 GitHub의 고급 OAuth 샘플을 참고하세요.

샘플

VerifyAccessToken

VerifyAccessToken

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

<OAuthV2 async="false" continueOnError="false" enabled="true" name="OAuth-v20-2">
    <DisplayName>OAuth v2.0 2</DisplayName>
    <Operation>VerifyAccessToken</Operation>
    <AccessTokenPrefix>Bearer</AccessTokenPrefix> <!-- Optional, default is Bearer -->
</OAuthV2>

참고: OAuth 2.0 Bearer 토큰만 지원됩니다. 메시지 인증 코드(MAC) 토큰은 지원되지 않습니다.

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

$ curl -H "Authorization: Bearer ylSkZIjbdWybfsUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282

기본적으로 Edge는 Authorization 헤더에 Bearer 프리픽스가 있는 액세스 토큰을 허용합니다. 이 기본값은 <AccessToken> 요소를 사용하여 변경할 수 있습니다.

GenerateAccessToken

액세스 토큰 생성

지원되는 각 부여 유형의 액세스 토큰을 요청하는 방법은 액세스 토큰 및 승인 코드 요청을 참조하세요. 이 주제에는 다음 작업의 예시가 포함됩니다.

GenerateAuthorizationCode

승인 코드 생성

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

RefreshAccessToken

액세스 토큰 새로고침

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

응답 흐름 토큰

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

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

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

<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 client_id = context.getVariable("local_clientid");
var client_secret = context.getVariable("local_secret");
context.setVariable("request.header.Authorization","Basic "+CryptoJS.enc.Base64.stringify(CryptoJS.enc.Latin1
                                      .parse(client_id + ':' + client_secret)));

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

요소 참조

정책 참조는 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">

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

속성 설명 기본 계정 현재 상태
name

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

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

N/A 필수
continueOnError

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

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

false 선택사항
enabled

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

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

true 선택사항
async

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

false 지원 중단됨

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>
기본 계정

N/A

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

현재 상태 선택사항
유형 문자열

<AccessToken> 요소

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

기본적으로 VerifyAccessToken은 액세스 토큰이 Authorization 헤더로 전송될 것으로 예상합니다. 이 요소를 사용하여 기본값을 변경할 수 있습니다. 예를 들어 request.queryparam.access_token은 액세스 토큰이 access_token이라는 쿼리 매개변수로 존재해야 함을 나타냅니다.

<AccessToken>request.header.access_token</AccessToken>이 지정된 예:

curl https://myorg-myenv.apigee.net/oauth2/validate -H "access_token:Rft3dqrs56Blirls56a"
<AccessToken>request.queryparam.access_token</AccessToken>가 지정된 경우의 예시는 다음과 같습니다.

curl "https://myorg-myenv.apigee.net/oauth2/validate?access_token:Rft3dqrs56Blirls56a"

기본값:

N/A

현재 상태:

선택사항

유형: 문자열
작업과 함께 사용:
  • VerifyAccessToken

<AccessTokenPrefix> 요소

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

기본적으로 VerifyAccessToken은 액세스 토큰이 Bearer 토큰으로 승인 헤더에 전송될 것으로 예상합니다. 예를 들면 다음과 같습니다.

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

현재 Bearer는 유일하게 지원되는 프리픽스입니다.

기본값:

Bearer

현재 상태:

선택사항

유형: 문자열
유효한 값:

Bearer

작업과 함께 사용:
  • VerifyAccessToken

<AppEndUser> 요소

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

앱 최종 사용자 ID를 승인 서버로 전송해야 하는 경우 이 요소를 통해 Edge에서 최종 사용자 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 액세스 토큰의 검색 및 취소 사용 설정을 참조하세요.

기본값:

N/A

현재 상태:

선택사항

유형: 문자열
유효한 값:

런타임 시 정책에 액세스할 수 있는 모든 흐름 변수

부여 유형과 함께 사용:
  • 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를 설정하면 이 목표를 달성할 수 있습니다. 하지만 나중에 갱신 토큰을 사용하여 새 액세스 토큰을 생성하면 액세스 토큰의 원래 커스텀 속성이 갱신 토큰 응답에 표시됩니다. 이는 Edge가 액세스 토큰 생성 정책에서 display 속성이 원래 false로 설정되었음을 기억하지 못하기 때문입니다. 커스텀 속성은 액세스 토큰 메타데이터의 일부일 뿐입니다.

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

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

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

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

기본값:

N/A

Presence:

선택사항

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

<ClientId> 요소

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

경우에 따라 클라이언트 앱은 클라이언트 ID를 승인 서버로 전송해야 합니다. 이 요소를 사용하면 Edge에서 클라이언트 ID를 찾을 위치를 지정할 수 있습니다. 설정할 수 있는 유효한 위치는 기본 위치(흐름 변수 request.formparam.client_id) 뿐입니다. ClientId를 다른 변수로 설정하면 지원되지 않습니다. 액세스 토큰 및 승인 코드 요청도 참조하세요.

기본값:

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 Edge)에 승인 코드를 제출해야 합니다. 이 요소를 사용하면 Edge가 승인 코드를 찾을 위치를 지정할 수 있습니다. 예를 들어 쿼리 매개변수, HTTP 헤더 또는 양식 매개변수(기본값)로 전송될 수 있습니다.

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

기본값:

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 Edge for Public Cloud의 경우 Edge는 항목에 액세스한 후 최소 180초 동안 다음 항목을 캐시에 유지합니다.

  • OAuth 액세스 토큰. 즉, 해지된 토큰은 캐시 한도가 만료될 때까지 최대 3분 동안 계속 성공할 수 있습니다.
  • 키 관리 서비스(KMS) 항목(앱, 개발자, API 제품)
  • OAuth 토큰 및 KMS 항목의 맞춤 속성입니다.

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

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

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

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

Private Cloud: Private Cloud용 Edge 설치의 경우 기본값은 conf_keymanagement_oauth_auth_code_expiry_time_in_millis 속성으로 설정됩니다. 이 속성을 설정하는 방법은 다음과 같습니다.

  1. 편집기에서 message-processor.properties 파일을 엽니다. 파일이 없으면 다음과 같이 만듭니다.
    vi /opt/apigee/customer/application/message-processor.properties
  2. 원하는 대로 속성을 설정합니다.
    conf_keymanagement_oauth_auth_code_expiry_time_in_millis=3600000
  3. 속성 파일을 'apigee' 사용자가 소유해야 합니다.
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. 메시지 프로세서를 다시 시작합니다.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

기본값:

지정되지 않은 경우 시스템은 시스템 수준에서 구성된 기본값을 적용합니다.

Presence:

선택사항

유형: 정수
유효한 값:
  • 0이 아닌 양의 정수입니다. 만료 시간을 밀리초로 지정합니다. 이 요소의 값은 밀리초 단위이지만 토큰의 expires_in 속성과 expires_in 흐름 변수에 설정된 값은 초 단위로 표현됩니다.
  • -1로 설정하면 최대 OAuth 액세스 토큰 만료에 따라 만료됩니다.

    참고: 다른 음의 정수 또는 0을 지정하면 배포 오류가 발생합니다.

    피해야 할 패턴: OAuth 토큰에 긴 만료 시간 설정도 참고하세요.

부여 유형과 함께 사용:
  • authorization_code
  • 암시적
  • 비밀번호
  • client_credentials
  • refresh_token

GenerateAuthorizationCode 작업에도 사용됩니다.

<ExternalAccessToken> 요소

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

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

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

<ExternalAuthorization> 요소

<ExternalAuthorization>true</ExternalAuthorization>

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

기본값:

false

현재 상태:

선택사항

유형: 불리언
유효한 값: true 또는 false
부여 유형과 함께 사용:
  • authorization_code
  • 비밀번호
  • client_credentials

<ExternalAuthorizationCode> 요소

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

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

변수 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 Edge에 외부 갱신 토큰 (Apigee Edge에서 생성되지 않은 갱신 토큰)을 찾을 위치를 알려줍니다.

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

<GenerateResponse> 요소

<GenerateResponse enabled='true'/>

true로 설정하면 정책에서 응답을 생성하고 반환합니다. 예를 들어 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인 경우 응답이 전송되지 않습니다. 대신 흐름 변수 집합이 정책 함수와 관련된 값으로 채워집니다. 예를 들어 oauthv2authcode.OAuthV2-GenerateAuthorizationCode.code라는 흐름 변수는 새로 발급된 인증 코드로 채워집니다. expires_in은 응답에서 초 단위로 표현됩니다.

기본값:

false

현재 상태:

선택사항

유형: string
유효한 값: true 또는 false
부여 유형과 함께 사용:
  • 암시적
  • 비밀번호
  • client_credentials
  • refresh_token
  • GenerateAuthorizationCode 작업에도 사용할 수 있습니다.

<GenerateErrorResponse> 요소

<GenerateErrorResponse enabled='true'/>

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

기본값:

false

현재 상태:

선택사항

유형: string
유효한 값: 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로 설정합니다. 액세스 토큰 및 승인 코드 요청도 참조하세요.

기본값:

request.formparam.grant_type (x-www-form-urlencoded 및 요청 본문에 지정됨)

Presence:

선택사항

유형: string
유효한 값: 위에 설명된 대로 변수
부여 유형과 함께 사용:
  • authorization_code
  • 비밀번호
  • 암시적
  • client_credentials
  • refresh_token

<Operation> 요소

<Operation>GenerateAuthorizationCode</Operation>

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

기본값:

<Operation>이 지정되지 않으면 Edge가 <SupportedGrantTypes> 목록을 확인합니다. 이러한 부여 유형에 대한 작업만 성공합니다. 즉, <SupportedGrantTypes> 목록에서 <GrantType>을 지정하면 <Operation>을 생략할 수 있습니다. <Operation> 또는 <SupportedGrantTypes>도 지정되지 않은 경우 기본 부여 유형은 authorization_code입니다. 즉, 승인 코드 부여 유형 요청은 성공하지만 나머지는 실패합니다.

Presence:

선택사항

유형: 문자열
유효한 값:

<PassWord> 요소

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

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

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

OAuthV2 정책은 이 사용자 인증 정보 값으로 다른 작업을 하지 않습니다. Edge는 단순히 이 값이 존재하는지 확인하는 것입니다. 토큰 생성 정책을 실행하기 전에 값 요청을 검색하여 ID 공급업체로 전송하는 것은 API 개발자의 책임입니다.

액세스 토큰 및 승인 코드 요청도 참조하세요.

기본값:

request.formparam.password (x-www-form-urlencoded 및 요청 본문에 지정됨)

Presence:

선택사항

유형: 문자열
유효한 값: 런타임에 정책에 사용할 수 있는 흐름 변수입니다.
부여 유형과 함께 사용: 비밀번호

<RedirectUri> 요소

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

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

리디렉션 URI 정보

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

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

  • (선택사항) 콜백 URL이 등록되고 요청에서 redirect_uri이 누락된 경우 Edge는 등록된 콜백 URL로 리디렉션됩니다.
  • (필수사항) 콜백 URL이 등록되지 않은 경우 redirect_uri는 필수입니다. 이 경우 Edge는 모든 URL을 허용합니다. 이 경우 보안 문제가 발생할 수 있으므로 신뢰할 수 있는 클라이언트 앱에서만 사용해야 합니다. 클라이언트 앱을 신뢰할 수 없는 경우 항상 콜백 URL 등록을 요구하는 것이 좋습니다.

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

기본값:

request.formparam.redirect_uri (x-www-form-urlencoded 및 요청 본문에 지정됨)

Presence:

선택사항

유형: 문자열
유효한 값: 런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:
  • authorization_code
  • 암시적

GenerateAuthorizationCode 작업에도 사용됩니다.

<RefreshToken> 요소

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

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

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

기본값:

request.formparam.refresh_token (x-www-form-urlencoded 및 요청 본문에 지정됨)

Presence:

선택사항

유형: 문자열
유효한 값: 런타임 시 정책에 액세스할 수 있는 모든 흐름 변수
부여 유형과 함께 사용:
  • refresh_token

<RefreshTokenExpiresIn> 요소

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

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

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

Private Cloud: Private Cloud용 Edge 설치의 경우 기본값은 conf_keymanagement_oauth_refresh_token_expiry_time_in_millis 속성으로 설정됩니다. 이 속성을 설정하는 방법은 다음과 같습니다.

  1. 편집기에서 message-processor.properties 파일을 엽니다. 파일이 없으면 다음과 같이 만듭니다.
    vi /opt/apigee/customer/application/message-processor.properties
  2. 원하는 대로 속성을 설정합니다.
    conf_keymanagement_oauth_refresh_token_expiry_time_in_millis=3600000
  3. 속성 파일을 'apigee' 사용자가 소유해야 합니다.
    chown apigee:apigee /opt/apigee/customer/application/message-processor.properties
  4. 메시지 프로세서를 다시 시작합니다.
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart

기본값:

지정되지 않은 경우 시스템은 시스템 수준에서 구성된 기본값을 적용합니다.

Presence:

선택사항

유형: 정수
유효한 값:
부여 유형과 함께 사용:
  • authorization_code
  • 비밀번호
  • refresh_token

<ResponseType> 요소

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

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

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

기본값:

request.formparam.response_type(x-www-form-url로 인코딩되어 요청 본문에 지정됨)

Presence:

선택사항입니다. 기본 동작을 재정의하려면 이 요소를 사용합니다.

유형: 문자열
유효한 값: code(승인 코드 부여 유형의 경우) 또는 token(암시적 부여 유형의 경우)
부여 유형과 함께 사용:
  • 암시적
  • GenerateAuthorizationCode 작업에도 사용됩니다.

<ReuseRefreshToken> 요소

<ReuseRefreshToken>true</ReuseRefreshToken>

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

기본값:

false

Presence:

선택사항

유형: boolean
유효한 값:

true 또는 false

부여 유형과 함께 사용:
  • refresh_token

<Scope> 요소

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

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

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

<Scope>A B</Scope>

OAuth2 범위 작업액세스 토큰 및 승인 코드 요청도 참조하세요.

기본값:

범위 없음

Presence:

선택사항

유형: 문자열
유효한 값:

Generate* 정책과 함께 사용되는 경우 흐름 변수입니다.

VerifyAccessToken과 함께 사용되는 경우 공백으로 구분된 범위 이름(문자열) 목록입니다.

부여 유형과 함께 사용:
  • authorization_code
  • 암시적
  • 비밀번호
  • client_credentials
  • GenerateAuthorizationCode 및 VerifyAccessToken 작업에도 사용할 수 있습니다.

<State> 요소

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

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

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

기본값:

상태 없음

Presence:

선택사항

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

<StoreToken> 요소

 <StoreToken>true</StoreToken> 

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

기본값:

false

현재 상태:

선택사항

유형: 불리언
유효한 값: 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 Edge에서 OAuth 토큰 엔드포인트에서 지원하는 권한 부여 유형을 지정합니다. 엔드포인트는 여러 부여 유형을 지원할 수 있습니다. 즉, 단일 엔드포인트를 구성하여 여러 부여 유형에 대한 액세스 토큰을 배포할 수 있습니다. 엔드포인트에 대한 자세한 내용은 OAuth 엔드포인트 이해를 참조하세요. 부여 유형은 grant_type 매개변수로 토큰 요청에 전달됩니다.

지원되는 부여 유형을 지정하지 않으면 허용되는 유일한 부여 유형은 authorization_codeimplicit입니다. <GrantType> 요소 (Apigee Edge가 클라이언트 요청에 전달된 grant_type 매개변수를 찾아야 하는 위치를 지정하는 데 사용되는 상위 수준 요소)를 참조하세요. Edge는 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>

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

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

OAuthV2 정책은 이 사용자 인증 정보 값으로 다른 작업을 하지 않습니다. Edge는 단순히 이 값이 존재하는지 확인하는 것입니다. 토큰 생성 정책을 실행하기 전에 값 요청을 검색하여 ID 공급업체로 전송하는 것은 API 개발자의 책임입니다.

액세스 토큰 및 승인 코드 요청도 참조하세요.

기본값:

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 헤더의 경우)에 제공될 것으로 예상되면 이 설정을 사용합니다.

액세스 토큰 확인액세스 토큰 및 승인 코드 요청도 참조하세요.

요청 변수 위치 지정

이 정책은 각 권한 유형에 대해 요청 메시지의 위치 또는 필수 정보에 대한 가정을 합니다. 이러한 가정은 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 또는 자바스크립트 정책을 사용하여 이러한 변수를 읽고 나중에 흐름에서 필요에 따라 사용할 수 있습니다. 이러한 변수는 디버깅하는 데도 유용할 수 있습니다.

토큰별 변수

변수 설명
organization_name 프록시가 실행 중인 조직의 이름입니다.
developer.id 등록된 클라이언트 앱과 연결된 개발자의 ID입니다.
developer.app.name 등록된 클라이언트 앱과 연결된 개발자의 이름입니다.
client_id 등록된 클라이언트 앱의 클라이언트 ID입니다.
grant_type 요청과 연결된 권한 유형입니다.
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만 해당) 액세스 토큰이 취소된 이유를 나타냅니다.

값은 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} 등록된 클라이언트 앱에 대해 이름이 지정된 맞춤 속성입니다.

개발자별 변수

app.appType이 'Company'이면 회사 속성이 채워지고 app.appType이 'Developer'인 경우 개발자 속성이 채워집니다.

변수 설명
개발자별 변수
developer.id
developer.userName
developer.firstName
developer.lastName
developer.email
developer.status 활성 또는 비활성
developer.apps
developer.created_by
developer.created_at
developer.last_modified_at
developer.last_modified_by
developer.{custom_attributes} 개발자에 대해 이름이 지정된 맞춤 속성입니다.

회사별 변수

app.appType이 'Company'이면 회사 속성이 채워지고 app.appType이 'Developer'인 경우 개발자 속성이 채워집니다.

변수 설명
company.id
company.displayName
company.apps
company.appOwnerStatus
company.created_by
company.created_at
company.last_modified_at
company.last_modified_by
company.{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> 요소를 참조하세요.

오류 참조

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

런타임 오류

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

오류 코드 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_clientInvalidClientIdentifier 이름을 모두 캡처하도록 기존 오류 규칙 조건을 변경하는 것이 좋습니다. 자세한 내용과 예시는 16.09.21 출시 노트를 참조하세요.

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\
steps.oauth.v2.ApiProductMatchFound
401

API 프록시가 액세스 토큰과 연결된 제품에 없습니다.

팁: 액세스 토큰과 연결된 제품이 올바르게 구성되었는지 확인하세요. 예를 들어 리소스 경로에 와일드 카드를 사용할 경우 와일드 카드가 올바르게 사용되고 있는지 확인합니다. 자세한 내용은 API 제품 만들기를 참고하세요.

이 오류의 원인에 대한 자세한 내용은 이 Apigee 커뮤니티 게시물을 참조하세요.

VerifyAccessToken
steps.oauth.v2.InvalidClientIdentifier 500

이 오류 이름은 정책의 <GenerateResponse> 속성이 false로 설정되고 요청에 전송된 클라이언트 ID가 잘못된 경우에 반환됩니다. 프록시와 연결된 개발자 앱에서 올바른 클라이언트 키와 보안 비밀 값을 사용하는지 확인합니다. 일반적으로 이 값은 Base64로 인코딩된 기본 승인 헤더로 전송됩니다.

참고: 이러한 경우 이 오류를 invalid_client라고 했습니다. 기존 오류 규칙 조건을 변경하여 invalid_clientInvalidClientIdentifier 이름을 둘 다 선택하는 것이 좋습니다. 자세한 내용과 예시는 16.09.21 출시 노트를 참조하세요.

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

배포 오류

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

오류 이름 원인
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> 값을 지정해야 합니다.

오류 변수

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

변수 각 항목의 의미는 다음과 같습니다.
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이면 이러한 응답은 클라이언트로 다시 전송됩니다.

<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>

정책 스키마

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

기본 OAuth 구성 작업

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

액세스 토큰 삭제

기본적으로 OAuth2 토큰은 액세스 토큰과 갱신 토큰 (있는 경우)이 모두 만료된 후 3일 (259, 200초) 후에 Apigee Edge 시스템에서 삭제됩니다. 경우에 따라 이 기본 동작을 변경해야 할 수 있습니다. 예를 들어 대량의 토큰이 생성되는 경우 삭제 시간을 단축하여 디스크 공간을 절약하려고 할 수 있습니다.

Private Cloud용 Edge를 사용 중인 경우 이 섹션에 설명된 대로 조직 속성을 설정하여 이 기본값을 변경할 수 있습니다. (만료된 토큰 3일 삭제는 프라이빗 클라우드용 Edge 버전 4.19.01 이상에 적용됩니다. 이전 버전의 경우 기본 삭제 간격은 180일입니다.)

Edge Private Cloud 4.16.01 이상 버전의 삭제 설정 업데이트

참고: 이러한 설정이 적용된 생성된 토큰만 영향을 미칩니다. 이전에 생성된 토큰에는 설정이 적용되지 않습니다.

Edge Private Cloud 4.15.07의 삭제 설정 업데이트

참고: 이러한 설정이 적용된 생성된 토큰만 영향을 받습니다. 이전에 생성된 토큰에는 설정이 적용되지 않습니다.

RFC 미준수 동작

OAuthV2 정책은 RFC를 준수하지 않는 특정 속성을 포함하는 토큰 응답을 반환합니다. 다음 표는 OAuthV2 정책에서 반환하는 비준수 속성과 해당 준수 속성을 보여줍니다.

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"}

관련 주제