OAuthV2 정책

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

Apigee Edge 문서 보기

제목

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

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

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

샘플

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

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

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

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

<DisplayName> 요소

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

<DisplayName>Policy Display Name</DisplayName>

<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에 액세스하는 데 사용되는 도메인입니다.

<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 요소도 사용되는 경우에만 효과가 있습니다.

<Algorithm>

<Algorithm>algorithm-here</Algorithm>

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

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

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

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

<CacheExpiryInSeconds> 요소

<CacheExpiryInSeconds ref="propertyset.settings.token-ttl">60</CacheExpiryInSeconds>

이 요소는 VerifyAccessToken 작업에만 사용할 수 있습니다. 특정 정책 실행의 액세스 토큰 캐시에서 TTL (수명)을 지정합니다. Apigee가 OAuth 2 액세스 토큰을 처음 확인할 때는 영구 저장소에서 액세스 토큰을 가져와야 합니다. 이는 비교적 비용이 많이 드는 작업이므로 Apigee는 토큰 상태, 토큰이 유효한 제품 목록, 토큰에 연결된 맞춤 속성을 비롯한 토큰 조회 결과를 캐시합니다. TTL이 만료될 때까지 OAuthV2/VerifyAccessToken를 계속 호출하면 메모리 내 캐시된 결과가 읽히므로 토큰 확인이 훨씬 빨라집니다.

액세스 토큰 캐시의 기본 TTL은 180초입니다. 이 요소를 사용하면 TTL을 줄여 정확성을 위해 성능을 희생할 수 있습니다. 토큰을 취소하는 경우가 있고 Apigee에서 취소된 토큰을 유효한 것으로 계속 처리하는 시간 범위를 줄이려는 경우 이 방법이 유용합니다.

지원되는 범위는 1~180초입니다. 흐름 변수와 기본값을 제공할 수 있습니다. 흐름 변수를 제공하고 숫자 값이 포함된 경우 지정된 기본값보다 우선 적용됩니다.

속성

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

<ClientId> 요소

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

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

<Code> 요소

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

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

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

<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 시스템에서 자동으로 삭제됩니다. 액세스 토큰 삭제도 참조하세요.

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

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

<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로 설정합니다. OAuth 2.0 토큰 가져오기도 참조하세요.

<Operation> 요소

<Operation>GenerateAuthorizationCode</Operation>

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

<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 토큰 가져오기도 참조하세요.

<PrivateKey>/<Value>

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

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

<PublicKey>/<Value>

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

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

<RedirectUri> 요소

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

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

리디렉션 URI 정보

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

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

• (선택사항) 콜백 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 토큰 가져오기도 참조하세요.

<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 토큰 가져오기도 참조하세요.

<RefreshTokenExpiresIn> 요소

<RefreshTokenExpiresIn>1000</RefreshTokenExpiresIn>

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

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

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

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

<ResponseType> 요소

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

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

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

<ReuseRefreshToken> 요소

<ReuseRefreshToken>true</ReuseRefreshToken>

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

<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"} 형식입니다.

<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바이트입니다. 낮은 안정성의 키를 사용하면 런타임 오류가 발생합니다.

<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 토큰 가져오기도 참조하세요.

<State> 요소

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

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

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

<StoreToken> 요소

 <StoreToken>true</StoreToken>

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

<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 매개변수의 값이 지원되는 부여 유형 중 하나와 일치하는지 확인합니다.

<Tokens>/<Token> 요소

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

<UserName> 요소

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

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

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

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

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

액세스 토큰 확인

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 사양을 기반으로 합니다. 앱이 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 또는 자바스크립트 정책을 사용하여 이러한 변수를 읽고 나중에 흐름에서 필요에 따라 사용할 수 있습니다. 이러한 변수는 디버깅하는 데도 유용할 수 있습니다.

토큰별 변수

앱별 변수

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

AppGroup 관련 변수

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

개발자별 변수

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

오류 참조

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

런타임 오류

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

JWT 토큰별 런타임 오류

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

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

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

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

토큰 확인 흐름 오류 코드

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

배포 오류

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

JWT 토큰별 배포 오류

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

오류 변수

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

오류 응답 예시

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

스토리지의 토큰이 해싱됨

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

기본 OAuth 구성 작업

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

액세스 토큰 삭제

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

RFC를 준수하지 않는 동작

기본적으로 GenerateAccessToken 작업과 함께 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 소개