액세스 토큰 및 승인 코드 요청

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

이 주제에서는 액세스 토큰 및 승인 코드를 요청하고, OAuth 2.0 엔드포인트를 구성하고, 지원되는 각 부여 유형에 대해 정책을 구성하는 방법을 보여줍니다.

샘플 코드

편의를 위해 이 주제에서 설명하는 정책 및 엔드포인트가 GitHub의 Apigee api-platform-samples 저장소에 있는 oauth-doc-examples 프로젝트에서 제공됩니다. 샘플 코드를 배포하고 이 주제에 표시된 샘플 요청을 사용해 볼 수 있습니다. 자세한 내용은 프로젝트 README를 참조하세요.

액세스 토큰 요청: 승인 코드 부여 유형

이 섹션에서는 승인 코드 부여 유형 흐름을 사용하여 액세스 토큰을 요청하는 방법을 설명합니다. OAuth 2.0 부여 유형에 대한 소개는 OAuth 2.0 소개를 참조하세요.

샘플 요청

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
   -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
   -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
   -d 'code=I9dMGHAN&grant_type=authorization_code&redirect_uri=http://example-callback.com'

필수 매개변수

기본적으로 이러한 매개변수는 x-www-form-urlencoded여야 하며 요청 본문에 지정되어야 합니다(위의 샘플 참조). 그러나 이 /accesstoken 엔드포인트에 연결된 OAuthV2 정책에서 <GrantType>, <Code>, <RedirectUri> 요소를 구성하여 이 기본값을 변경할 수 있습니다. 자세한 내용은 OAuthV2 정책을 참조하세요.

  • grant_type - authorization_code 값으로 설정해야 합니다.
  • code - /authorize 엔드포인트(또는 원하는 아무 이름)에서 받은 승인 코드입니다. 승인 코드 부여 유형 흐름에서 액세스 토큰을 요청하려면 먼저 승인 코드를 받아야 합니다. 아래의 승인 코드 요청을 참조하세요. 승인 코드 부여 유형 구현을 참조하세요.
  • redirect_uri - redirect_uri 매개변수가 이전 승인 코드 요청에 포함되면 이 매개변수를 제공해야 합니다. redirect_uri 매개변수가 승인 코드 요청에 포함되어 있지 않고 이 매개변수를 제공하지 않으면 이 정책은 개발자 앱이 등록될 때 제공된 콜백 URL의 값을 사용합니다.

선택적 매개변수

  • state - 응답과 함께 다시 전송되는 문자열입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하는 데 사용됩니다.
  • scope - 발급된 토큰을 사용할 수 있는 API 제품 목록을 필터링할 수 있습니다. 범위에 대한 자세한 내용은 OAuth2 범위 다루기을 참조하세요.

인증

클라이언트 ID와 클라이언트 보안 비밀번호를 기본 인증 헤더(Base64 인코딩) 또는 양식 매개변수 client_idclient_secret로 전달해야 합니다. 등록된 개발자 앱에서 이러한 값을 가져옵니다. '기본 사용자 인증 정보 인코딩'도 참조하세요.

샘플 엔드포인트

다음은 액세스 토큰을 생성하기 위한 샘플 엔드포인트 구성입니다. 이는 authorization_code 부여 유형을 지원하도록 구성되어야 하는 GenerateAccessToken 정책을 실행합니다.

...
       <Flow name="generate-access-token">
            <Description>Generate a token</Description>
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

샘플 정책

이는 authorization_code 부여 유형을 허용하도록 구성된 기본 GenerateAccessToken 정책입니다. 이 정책으로 구성할 수 있는 선택적 구성 요소에 대한 자세한 내용은 OAuthV2 정책을 참조하세요.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn>
    <RefreshTokenExpiresIn>86400000</RefreshTokenExpiresIn>
    <SupportedGrantTypes>
      <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

반환

<GenerateResponse>를 사용 설정하면 정책은 아래와 같이 액세스 토큰이 포함된 JSON 응답을 반환합니다. authorization_code 부여 유형은 액세스 토큰과 갱신 토큰을 생성하므로 다음과 같은 응답이 반환됩니다.

