현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보
클라이언트 사용자 인증 정보 부여 유형을 사용하면 앱이 자체 사용자 인증 정보(클라이언트 ID 및 클라이언트 보안 비밀번호)를 액세스 토큰을 생성하도록 설정된 Apigee Edge의 엔드포인트로 전송합니다. 사용자 인증 정보가 유효하면 Edge가 클라이언트 앱에 액세스 토큰을 반환합니다.
주제 정보
이 주제에서는 OAuth 2.0 클라이언트 사용자 인증 정보 부여 유형에 대한 일반적인 설명과 Apigee Edge에서 이 흐름을 구현하는 방법을 설명합니다.
사용 사례
일반적으로 이 부여 유형은 앱이 리소스 소유자일 때 사용됩니다. 예를 들어 앱이 최종 사용자가 소유한 데이터가 아닌, 작업을 수행하는 데 사용하는 데이터를 저장 및 검색하기 위해 백엔드 클라우드 기반 스토리지 서비스에 액세스해야 할 수 있습니다. 이 권한 부여 흐름은 클라이언트 앱과 승인 서버 간에서만 발생합니다. 최종 사용자는 이 지원 유형 흐름에 참여하지 않습니다.
역할
역할은 OAuth 흐름에 참여하는 '행위자'를 지정합니다. 클라이언트 사용자 인증 정보 역할의 간략한 개요를 통하여 Apigee Edge가 어디에 적합한지 보여줍니다. OAuth 2.0 역할에 대한 자세한 내용은 IETF OAuth 2.0 사양을 참조하세요.
- 클라이언트 앱 -- 사용자의 보호된 리소스에 대한 액세스가 필요한 앱입니다. 일반적으로 이 흐름을 사용하면 사용자의 노트북 또는 기기에서의 로컬이 아닌 서버에서 앱이 실행됩니다.
- Apigee Edge -- 이 흐름에서 Apigee Edge는 OAuth 승인 서버입니다. Apigee Edge의 역할은 액세스 토큰을 생성하고, 액세스 토큰의 유효성을 검사하며, 보호된 리소스에 대한 승인된 요청을 리소스 서버에 전달하는 것입니다.
- 리소스 서버 - 클라이언트 앱이 액세스하는 데 권한이 필요한 보호된 데이터를 저장하는 백엔드 서비스입니다. Apigee Edge에서 호스팅되는 API 프록시를 보호하는 경우 Apigee Edge는 리소스 서버도 됩니다.
코드 샘플
GitHub에서 완전히 작동하는 클라이언트 사용자 인증 정보 부여 유형의 샘플 구현을 확인할 수 있습니다. 더 많은 예시의 링크는 아래의 추가 리소스를 참조하세요.
흐름도
다음 흐름도는 Apigee Edge가 승인 서버로 사용되는 클라이언트 사용자 인증 정보 흐름을 보여줍니다. 일반적으로 Edge는 이 흐름의 리소스 서버이기도 합니다. 즉, API 프록시는 보호된 리소스입니다.
클라이언트 사용자 인증 정보 흐름의 단계
다음은 Apigee Edge가 승인 서버 역할을 하는 클라이언트 사용자 인증 정보 코드 부여 유형을 구현하는 데 필요한 단계의 요약입니다. 이 흐름을 사용하면 클라이언트 앱은 단순히 클라이언트 ID와 클라이언트 보안 비밀번호를 표시하며 이것이 유효한 경우 Apigee Edge는 액세스 토큰을 반환한다는 것을 기억하세요.
기본 요건: 클라이언트 ID와 클라이언트 보안 비밀번호 키를 가져오려면 클라이언트 앱을 Apigee Edge를 통해 등록해야 합니다. 자세한 내용은 클라이언트 앱 등록을 참조하세요.
1. 클라이언트가 액세스 토큰 요청
액세스 토큰을 받기 위해 클라이언트는 등록된 개발자 앱에서 가져온 클라이언트 ID 및 클라이언트 보안 비밀번호를 포함한 Edge로 API 호출을 POST합니다. 또한 grant_type=client_credentials 매개변수는 쿼리 매개변수로 전달되어야 합니다. 그러나 요청 헤더 또는 본문에서 이 매개변수를 허용하도록 OAuthV2 정책을 구성할 수 있습니다. 자세한 내용은 OAuthV2 정책을 참조하세요.
예를 들면 다음과 같습니다.
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials&client_id=ns4fQc14Zg4hKFCNaSzArVuwszX95X&client_secret=ZIjFyTsNgQNyxI'
참고: 위와 같이 client_id 및 client_secret 값을 쿼리 매개변수로 전달할 수 있지만 승인 헤더에 base64 URL 인코딩 문자열로 전달하는 것이 좋습니다. 이렇게 하려면 base64 인코딩 도구 또는 유틸리티를 사용하여 두 값과 이를 구분하는 콜론을 함께 인코딩해야 합니다. 예를 들면 다음과 같습니다. aBase64EncodeFunction(clientidvalue:clientsecret). 따라서 위 예시는 다음과 같이 인코딩됩니다.
result = aBase64EncodeFunction(ns4fQc14Zg4hKFCNaSzArVuwszX95X:ZIjFyTsNgQNyxI) // 두 값을 구분하는 콜론을 확인합니다.
위 문자열을 base64로 인코딩한 결과는 다음과 같습니다. bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg==
그런 다음과 같은 토큰 요청을 수행합니다.
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic bnM0ZlFjMTRaZzRoS0ZDTmFTekFyVnV3c3pYOTVYOlpJakZ5VHNOZ1FOeXhJOg=='
2. Edge가 사용자 인증 정보 유효성을 검사
API 호출은 /accesstoken 엔드포인트로 전송됩니다. 이 엔드포인트에는 앱의 사용자 인증 정보의 유효성을 검사하는 정책이 연결되어 있습니다. 즉, 정책은 제출된 키를 앱이 등록되었을 때 Apigee Edge가 생성한 키와 비교합니다. Edge의 OAuth 엔드포인트에 대한 자세한 내용은 OAuth 엔드포인트 및 정책 구성을 참조하세요.
3. Edge가 응답을 반환
사용자 인증 정보가 정상이면 Edge는 클라이언트에 액세스 토큰을 반환합니다. 그렇지 않으면 오류가 반환됩니다.
4. 클라이언트가 보호된 API를 호출
이제 유효한 액세스 토큰을 사용하여 클라이언트가 보호된 API를 호출할 수 있습니다. 이 시나리오에서는 Apigee Edge(프록시)로 요청이 전송되며, Edge는 대상 리소스 서버에 API 호출을 전달하기 전에 액세스 토큰의 유효성 검사를 담당합니다. 예시를 보려면 아래의 보호된 API 호출을 참조하세요.
흐름 및 정책 구성
Edge는 승인 서버로서 액세스 토큰 요청을 처리합니다. API 개발자는 토큰 요청을 처리하고 OAuthV2 정책을 추가 및 구성하기 위해 커스텀 흐름으로 프록시를 만들어야 합니다. 이 섹션에서는 이 엔드포인트를 구성하는 방법을 설명합니다.
커스텀 흐름 구성
API 프록시 흐름을 구성하는 방법을 가장 쉽게 보여주는 방법은 XML 흐름 정의를 표시하는 것입니다. 다음은 액세스 토큰 요청을 처리하도록 설계된 API 프록시 흐름의 예시입니다. 예를 들어 요청이 수신되고 경로 서픽스가 /accesstoken과 일치하면 GetAccessToken 정책이 트리거됩니다. 이와 같은 커스텀 흐름을 만드는 데 필요한 단계의 간략한 개요는 OAuth 엔드포인트 및 정책 구성을 참조하세요.
<Flows>
<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>GetAccessToken</Name></Step>
</Request>
</Flow>
</Flows>
다음과 같이 엔드포인트에 정책을 연결해야 합니다. 프록시 엔드포인트에 OAuthV2 정책을 추가하는 데 필요한 단계의 간략한 개요는 OAuth 엔드포인트 및 정책 구성을 참조하세요.
액세스 토큰 가져오기
이 정책은 /accesstoken 경로에 연결됩니다. 이는 GenerateAccessToken 작업이 지정된 OAuthV2 정책을 사용합니다.
<OAuthV2 name="GetAccessToken">
<Operation>GenerateAccessToken</Operation>
<ExpiresIn>3600000</ExpiresIn>
<SupportedGrantTypes>
<GrantType>client_credentials</GrantType>
</SupportedGrantTypes>
<GenerateResponse/>
</OAuthV2>
액세스 토큰을 가져오기 위한 API 호출은 POST이며, 형태가 base64로 인코딩된 client_id + 클라이언트 + 보안 비밀인 승인 헤더와 쿼리 매개변수 grant_type=client_credentials를 포함합니다. 또한 범위와 상태에 대한 선택적 매개변수를 포함할 수 있습니다. 예를 들면 다음과 같습니다.
$ curl -i -H 'Content-Type: application/x-www-form-urlencoded' -X POST 'https://docs-test.apigee.net/oauth/accesstoken' -d 'grant_type=client_credentials' -H 'Authorization: Basic c3FIOG9vSGV4VHo4QzAySVgT1JvNnJoZ3ExaVNyQWw6WjRsanRKZG5lQk9qUE1BVQ'
액세스 토큰 정책 확인 연결
OAuth 2.0 보안을 사용하여 API를 보호하려면 VerifyAccessToken 작업이 있는 OAuthV2 정책을 추가해야 합니다. 이 정책은 수신 요청에 유효한 액세스 토큰이 있는지 확인합니다. 토큰이 유효하다면 Edge가 요청을 처리합니다. 토큰이 유효하지 않다면 Edge가 오류를 반환합니다. 기본 단계를 보려면 액세스 토큰 확인을 참조하세요.
<OAuthV2 async="false" continueOnError="false" enabled="true" name="VerifyAccessToken">
<DisplayName>VerifyAccessToken</DisplayName>
<ExternalAuthorization>false</ExternalAuthorization>
<Operation>VerifyAccessToken</Operation>
<SupportedGrantTypes/>
<GenerateResponse enabled="true"/>
<Tokens/>
</OAuthV2>
OAuth 2.0 보안으로 보호된 API를 호출하려면 유효한 액세스 토큰을 제시해야 합니다. 올바른 패턴은 다음과 같이 승인 헤더에 토큰을 포함하는 것입니다. 액세스 토큰은 'Bearer 토큰'이라고도 합니다.
$ curl -H "Authorization: Bearer UAj2yiGAcMZGxfN2DhcUbl9v8WsR" \ http://myorg-test.apigee.net/v0/weather/forecastrss?w=12797282
액세스 토큰 보내기도 참조하세요.
- Apigee는 OAuth를 포함하는 API 보안 과정이 포함된, API 개발자를 위한 온라인 교육을 제공합니다.
- OAuthV2 정책 -- 승인 서버에 요청을 수행하는 방법과 OAuthV2 정책을 구성하는 방법을 보여주는 많은 예시가 있습니다.