승인 코드 부여 유형 구현

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

Apigee Edge 문서 보기

승인 코드는 가장 일반적으로 사용되는 OAuth 2.0 권한 유형 중 하나입니다. 승인 코드 흐름은 3-legged OAuth 구성입니다. 이 구성에서 사용자는 리소스 서버를 통해 직접 인증하고 클라이언트 앱에 사용자 이름/비밀번호를 공개하지 않고도 보호된 리소스에 액세스할 수 있도록 앱에서 권한을 부여합니다.

주제 정보

이 주제에서는 OAuth 2.0 승인 부여 유형에 대한 일반적인 설명과 개요를 제공하고, Apigee에서 이 흐름을 구현하는 방법을 설명합니다.

동영상

OAuth 2.0 승인 부여 유형을 사용하여 API를 보호하는 방법을 알아보려면 짧은 동영상을 시청하세요.

사용 사례

이 부여 유형은 API 제공업체와 신뢰할 수 있는 비즈니스 관계가 없는 타사 개발자가 작성한 앱을 대상으로 합니다. 예를 들어 공개 API 프로그램에 등록하는 개발자는 일반적으로 신뢰되어서는 안 됩니다. 이 부여 유형을 사용하면 리소스 서버의 사용자 인증 정보가 앱과 공유되지 않습니다.

코드 샘플

GitHub의 api-platform-samples 저장소에서 Apigee 승인 코드 부여 유형에 대한 실제 작동하는 완전한 샘플 구현 예시를 확인할 수 있습니다. api-platform-samples/sample-proxies 디렉터리에서 oauth-advanced 샘플을 참조하세요. 샘플에 대한 자세한 내용은 README 파일을 참조하세요.

흐름도

다음 흐름도는 Apigee가 승인 서버로 사용되는 승인 코드 OAuth 흐름을 보여줍니다.

승인 코드 OAuth 흐름.

승인 코드 흐름의 단계

다음은 승인 코드 부여 유형을 구현하는 데 필요한 단계의 요약입니다. 여기서 Apigee는 승인 서버 역할을 합니다. 이 흐름의 핵심은 클라이언트가 리소스 서버에서 사용자의 사용자 인증 정보를 볼 수 없다는 것입니다.

기본 요건: 클라이언트 ID와 클라이언트 보안 비밀번호 키를 가져오려면 클라이언트 앱을 Apigee를 사용하여 등록해야 합니다. 자세한 내용은 클라이언트 앱 등록을 참조하세요.

1. 사용자가 흐름 시작

리소스 서버에서 소셜 미디어 사이트의 연락처 목록과 같은 사용자의 보호된 리소스에 액세스해야 하는 경우 앱은 Apigee로 API 호출을 전송하여 클라이언트 ID의 유효성을 검증하고, 유효성이 검증되면 사용자의 브라우저를 사용자가 자격 증명을 입력할 로그인 페이지로 리디렉션합니다. API 호출에는 클라이언트 앱 등록 시 얻은 정보인 클라이언트 ID와 리디렉션 URI가 포함됩니다.

2. 사용자가 사용자 인증 정보 입력

이제 사용자에게 로그인 사용자 인증 정보를 입력하라는 로그인 페이지가 표시됩니다. 로그인이 성공하면 다음 단계로 이동합니다.

이메일 주소 및 비밀번호 필드가 있는 Apigee 로그인 페이지입니다.

3. 사용자가 동의

이 단계에서 사용자는 앱의 리소스에 액세스하는 데 동의합니다. 동의 양식에는 일반적으로 범위 선택이 포함되므로 사용자가 앱이 리소스 서버에서 수행할 수 있는 작업을 선택할 수 있습니다. 예를 들어 사용자는 읽기 전용 권한이나 앱이 리소스를 업데이트할 수 있는 권한을 부여할 수 있습니다.

샘플 앱이 허용 및 거부 버튼으로 주문하도록 요청하는 동의 페이지입니다.

4. 로그인 앱에서 Apigee에 요청 전송

로그인 및 동의에 성공하면 로그인 앱이 Apigee의 /authorizationcode 엔드포인트에 데이터를 게시합니다. 데이터에는 리디렉션 URI, 클라이언트 ID, 범위, 포함하려는 사용자별 정보, 로그인 성공 표시가 있습니다.

5. Apigee가 승인 코드 생성

Apigee가 로그인 앱의 /authorizationcode 엔드포인트에서 GET 요청을 받으면 두 가지 작업이 수행됩니다. 먼저 Apigee는 HTTP 상태 확인 또는 다른 방법을 통해 로그인이 성공했는지 확인합니다. 그런 다음 Apigee는 로그인 앱에서 전송된 리디렉션 URI가 앱이 Apigee에 등록되었을 때 지정된 리디렉션 URI와 일치하는지 확인합니다. 아무 문제가 없으면 Apigee는 승인 코드를 생성합니다. 예를 들면 다음과 같습니다.