{
    "issued_at": "1420262924658",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420262924658",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "fYACGW7OCPtCNDEnRSnqFlEgogboFPMm",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "2l4IQtZXbn5WBJdL6EF7uenOWRsi",
    "organization_name": "docs",
    "refresh_token_expires_in": "86399", //--in seconds
    "refresh_count": "0"
}

<GenerateResponse>가 false로 설정되면 정책이 응답을 반환하지 않습니다. 그 대신 다음과 같은 흐름 변수 집합을 액세스 토큰 부여와 관련된 데이터로 채웁니다.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

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

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

액세스 토큰 요청: 클라이언트 사용자 인증 정보 부여 유형

이 섹션에서는 클라이언트 사용자 인증 정보 부여 유형 흐름을 사용하여 액세스 토큰을 요청하는 방법을 설명합니다. OAuth 2.0 부여 유형에 대한 소개는 OAuth 2.0 소개를 참조하세요.

샘플 요청

다음 호출에서 기본 인증 헤더를 인코딩하는 방법은 '기본 인증 사용자 인증 정보 인코딩'을 참조하세요.

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHoAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

필수 매개변수

기본적으로 필수 grant_type 매개변수는 x-www-form-urlencoded여야 하며 요청 본문에 지정되어야 합니다(위의 샘플 참조). 그러나 이 /accesstoken 엔드포인트에 연결된 OAuthV2 정책에서 <GrantType> 요소를 구성하여 이 기본값을 변경할 수 있습니다. 예를 들어 쿼리 매개변수에 매개변수를 전달하도록 선택할 수 있습니다. 자세한 내용은 OAuthV2 정책을 참조하세요.

  • grant_type - client_credentials 값으로 설정해야 합니다.

선택적 매개변수

  • state - 응답과 함께 다시 전송되는 문자열입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하는 데 사용됩니다.
  • scope - 발급된 토큰을 사용할 수 있는 API 제품 목록을 필터링할 수 있습니다. 범위에 대한 자세한 내용은 OAuth2 범위 다루기을 참조하세요.

인증

클라이언트 ID와 클라이언트 보안 비밀번호를 기본 인증 헤더(Base64 인코딩) 또는 양식 매개변수 client_idclient_secret로 전달해야 합니다. 이러한 값은 요청과 연결된, 등록된 개발자 앱에서 가져옵니다. '기본 인증 사용자 인증 정보 인코딩'도 참조하세요.

샘플 엔드포인트

다음은 액세스 토큰을 생성하기 위한 샘플 엔드포인트 구성입니다. 이는 client_credentials 부여 유형을 지원하도록 구성되어야 하는 GenerateAccessToken 정책을 실행합니다.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

샘플 정책

이는 client_credentials 부여 유형을 허용하도록 구성된 기본 GenerateAccessToken 정책입니다. 이 정책으로 구성할 수 있는 선택적 구성 요소에 대한 자세한 내용은 OAuthV2 정책을 참조하세요.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <SupportedGrantTypes>
      <GrantType>client_credentials</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

반환

<GenerateResponse>가 사용 설정되면 정책에서 JSON 응답을 반환합니다. client_credentials 권한 부여 유형에서는 갱신 토큰이 지원되지 않으며, 액세스 토큰만 발급됩니다. 예를 들면 다음과 같습니다.

{
    "issued_at": "1420260525643",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "XkhU2DFnMGIVL2hvsRHLM00hRWav",
    "organization_name": "docs"
}

<GenerateResponse>가 false로 설정되면 정책이 응답을 반환하지 않습니다. 그 대신 다음과 같은 흐름 변수 집합을 액세스 토큰 부여와 관련된 데이터로 채웁니다.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in //--in seconds

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

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in     //--in seconds

이 섹션에서는 리소스 소유자 비밀번호 사용자 인증 정보(비밀번호) 부여 유형 흐름을 사용하여 액세스 토큰을 요청하는 방법을 설명합니다. OAuth 2.0 부여 유형에 대한 소개는 OAuth 2.0 소개를 참조하세요.

