현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보
OAuth는 API에 대한 최고의 승인 프로토콜로 부상했습니다. 이 주제에서 자세히 다루는 OAuth 버전은 OAuth 2.0 사양에 정의되어 있습니다.
OAuth는 앱 최종 사용자가 자신을 대신하여 작업을 수행할 앱을 승인할 수 있게 해주는 프로토콜입니다. 이를 위해 앱은 API 제공업체로부터 액세스 토큰을 가져옵니다. API 제공업체는 앱 최종 사용자의 사용자 인증 정보를 인증하고 사용자가 앱을 승인했는지 확인한 후 앱에 액세스 토큰을 발급합니다. 앱이 보호된 API를 사용할 때 Apigee Edge는 액세스 토큰을 검사하여 액세스 토큰이 유효하고 만료되지 않았는지 확인합니다. API 제공업체는 앱이 액세스 토큰을 가져올 수 있도록 하는 엔드포인트를 노출해야 합니다.
Apigee Edge를 사용하면 코드를 작성하지 않고도 정책을 사용하여 OAuth를 구성하고 시행할 수 있으므로 OAuth를 쉽게 사용할 수 있습니다. 이 주제에서는 API를 보호하는 방법과 액세스 토큰을 얻는 방법, 이러한 액세스 토큰을 사용하여 보호 대상 API에 액세스하는 방법을 알아봅니다.
조직의 기본 OAuth 구성
편의를 위해 Apigee Edge의 모든 조직에는 클라이언트 사용자 인증 정보 부여 유형을 구현하는 OAuth 2.0 엔드포인트 집합이 사전 구성되어 있습니다. 클라이언트 사용자 인증 정보 부여 유형은 앱 사용자 인증 정보를 얻는 대가로 액세스 토큰을 발급하는 절차를 정의합니다. 이러한 앱 사용자 인증 정보는 Apigee Edge에서 조직에 등록된 각 앱에 발급하는 고객 키와 비밀번호 쌍입니다. '클라이언트 사용자 인증 정보'는 고객 키와 보안 비밀의 쌍 자체를 의미합니다.
Edge 개발자 서비스를 사용하여 앱에 사용자 인증 정보를 발급하는 방법에 관한 자세한 내용은 앱 등록 및 키 관리를 참고하세요.
따라서 API 보안 스키마를 API 키 검증에서 OAuth 클라이언트 사용자 인증 정보로 '단계별'하는 것은 비교적 간단합니다. 두 스키마 모두 동일한 고객 키와 비밀번호를 사용하여 클라이언트 앱을 검증합니다. 차이점은 클라이언트 사용자 인증 정보가 추가 제어 레이어를 제공한다는 점입니다. 앱의 고객 키를 취소할 필요 없이 필요할 때 액세스 토큰을 쉽게 취소할 수 있기 때문입니다. 기본 OAuth 엔드포인트를 사용하려면 조직의 앱에 대해 생성된 고객 키와 보안 비밀을 사용하여 토큰 엔드포인트에서 액세스 토큰을 검색하면 됩니다. (이미 고객 키와 보안 비밀이 있는 앱에도 클라이언트 사용자 인증 정보를 사용 설정할 수 있습니다.)
클라이언트 사용자 인증 정보 부여의 전체 사양은 OAuth 2.0 사양에서 확인할 수 있습니다.
정책으로 API 보호
액세스 토큰을 사용하려면 먼저 런타임 시 OAuth 액세스 토큰을 검증하도록 API를 구성해야 합니다. 이를 위해API 프록시를 구성하여 액세스 토큰 validate을 수행합니다. 즉, 앱이 API 중 하나를 사용하도록 요청할 때마다 API 요청과 함께 유효한 액세스 토큰을 제공해야 합니다. Apigee Edge는 표시된 액세스 토큰의 생성, 저장, 검증과 관련된 복잡성을 처리합니다.
새 API 프록시를 만들 때 API에 OAuth 확인을 쉽게 추가할 수 있습니다. 새 API 프록시를 만들 때 기능을 추가할 수 있습니다. 아래와 같이 OAuth v2.0 액세스 토큰으로 보안 설정 옆에 있는 라디오 버튼을 선택하여 OAuth 2.0 액세스 토큰 인증을 추가할 수 있습니다. 이 옵션을 선택하면 새로 만든 API 프록시에 액세스 토큰 확인용 정책과 확인 후 액세스 토큰을 삭제하는 정책 두 개가 연결됩니다.
또한 OAuth v2.0 액세스 토큰으로 보안 설정 옵션을 선택하면 API 제품 게시 체크박스를 선택할 수 있게 되고 자동으로 선택됩니다. 새 API 프록시를 빌드할 때 제품을 자동으로 생성하려면 이 옵션을 선택합니다. 자동 생성된 제품이 새 API 프록시에 연결된 상태로 생성됩니다. 이 새 API를 연결할 기존 제품이 있는 경우 불필요한 제품을 만들지 않도록 이 체크박스를 선택 해제하세요. 제품에 대한 자세한 내용은 API 제품이란 무엇인가요?를 참조하세요.
이미 존재하는 API 프록시에 액세스 토큰 확인을 사용 설정해야 하는 경우 보호하려는 API에 OAuthV2 유형의 정책을 연결하기만 하면 됩니다. OAuthV2 정책은 작업을 지정하여 작동합니다. 액세스 토큰을 검증하려면 VerifyAccessToken이라는 작업을 지정합니다. (OAuthV2 정책 유형에서 지원되는 다른 작업 유형은 GenerateAccessToken 및 GenerateRefreshToken입니다. 이러한 작업은 OAuth 엔드포인트를 설정할 때 배우게 됩니다.)
OAuthV2 유형의 VerifyOAuthTokens 정책
액세스 토큰의 유효성을 검사하는 정책의 예는 다음과 같습니다. 설정은 아래 표에 설명되어 있습니다.
<OAuthV2 name="VerifyOAuthTokens"> <Operation>VerifyAccessToken</Operation> </OAuthV2>
정책 설정
| 이름 | 설명 | 기본 계정 | 필수 여부 |
|---|---|---|---|
OAuthV2 |
정책 유형 | ||
name |
API 프록시 엔드포인트 구성에서 참조되는 정책의 이름입니다. | N/A | 지원됨 |
Operation |
OAuthV2 정책에 따라 실행되는 작업입니다. VerifyAccessToken을 지정하면 액세스 토큰 요청을 확인하고, 액세스 토큰이 유효하고 만료되지 않았으며 요청된 API 리소스(URI)를 사용하도록 승인되었는지 확인하는 정책을 구성할 수 있습니다. (이를 확인하기 위해 정책에서는 앱에서 사용하도록 승인된 API 제품을 읽습니다.) | N/A | 지원됨 |
관리 UI에서 이 정책을 만들려면 API > API 프록시로 이동합니다.
API 프록시 목록에서 weatherapi를 선택합니다.
weatherapi의 개요에서 개발 뷰를 선택합니다.
드롭다운 메뉴에서 새 정책 > OAuth v2.0을 선택합니다.
OAuth v2.0 정책을 선택하면 새 정책 구성 메뉴가 표시됩니다.
정책에 설명이 포함된 이름을 지정하고 Attach Policy(정책 연결), Flow PreFlow(흐름 사전 흐름), Request(요청)를 정책 첨부파일 설정으로 선택합니다.
추가를 선택하면 정책이 생성되고 weatherapi의 요청 PreFlow에 연결됩니다.
정책을 추가하면 Designer 창에 아래의 요청 PreFlow 구성이 표시됩니다.
텍스트 편집기 또는 IDE에서 로컬로 작업하는 경우 보호하려는 API 프록시의 요청 PreFlow에 정책을 연결합니다.
<PreFlow>
<Request>
<Step><Name>VerifyOAuthTokens</Name></Step>
</Request>
</PreFlow>
요청 PreFlow에 정책을 연결하면 모든 요청 메시지에 정책이 항상 적용됩니다.
이제 OAuth 2.0 클라이언트 사용자 인증 정보로 API를 보호했습니다. 다음 단계에서는 액세스 토큰을 가져오고 이를 사용하여 보안 API에 액세스하는 방법을 알아봅니다.
액세스 토큰을 사용하여 보호되는 리소스에 액세스
이제 weatherapi가 OAuth 2.0으로 보호되었으므로, 앱에서 API를 사용할 액세스 토큰을 제시해야 합니다. 보호되는 리소스에 액세스하기 위해 앱은 다음과 같이 요청에 액세스 토큰을 'Authorization' HTTP 헤더로 제공합니다.
$ curl -H "Authorization: Bearer ylSkZIjbdWybfs4fUQe9BqP0LH5Z" http://{org_name}-test.apigee.net/weather/forecastrss?w=12797282
API에 OAuthV2 정책이 연결되어 있으므로 Apigee Edge는 제공된 액세스 토큰이 유효한지 확인한 후 API에 대한 액세스 권한을 부여하여 요청을 보낸 앱에 날씨 보고를 반환합니다.
그런데 앱은 어떻게 액세스 토큰을 얻나요? 다음 섹션에서 이에 대해 다루겠습니다.
클라이언트 사용자 인증 정보를 액세스 토큰으로 교환하는 방법
앱은 고객 키/보안 비밀 쌍을 토큰 엔드포인트에 제시하여 액세스 토큰을 얻습니다. 토큰 엔드포인트는 oauth라는 API 프록시에서 구성됩니다. 따라서 앱은 oauth API 프록시에서 노출된 API를 호출하여 액세스 토큰을 가져와야 합니다. 앱이 액세스 토큰을 갖게 되면 액세스 토큰이 만료되거나 액세스 토큰이 취소될 때까지 weatherapi를 반복적으로 호출할 수 있습니다.
이제 스스로를 앱 개발자라고 생각하도록 방향을 바꿔야 합니다. weatherapi를 호출하려면, 앱의 액세스 토큰을 가져와야 합니다. 가장 먼저 해야 할 일은 고객 키와 비밀번호의 쌍 (API 키 또는 앱 키라고도 함)을 가져오는 것입니다.
Apigee Edge에 조직의 앱을 등록하여 고객 키와 비밀번호를 가져올 수 있습니다.
Apigee Edge 관리 UI에서 조직의 모든 앱을 볼 수 있습니다.
조직에 등록된 앱 목록이 표시됩니다.
앱이 표시되지 않으면 앱 등록 및 API 키 관리라는 주제에서 앱을 등록하는 방법을 알아보세요.
목록에서 앱을 선택하여 세부 프로필을 확인합니다.
선택한 앱의 세부정보 뷰에서 고객 키 및 고객 비밀번호 필드를 확인합니다. 이 두 값이 OAuth 액세스 토큰을 얻는 데 사용할 클라이언트 사용자 인증 정보입니다.
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps \
-u myname:mypass
이 호출은 앱 ID별로 앱 목록을 반환합니다.
[ "da496fae-2a04-4a5c-b2d0-709278a6f9db", "50e3e831-175b-4a05-8fb6-05a54701af6e" ]
앱 ID에 대해 간단한 GET 호출을 수행하여 앱 프로필을 검색할 수 있습니다.
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/{app_id} \
-u myname:mypass
예를 들면 다음과 같습니다.
$ curl https://api.enterprise.apigee.com/v1/o/{org_name}/apps/da496fae-2a04-4a5c-b2d0-709278a6f9db \
-u myname:mypass
API 호출은 지정한 앱의 프로필을 반환합니다. 예를 들어 weatherapp의 앱 프로필에는 다음과 같은 JSON 표현이 있습니다.
{
"accessType" : "read",
"apiProducts" : [ ],
"appFamily" : "default",
"appId" : "da496fae-2a04-4a5c-b2d0-709278a6f9db",
"attributes" : [ ],
"callbackUrl" : "http://weatherapp.com",
"createdAt" : 1380290158713,
"createdBy" : "noreply_admin@apigee.com",
"credentials" : [ {
"apiProducts" : [ {
"apiproduct" : "PremiumWeatherAPI",
"status" : "approved"
} ],
"attributes" : [ ],
"consumerKey" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"consumerSecret" : "hAr4Gn0gA9vAyvI4",
"expiresAt" : -1,
"issuedAt" : 1380290161417,
"scopes" : [ ],
"status" : "approved"
} ],
"developerId" : "5w95xGkpnjzJDBT4",
"lastModifiedAt" : 1380290158713,
"lastModifiedBy" : "noreply_admin@apigee.com",
"name" : "weatherapp",
"scopes" : [ ],
"status" : "approved"
}
consumerKey 및 consumerSecret의 값을 확인합니다. 아래와 같이
이 사용자 인증 정보를 HTTP 요청에서 기본 인증 사용자 인증 정보로 제시하여
액세스 토큰을 얻습니다. 권한 부여 유형은 요청에 쿼리 매개변수로 표시됩니다.
Apigee Edge에 적용되는 조직 이름이 반영되도록 {org_name} 변수의 값을 변경해야 합니다.
액세스 토큰 가져오기 요청 만들기
다음 요청에서 client_id를 consumerKey 값으로 대체합니다. 연결된 consumerSecret의 값을 client_secret로 대체합니다.
$ curl https://{org_name}-test.apigee.net/oauth/client_credential/accesstoken?grant_type=client_credentials -X POST -d 'client_id=bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K&client_secret=hAr4Gn0gA9vAyvI4'
API 서비스는 고객 키와 보안 비밀을 확인한 다음 이 앱의 액세스 토큰이 포함된 응답을 생성합니다.
{
"issued_at" : "1380892555397",
"application_name" : "957aa73f-25c2-4ead-8021-adc01f0d2c6b",
"scope" : "",
"status" : "approved",
"api_product_list" : "[oauth-test]",
"expires_in" : "3599",
"developer.email" : "tesla@weathersample.com",
"organization_id" : "0",
"client_id" : "bBGAQrXgivA9lKu7NMPyoYpVKNhGar6K",
"access_token" : "ylSkZIjbdWybfs4fUQe9BqP0LH5Z",
"organization_name" : "rqa",
"refresh_token_expires_in" : "0",
"refresh_count" : "0"
}
위 응답의 access_token 값을 확인합니다. 앱이 보호된 리소스에 대한 런타임 액세스를 얻기 위해 사용하는 액세스 토큰입니다. 이 앱의 액세스 토큰은 ylSkZIjbdWybfs4fUQe9BqP0LH5Z입니다.
이제 보호된 API에 액세스하는 데 사용할 수 있는 유효한 액세스 토큰인 ylSkZIjbdWybfs4fUQe9BqP0LH5Z가 생겼습니다.
기본 OAuth 구성 사용하기
Apigee Edge의 각 조직 (무료 체험판 조직 포함)은 OAuth 토큰 엔드포인트로 프로비저닝됩니다. 엔드포인트는 oauth라는 API 프록시의 정책으로 사전 구성됩니다. Apigee Edge에서 계정을 만드는 즉시 토큰 엔드포인트를 사용할 수 있습니다.
기본 OAuth 엔드포인트는 다음 엔드포인트 URI를 노출합니다.
/oauth/client_credential/accesstoken
액세스 토큰을 받아야 하는 개발자에게 이 URI를 게시합니다. 앱 개발자는 이 엔드포인트를 호출할 수 있도록 앱을 구성하여 소비자 키/비밀번호 조합을 표시하여 액세스 토큰을 얻습니다.
기본 클라이언트 사용자 인증 정보 토큰 엔드포인트는 다음 URL에서 네트워크를 통해 노출됩니다.
https://{org_name}-{env_name}.apigee.net/oauth/client_credential/accesstoken
예를 들어 조직 이름이 'apimaker'인 경우 URL은 다음과 같습니다.
https://apimakers-test.apigee.net/oauth/client_credential/accesstoken
이 URL은 개발자가 액세스 토큰을 받기 위해 호출하는 URL입니다.
3-legged OAuth 구성
Three-legged OAuth 구성 (승인 코드, 암시적 및 비밀번호 부여 유형)에서는 API 제공업체가 앱 최종 사용자를 인증해야 합니다. 조직마다 서로 다른 방식으로 사용자를 인증하므로 OAuth를 사용자 저장소와 통합하려면 몇 가지 정책 맞춤설정이나 코드가 필요합니다. 예를 들어 모든 사용자가 Active Directory, LDAP 또는 다른 사용자 저장소에 저장되어 있을 수 있습니다. 3-legged OAuth를 사용하려면 이 사용자 저장소에 대한 검사를 전체 OAuth 흐름에 통합해야 합니다.
OAuth 1.0a
OAuth 1.0a 정책에 대한 자세한 내용은 OAuth v1.0a 정책을 참고하세요.
도움말 보기
도움이 필요하면 Apigee 고객 지원을 참조하세요.