http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

6. Apigee가 클라이언트에 승인 코드 다시 전송

Apigee는 클라이언트에 쿼리 매개변수로 연결된 인증 코드와 함께 302 리디렉션을 전송합니다.

7. 클라이언트가 승인 코드를 검색하고 Apigee에서 액세스 코드 요청

이제 유효한 승인 코드를 사용하여 클라이언트가 Apigee에서 액세스 토큰을 요청할 수 있습니다. 이 작업은 앱이 Apigee에 등록되었을 때 얻은 클라이언트 ID와 클라이언트 보안 비밀번호 키, 권한 유형, 범위를 게시하여 수행됩니다. Apigee는 클라이언트 ID와 보안 비밀 키를 포함하면 클라이언트 앱이 등록된 앱인지 확인할 수 있습니다. 예를 들면 다음과 같습니다.

$ curl https://{org_name}-test.apigee.net/my_oauth_proxy/accesstoken?code=Xyz123&grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpKNhGar6K&client_secret=hAr4GngA9vAyvI4'

8. 클라이언트가 액세스 토큰 수신

모든 것이 성공하면 Apigee는 클라이언트에 액세스 토큰을 반환합니다. 액세스 토큰은 만료되며 사용자가 앱이 리소스에 액세스하도록 동의할 때 사용자가 지정한 범위에 대해서만 유효합니다.

9. 클라이언트가 보호된 API를 호출

이제 유효한 액세스 코드를 사용하여 클라이언트가 보호된 API를 호출할 수 있습니다. 이 시나리오에서는 Apigee(프록시)로 요청이 전송되며 Apigee는 대상 리소스 서버에 API 호출을 전달하기 전에 액세스 토큰의 유효성을 검사합니다. 액세스 토큰은 승인 헤더로 전달됩니다. 예를 들면 다음과 같습니다.

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

흐름 및 정책 구성

승인 서버로서 Apigee는 액세스 토큰, 인증 코드, 새로고침 토큰, 로그인 페이지 리디렉션 등 다양한 OAuth 요청을 처리해야 합니다. 이러한 엔드포인트를 구성하는 두 가지 기본 단계가 있습니다.

  • 커스텀 흐름 만들기
  • OAuthV2 정책 추가 및 구성

커스텀 흐름 구성

일반적으로 이 부여 유형 흐름을 구성하여 흐름의 각 단계 또는 구간을 Apigee 프록시의 흐름에서 정의할 수 있습니다. 각 흐름에는 엔드포인트와 승인 코드 또는 액세스 토큰 생성과 같은 필요한 OAuth 관련 작업을 수행하는 정책이 있습니다. 예를 들어 아래 XML에 표시된 대로 /oauth/authorizationcode 엔드포인트에는 GenerateAuthorizationCode 작업이 지정된 OAuthV2 정책인 GenerateAuthCode라는 관련 정책이 있습니다.

흐름 구성을 가장 쉽게 보여주는 방법은 XML 예시를 사용하는 것입니다. 각 흐름에 대한 자세한 내용은 인라인 주석을 참조하세요. 이는 예시이며 흐름과 경로의 이름은 원하는 대로 구성할 수 있습니다. 이와 같은 커스텀 흐름을 만드는 데 필요한 단계의 간략한 개요는 OAuth 엔드포인트 및 정책 구성을 참조하세요.

GitHub의 구현 예시도 참조하면 도움이 됩니다. 

<Flows>
  <Flow name="RedirectToLoginApp">
         <!-- 
         Publish this URI to developers to use for their 'login' link 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorize"</Condition>
    <Request>
        <Step><Name>RedirectToLoginPage</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAuthCode">
         <!-- 
         Call this URL from your Login app after you authenticate the user.
         The policy will automatically return the auth code in the response to the 
         redirect_uri registered by the calling app 
         -->
    <Condition>proxy.pathsuffix == "/oauth/authorizationcode"</Condition>
    <Request>
        <Step><Name>GenerateAuthCode</Name></Step>
    </Request>
  </Flow>
  <Flow name="GetAccessToken">
         <!-- This policy flow is triggered when the URI path suffix
         matches /oauth/accesstoken. Publish this URL to app developers 
         to use when obtaining an access token using an auth code   
         -->
    <Condition>proxy.pathsuffix == "/oauth/accesstoken"</Condition>
    <Request>
        <Step><Name>GenerateAccessToken</Name></Step>
    </Request>
  </Flow>