구현 방법을 보여주는 4분 길이의 동영상이 포함된 비밀번호 부여 유형에 대한 자세한 내용은 비밀번호 부여 유형 구현을 참조하세요.

샘플 요청

다음 호출에서 기본 인증 헤더를 인코딩하는 방법은 '기본 인증 사용자 인증 정보 인코딩'을 참조하세요.

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  -X POST https://docs-test.apigee.net/oauth/token \
  -d 'grant_type=password&username=the-user-name&password=the-users-password'

필수 매개변수

기본적으로 이러한 매개변수는 x-www-form-urlencoded여야 하며 요청 본문에 지정되어야 합니다(위의 샘플 참조). 그러나 이 /token 엔드포인트에 연결된 OAuthV2 정책에서 <GrantType>, <Username>, <Password> 요소를 구성하여 이 기본값을 변경할 수 있습니다. 자세한 내용은 OAuthV2 정책을 참조하세요.

사용자 인증 정보는 일반적으로 LDAP 또는 자바스크립트 정책을 사용하여 사용자 인증 정보 저장소에 맞게 검증됩니다.

  • grant_type - password 값으로 설정해야 합니다.
  • username - 리소스 소유자의 사용자 이름입니다.
  • password - 리소스 소유자의 비밀번호입니다.

선택적 매개변수

  • state - 응답과 함께 다시 전송되는 문자열입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하는 데 사용됩니다.
  • scope - 발급된 토큰을 사용할 수 있는 API 제품 목록을 필터링할 수 있습니다. 범위에 대한 자세한 내용은 OAuth2 범위 다루기을 참조하세요.

인증

클라이언트 ID와 클라이언트 보안 비밀번호를 기본 인증 헤더(Base64 인코딩) 또는 양식 매개변수 client_idclient_secret로 전달해야 합니다. 이러한 값은 요청과 연결된, 등록된 개발자 앱에서 가져옵니다. '기본 인증 사용자 인증 정보 인코딩'도 참조하세요.

샘플 엔드포인트

다음은 액세스 토큰을 생성하기 위한 샘플 엔드포인트 구성입니다. 이는 비밀번호 부여 유형을 지원하도록 구성되어야 하는 GenerateAccessToken 정책을 실행합니다.

...
       <Flow name="generate-access-token">
            <Request>
                <Step>
                    <Name>GenerateAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/token") and (request.verb = "POST")</Condition>
        </Flow>
...

샘플 정책

비밀번호 부여 유형을 수락하도록 구성된 기본 GenerateAccessToken 정책입니다. 이 정책으로 구성할 수 있는 선택적 구성 요소에 대한 자세한 내용은 OAuthV2 정책을 참조하세요.

<OAuthV2 name="GenerateAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
    <SupportedGrantTypes>
      <GrantType>password</GrantType>
    </SupportedGrantTypes>
    <GenerateResponse enabled="true"/>
</OAuthV2>

반환

<GenerateResponse>가 사용 설정되면 정책에서 JSON 응답을 반환합니다. 비밀번호 부여 유형을 사용하면 액세스 토큰과 갱신 토큰이 모두 발급됩니다. 예를 들면 다음과 같습니다.

{
    "issued_at": "1420258685042",
    "scope": "READ",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "refresh_token_issued_at": "1420258685042",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "organization_id": "0",
    "token_type": "BearerToken",
    "refresh_token": "IFl7jlijYuexu6XVSSjLMJq8SVXGOAAq",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "I6daIgMSiUgYX1K2qgQWPi37ztS6",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "0"
}

<GenerateResponse>가 false로 설정되면 정책이 응답을 반환하지 않습니다. 그 대신 다음과 같은 흐름 변수 집합을 액세스 토큰 부여와 관련된 데이터로 채웁니다.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

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

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token
oauthv2accesstoken.GenerateAccessToken.refresh_token_expires_in
oauthv2accesstoken.GenerateAccessToken.refresh_token_issued_at
oauthv2accesstoken.GenerateAccessToken.refresh_token_status

액세스 토큰 요청: 암시적 부여 유형

이 섹션에서는 암시적 부여 유형 흐름을 사용하여 액세스 토큰을 요청하는 방법을 설명합니다. OAuth 2.0 부여 유형에 대한 소개는 OAuth 2.0 소개를 참조하세요.

