OAuthV2 정책

Apigee Edge 문서입니다.
Apigee X 문서로 이동하세요. 정보

대상

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

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

샘플

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

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

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

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

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<AccessToken> 요소

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

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

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

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

<AccessTokenPrefix> 요소

<AccessTokenPrefix>Bearer</AccessTokenPrefix>

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

-H "Authorization: Bearer Rft3dqrs56Blirls56a"

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

<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 액세스 토큰의 검색 및 취소 사용 설정을 참조하세요.

<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 정책을 사용하여 원래 액세스 토큰에서 원래 맞춤 값을 검색해야 할 수 있습니다.
• 자바스크립트 후처리 정책을 사용하여 응답에서 보고 싶지 않은 맞춤 속성을 수동으로 추출합니다.

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

<ClientId> 요소

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

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

<Code> 요소

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

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

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

<ExpiresIn> 요소

<ExpiresIn>10000</ExpiresIn> 

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

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

퍼블릭 클라우드용 Apigee Edge를 사용하면 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

<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 토큰 사용을 참조하세요.

<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은 응답에서 초 단위로 표현됩니다.

<GenerateErrorResponse> 요소

<GenerateErrorResponse enabled='true'/>

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

<GrantType>

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

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

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

<Operation> 요소

<Operation>GenerateAuthorizationCode</Operation>

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

<PassWord> 요소

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

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

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

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

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

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

<RefreshToken> 요소

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

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

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

<RefreshTokenExpiresIn> 요소

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

<ResponseType> 요소

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

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

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

<ReuseRefreshToken> 요소

<ReuseRefreshToken>true</ReuseRefreshToken>

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

<Scope> 요소

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

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

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

<Scope>A B</Scope>

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

<State> 요소

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

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

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

<StoreToken> 요소

 <StoreToken>true</StoreToken> 

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

<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_code 및 implicit입니다. <GrantType> 요소도 참고하세요. 이 요소는 Apigee Edge가 클라이언트 요청에서 전달된 grant_type 매개변수를 찾아야 하는 위치를 지정하는 데 사용되는 상위 수준 요소입니다. Edge는 grant_type 매개변수의 값이 지원되는 부여 유형 중 하나와 일치하는지 확인합니다.

<Tokens>/<Token> 요소

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

<UserName> 요소

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

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

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

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

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

액세스 토큰 확인

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 작업의 기본 설정을 재정의할 수 있습니다.

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

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

요청 변수 위치 지정

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

토큰별 변수

앱별 변수

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

개발자별 변수

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

회사별 변수

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

GenerateAuthorizationCode 작업

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

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

예: oauthv2authcode.GenerateCodePolicy.code

GenerateAccessToken 및 RefreshAccessToken 작업

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

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

예: oauthv2accesstoken.GenerateTokenPolicy.access_token

GenerateAccessTokenImplicitGrant

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

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

예: oauthv2accesstoken.RefreshTokenPolicy.access_token

오류 참조

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

런타임 오류

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

배포 오류

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

오류 변수

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

오류 응답 예시

<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일 삭제는 Private Cloud용 Edge 버전 4.19.01 이상에 적용됩니다. 이전 버전의 경우 기본 삭제 간격은 180일입니다.)

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

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

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

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

RFC를 준수하지 않는 동작

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

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

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

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

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

관련 주제

• OAuth 2.0 소개