</Flows>

정책을 사용하여 흐름 구성

각 엔드포인트에는 연결된 정책이 있습니다. 정책의 예시를 살펴보겠습니다. OAuthV2 정책을 프록시 엔드포인트에 추가하는 데 필요한 단계를 간략하게 알아보려면 OAuth 엔드포인트 및 정책 구성을 참조하세요.

로그인 리디렉션

/oauth/authorize 경로입니다. 연결된 정책은 최종 사용자가 사용자 이름과 비밀번호를 클라이언트 앱에 공개하지 않고도 클라이언트 앱이 사용자의 보호된 리소스에 액세스할 수 있도록 안전하게 인증 및 승인하는 로그인 앱으로 사용자를 리디렉션하는 역할을 합니다. 서비스 콜아웃 정책, 자바스크립트 또는 기타 방법으로 이 작업을 수행할 수 있습니다.

요청을 수행하기 위한 API 호출은 GET이며 쿼리 매개변수 client_id, response_type, redirect_uri, scope, state가 필요합니다.

$ curl http://myorg-test.apigee.net/oauth/authorize?client_id={consumer_key}&response_type=code&redirect_uri={redirect_uri}&scope=scope1%20scope2&state={some_string}

인증 코드 받기

/oauth/authorizationcode 경로입니다. 이는 GenerateAuthorizationCode 작업이 지정된 OAuthV2 정책을 사용합니다.

<OAuthV2 async="false" continueOnError="false" enabled="true" name="GetAuthCode">
    <DisplayName>GetAuthCode</DisplayName>
    <Operation>GenerateAuthorizationCode</Operation>
    <ExpiresIn>600000</ExpiresIn>
    <GenerateResponse/>
</OAuthV2>

승인 코드를 얻기 위한 API 호출은 GET이며 다음 예시와 같이 쿼리 매개변수 client_id, response_type과 경우에 따라 scope, state가 필요합니다.

$curl http://myorg-test.apigee.net/oauth/authorizationcode?client_id={consumer_key}&response_type=code&scope=scope1%20scope2&state={some_string}

액세스 토큰 가져오기

이 정책은 /oauth/accesstoken 경로에 연결됩니다. GenerateAccessCode 작업이 지정된 OAuthV2 정책을 사용합니다. 이 경우 쿼리 매개변수로 grant_type 매개변수가 필요합니다.

<OAuthV2 name="GetAccessToken">
    <Operation>GenerateAccessToken</Operation>
    <ExpiresIn>360000000</ExpiresIn>
    <SupportedGrantTypes>
        <GrantType>authorization_code</GrantType>
    </SupportedGrantTypes>
    <GrantType>request.queryparam.grant_type</GrantType>
    <GenerateResponse/>
</OAuthV2>

액세스 코드를 얻기 위한 API 호출은 POST이며 client_id, client_secret, grant_type=authorization_code와 경우에 따라 scope를 포함해야 합니다. 예를 들면 다음과 같습니다.

$ curl https://{org_name}-test.apigee.net/oauth/accesstoken?grant_type=authorization_code -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'

이는 기본 요약 정보입니다. 프로덕션 예시에는 URL 빌드, 변환 작업, 기타 태스크 수행을 위한 다른 많은 정책이 포함되어 있습니다. 완전하게 작업 프로젝트는 GitHub 샘플을 참조하세요.

액세스 토큰 정책 확인 연결

보호된 리소스에 대한 요청이 들어올 때마다 실행되도록 보호된 API에 액세스하는 흐름의 시작 부분에 VerifyAccessToken 정책(VerifyAccessToken 작업이 지정된 OAuthV2 정책)을 연결합니다. Apigee에서는 각 요청에 유효한 액세스 토큰이 포함되어 있는지 확인합니다. 그렇지 않으면 오류가 반환됩니다. 기본 단계를 보려면 액세스 토큰 확인을 참조하세요. 

<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
    <DisplayName>VerifyAccessToken</DisplayName>
    <ExternalAuthorization>false</ExternalAuthorization>
    <Operation>VerifyAccessToken</Operation>
    <SupportedGrantTypes/>
    <GenerateResponse enabled="true"/>
    <Tokens/>
</OAuthV2>

보호된 API 호출

OAuth 2.0 보안으로 보호된 API를 호출하려면 유효한 액세스 토큰을 제시해야 합니다. 올바른 패턴은 다음과 같이 승인 헤더에 토큰을 포함하는 것입니다. 액세스 토큰은 Bearer 토큰이라고도 합니다. 

$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \
  http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282

액세스 토큰 보내기도 참조하세요.