샘플 요청

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'https://docs-test.apigee.net/oauth/implicit?response_type=token&client_id=ABC123&redirect_uri=http://callback-example.com'

필수 매개변수

기본적으로 이러한 매개변수는 쿼리 매개변수여야 합니다(위의 샘플 참조). 그러나 이 /token 엔드포인트에 연결된 OAuthV2 정책에서 <ResponseType>, <ClientId>, <RedirectUri> 요소를 구성하여 이 기본값을 변경할 수 있습니다. 자세한 내용은 OAuthV2 정책을 참조하세요.

사용자 인증 정보는 일반적으로 LDAP 서비스 콜아웃 또는 자바스크립트 정책을 사용하여 사용자 인증 정보 저장소에 맞게 검증됩니다.

  • response_type - token 값으로 설정해야 합니다.
  • client_id - 등록된 개발자 앱의 클라이언트 ID입니다.
  • redirect_uri - 클라이언트 개발자 앱이 등록될 때 콜백 URI가 제공되지 않은 경우 이 매개변수는 필수입니다. 클라이언트 등록 시 콜백 URL이 제공되었다면 이 값과 비교하며 이 값과 정확하게 일치해야 합니다.

선택적 매개변수

  • state - 응답과 함께 다시 전송되는 문자열입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하는 데 사용됩니다.
  • scope - 발급된 토큰을 사용할 수 있는 API 제품 목록을 필터링할 수 있습니다. 범위에 대한 자세한 내용은 OAuth2 범위 다루기을 참조하세요.

인증

암시적 부여는 기본 인증이 필요하지 않습니다. 여기에 설명된 대로 클라이언트 ID를 요청 매개변수로 전달해야 합니다.

샘플 엔드포인트

다음은 액세스 토큰을 생성하기 위한 샘플 엔드포인트 구성입니다. 이는 GenerateAccessTokenImplicitGrant 정책을 실행합니다.

...
       <Flow name="generate-access-token-implicit">
            <Request>
                <Step>
                    <Name>GenerateAccessTokenImplicitGrant</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/implicit") and (request.verb = "POST")</Condition>
        </Flow>
...

샘플 정책

암시적 권한 부여 유형 흐름에 대한 토큰 요청을 처리하는 기본 GenerateAccessTokenImplicitGrant 정책입니다. 이 정책으로 구성할 수 있는 선택적 구성 요소에 대한 자세한 내용은 OAuthV2 정책을 참조하세요.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="GenerateAccessTokenImplicit">
    <DisplayName>GenerateAccessTokenImplicit</DisplayName>
    <Operation>GenerateAccessTokenImplicitGrant</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

반환

<GenerateResponse>를 사용 설정하면 정책은 응답 헤더에 302 Location 리디렉션을 반환합니다. 리디렉션은 redirect_uri 매개변수에 지정된 URL을 가리키며 액세스 토큰 및 토큰 만료 시간이 추가됩니다. 암시적 권한 부여는 갱신 토큰을 지원하지 않습니다. 예를 들면 다음과 같습니다.

https://callback-example.com#expires_in=1799&access_token=In4dKm4ueoGZRbIYJhC9yZCmTFw5

<GenerateResponse>가 false로 설정되면 정책이 응답을 반환하지 않습니다. 그 대신 다음과 같은 흐름 변수 집합을 액세스 토큰 부여와 관련된 데이터로 채웁니다.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in  //--in seconds

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

oauthv2accesstoken.GenerateAccessToken.access_token
oauthv2accesstoken.GenerateAccessToken.expires_in   //--in seconds

승인 코드 부여 유형 흐름을 사용하는 경우 액세스 토큰을 요청하기 전에 승인 코드를 받아야 합니다.

샘플 요청

$ curl -X POST -H 'Content-Type: application/x-www-form-urlencoded' \
  'http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code'

여기서 OAuthV2 GenerateAuthorizationCode 정책은 /oauth/authorize 프록시 엔드포인트에 연결됩니다(아래 샘플 엔드포인트 참조).

필수 매개변수

기본적으로 이러한 매개변수는 쿼리 매개변수여야 합니다(위의 샘플 참조). 그러나 이 /authorize 엔드포인트에 연결된 OAuthV2 정책에서 <ResponseType>, <ClientId>, <RedirectUri> 요소를 구성하여 이 기본값을 변경할 수 있습니다. 자세한 내용은 OAuthV2 정책을 참조하세요.

  • response_type - code 값으로 설정해야 합니다.
  • client_id - 등록된 개발자 앱의 클라이언트 ID입니다.

선택적 매개변수

  • redirect_uri - 부분이 아닌 전체 콜백 URI가 등록된 클라이언트 앱에 지정된 경우 이 매개변수는 선택사항이며 그렇지 않으면 필수입니다. 콜백은 Edge가 발급된 인증 코드를 전송하는 URL입니다. 앱 등록 및 API 키 관리도 참조하세요.
  • state - 응답과 함께 다시 전송되는 문자열입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하는 데 사용됩니다.
  • scope - 발급된 토큰을 사용할 수 있는 API 제품 목록을 필터링할 수 있습니다. 범위에 대한 자세한 내용은 OAuth2 범위 다루기을 참조하세요.

인증

기본 인증이 필요하지 않지만 등록된 클라이언트 앱의 클라이언트 ID는 요청에서 제공되어야 합니다.

샘플 엔드포인트

다음은 승인 코드를 생성하는 샘플 엔드포인트 구성입니다.


<OAuthV2 name="GenerateAuthorizationCode">
  <Operation>GenerateAuthorizationCode</Operation>
    <!--
    ExpiresIn, in milliseconds. The ref is optional. The explicitly specified
    value is the default, when the variable reference cannot be resolved.
        60000 = 1 minute
       120000 = 2 minutes
    -->
  <ExpiresIn>60000</ExpiresIn>
  <GenerateResponse enabled="true"/>
</OAuthV2>

샘플 정책

기본 GenerateAuthorizationCode 정책입니다. 이 정책으로 구성할 수 있는 선택적 구성 요소에 대한 자세한 내용은 OAuthV2 정책을 참조하세요.

<OAuthV2 name="GenerateAuthorizationCode">
    <Operation>GenerateAuthorizationCode</Operation>
    <GenerateResponse enabled="true"/>
</OAuthV2>

반환

<GenerateResponse>가 사용 설정되면 정책은 승인 코드가 연결된 redirect_uri(콜백 URI) 위치로 ?code 쿼리 매개변수를 반환합니다. 이 쿼리 매개변수는 응답의 Location 헤더에 있는 URL을 포함하는 302 브라우저 리디렉션을 통해 전송됩니다. 예를 들면 ?code=123456입니다.

<GenerateResponse>false로 설정하면 정책이 응답을 반환하지 않습니다. 대신 다음의 흐름 변수 집합을 승인 코드와 관련된 데이터로 채웁니다.

oauthv2authcode.{policy-name}.code
oauthv2authcode.{policy-name}.scope
oauthv2authcode.{policy-name}.redirect_uri
oauthv2authcode.{policy-name}.client_id

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

oauthv2authcode.GenerateAuthorizationCode.code
oauthv2authcode.GenerateAuthorizationCode.scope
oauthv2authcode.GenerateAuthorizationCode.redirect_uri
oauthv2authcode.GenerateAuthorizationCode.client_id

액세스 토큰 갱신

갱신 토큰은 일반적으로 액세스 토큰이 만료되거나 무효화된 후에 액세스 토큰을 얻기 위해 사용하는 사용자 인증 정보입니다. 액세스 토큰을 받으면 갱신 토큰이 응답에 반환됩니다.

갱신 토큰을 사용하여 새 액세스 토큰을 요청하려면 다음 단계를 따르세요.

샘플 요청

다음 호출에서 기본 인증 헤더를 인코딩하는 방법은 '기본 인증 사용자 인증 정보 인코딩'을 참조하세요.

$ curl -X POST \
  -H "Content-type: application/x-www-form-urlencoded" \
  -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAyg5T1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ' \
  https://myorg-test.apigee.net/my_oauth_endpoint/refresh_accesstoken \
  -d 'grant_type=refresh_token&refresh_token=my-refresh-token'

필수 매개변수

  • grant_type - refresh_token 값으로 설정해야 합니다.
  • refresh_token - 갱신하려는 액세스 토큰과 연결된 갱신 토큰입니다.

기본적으로 정책은 위의 예시와 같이 요청 본문에 지정된 x-www-form-urlencoded 매개변수를 찾습니다. 이러한 입력에 대체 위치를 구성하려면 OAuthV2 정책에서 <GrantType><RefreshToken> 요소를 사용하면 됩니다. 자세한 내용은 OAuthV2 정책을 참조하세요.

선택적 매개변수

  • state - 응답과 함께 다시 전송되는 문자열입니다. 일반적으로 교차 사이트 요청 위조 공격을 방지하는 데 사용됩니다.
  • scope - 발급된 토큰을 사용할 수 있는 API 제품 목록을 필터링할 수 있습니다. 범위에 대한 자세한 내용은 OAuth2 범위 다루기을 참조하세요.

인증

  • client_id
  • client_secret

클라이언트 ID와 클라이언트 보안 비밀번호를 기본 인증 헤더(Base64 인코딩) 또는 양식 매개변수 client_idclient_secret로 전달해야 합니다. '기본 인증 사용자 인증 정보 인코딩'도 참조하세요.

액세스 토큰을 갱신할 때 사용자의 재인증은 하지 않습니다.

다음은 갱신 토큰을 사용하여 액세스 토큰을 생성하는 샘플 엔드포인트 구성입니다. 이는 RefreshAccessToken 정책을 실행합니다.

 ...
       <Flow name="generate-refresh-token">
            <Request>
                <Step>
                    <Name>RefreshAccessToken</Name>
                </Step>
            </Request>
            <Response/>
            <Condition>(proxy.pathsuffix MatchesPath "/refresh") and (request.verb = "POST")</Condition>
       </Flow>
...

샘플 정책

이는 refresh_token 부여 유형을 허용하도록 구성된 기본 RefreshAccessToken 정책입니다. 이 정책으로 구성할 수 있는 선택적 구성 요소에 대한 자세한 내용은 OAuthV2 정책을 참조하세요.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OAuthV2 name="RefreshAccessToken">
    <Operation>RefreshAccessToken</Operation>
    <GenerateResponse enabled="true"/>
    <ExpiresIn>1800000</ExpiresIn> <!-- 30 minutes -->
    <RefreshTokenExpiresIn>28800000</RefreshTokenExpiresIn> <!-- 8 hours -->
</OAuthV2>

반환

<GenerateResponse>를 사용 설정하면 정책에서 새 액세스 토큰이 포함된 JSON 응답을 반환합니다. refresh_token 권한 부여 유형을 사용하면 액세스 토큰과 새 갱신 토큰을 모두 발급할 수 있습니다. 예를 들면 다음과 같습니다.

{
    "issued_at": "1420301470489",
    "application_name": "ce1e94a2-9c3e-42fa-a2c6-1ee01815476b",
    "scope": "READ",
    "refresh_token_issued_at": "1420301470489",
    "status": "approved",
    "refresh_token_status": "approved",
    "api_product_list": "[PremiumWeatherAPI]",
    "expires_in": "1799", //--in seconds
    "developer.email": "tesla@weathersample.com",
    "token_type": "BearerToken",
    "refresh_token": "8fKDHLryAD9KFBsrpixlq3qPJnG2fdZ5",
    "client_id": "5jUAdGv9pBouF0wOH5keAVI35GBtx3dT",
    "access_token": "jmZ2Hqv3iNsABUtAAsfWR3QGNctw",
    "organization_name": "docs",
    "refresh_token_expires_in": "28799", //--in seconds
    "refresh_count": "2"
}

새로운 갱신 토큰이 발급된 후에는 원래 토큰이 더 이상 유효하지 않는다는 점을 알아두세요.

위 응답은 <GenerateResponse>가 true로 설정된 경우에 받게 됩니다. <GenerateResponse>가 false로 설정되면 정책이 응답을 반환하지 않습니다. 그 대신 다음과 같은 컨텍스트(흐름) 변수 집합을 액세스 토큰 부여와 관련된 데이터로 채웁니다.

oauthv2accesstoken.{policy-name}.access_token
oauthv2accesstoken.{policy-name}.expires_in   //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token
oauthv2accesstoken.{policy-name}.refresh_token_expires_in  //--in seconds
oauthv2accesstoken.{policy-name}.refresh_token_issued_at
oauthv2accesstoken.{policy-name}.refresh_token_status

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

oauthv2accesstoken.RefreshAccessToken.access_token
oauthv2accesstoken.RefreshAccessToken.expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token
oauthv2accesstoken.RefreshAccessToken.refresh_token_expires_in
oauthv2accesstoken.RefreshAccessToken.refresh_token_issued_at
oauthv2accesstoken.RefreshAccessToken.refresh_token_status

토큰 또는 인증 코드를 요청하기 위해 API를 호출하는 경우 OAuth 2.0 사양에서 권장하는 좋은 방법은 IETF RFC 2617에 설명된 대로 client_id 및 client_secret 값을 HTTP 기본 인증 헤더로 전달하는 것입니다. 이렇게 하려면 두 값을 구분하는 콜론으로 결합한 결과를 base64로 인코딩해야 합니다.

의사 코드는 다음과 같습니다.

result = Base64Encode(concat('ns4fQc14Zg4hKFCNaSzArVuwszX95X', ':', 'ZIjFyTsNgQNyxI'))

이 예시에서 ns4fQc14Zg4hKFCNaSzArVuwszX95X는 client_id이고 ZIjFyTsNgQNyxI는 클라이언트 보안 비밀번호입니다.

base64로 인코딩된 결과를 계산하는 데 사용하는 프로그래밍 언어에 관계없이 클라이언트 사용자 인증 정보가 주어지면 base64로 인코딩된 결과는 다음과 같습니다. bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==

그런 다음 다음과 같이 토큰을 요청할 수 있습니다.

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

-u 옵션을 사용하면 curl 유틸리티가 실제로 HTTP 기본 헤더를 만듭니다. 다음은 위의 예시와 동일합니다.

$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' \
  -u 'ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI' \
  -X POST 'https://docs-test.apigee.net/oauth/accesstoken' \
  -d 'grant_type=client_credentials'

다른 프로그래밍 환경에는 base64 인코딩 헤더를 자동으로 생성하는 유사한 단축키가 있을 수 있습니다.

데이터베이스에서 토큰 해싱

데이터베이스 보안 위반 시 OAuth 액세스 및 갱신 토큰을 보호하려면 Edge 조직에서 자동 토큰 해싱을 사용 설정하면 됩니다. 이 기능을 사용 설정하면 Edge는 지정된 알고리즘을 사용하여 새로 생성된 OAuth 액세스 및 갱신 토큰의 해시된 버전을 자동으로 만듭니다. (다음은 기존 토큰 일괄 해싱에 대한 정보입니다.) 해시되지 않은 토큰은 API 호출에서 사용되며 Edge에서 데이터베이스의 해시된 버전에 맞게 검증됩니다.

다음 조직 수준 속성은 OAuth 토큰 해싱을 제어합니다.

features.isOAuthTokenHashingEnabled = true
features.OAuthTokenHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

기존 해시된 토큰이 있으며 이를 만료될 때까지 보존하려면 해싱 알고리즘이 기존 알고리즘(예: 이전 Edge 기본값인 SHA1)과 일치하는 조직에서 다음 속성을 설정합니다. 토큰이 해시되지 않은 경우 PLAIN을 사용합니다.

features.isOAuthTokenFallbackHashingEnabled = true
features.OAuthTokenFallbackHashingAlgorithm = SHA1 | SHA256 | SHA384 | SHA512 | PLAIN

Edge 클라우드 고객인 경우 Apigee Edge 지원팀에 문의하여 조직에 이러한 속성을 설정하고 원하는 경우 기존 토큰을 일괄 해싱할 수 있습니다.

관련 주제