적용 대상: 개발자 | 기본 | 기본 v2 | 표준 | 표준 v2 | 프리미엄 | 프리미엄 v2
위임을 사용하면 웹 사이트에서 사용자 데이터를 소유하고 사용자 지정 유효성 검사를 수행할 수 있습니다. 위임을 사용하면 개발자 포털의 기본 제공 기능이 아니라 기존 웹 사이트를 사용하여 개발자 로그인/가입(관련 계정 관리 작업) 및 제품 구독을 처리할 수 있습니다.
개발자 로그인/가입 및 개발자 계정 관리 옵션을 기존 웹 사이트에 위임하려면 사이트에서 특별한 위임 엔드포인트를 만듭니다. 이 특수 위임은 API Management 개발자 포털에서 시작된 로그인/가입 및 관련 요청에 대한 진입점 역할을 합니다.
최종 워크플로는 다음과 같습니다.
- 개발자가 API Management 개발자 포털에서 로그인/가입 링크 또는 계정 관리 링크를 클릭합니다.
- 브라우저가 위임 엔드포인트로 리디렉션됩니다.
- 대신 위임 엔드포인트는 사용자를 로그인/가입 또는 계정 관리 UI로 리디렉션하거나 사용자에게 제공합니다.
- 작업이 완료되면 사용자가 떠난 위치의 API Management 개발자 포털로 다시 리디렉션됩니다.
Azure Portal에서 API Management 인스턴스로 이동합니다.
왼쪽 메뉴의 개발자 포털에서 위임을 선택합니다.
로그인 및 가입 위임 확인란을 클릭하여 사용하도록 설정합니다.
특수 위임 엔드포인트의 URL을 결정하고 위임 엔드포인트 URL 필드에 이 URL을 입력합니다.
위임 유효성 검사 키 필드에 다음을 입력합니다.
- 요청이 API Management에서 시작되는지 확인하기 위해 제공된 서명을 계산하는 데 사용하는 비밀을 입력합니다.
- API Management의 생성 단추를 클릭하여 임의 키를 생성합니다.
저장을 클릭합니다.
사이트에서 구현할 새 위임 엔드포인트를 만드는 권장 단계는 다음과 같습니다.
작업에 따라 다음 형식으로 요청을 받습니다.
http://www.yourwebsite.com/apimdelegation?operation={operation}&returnUrl={원본 페이지의 URL}&salt={string}&sig={string}
-또는-
http://www.yourwebsite.com/apimdelegation?operation={operation}&userId={계정의 사용자 ID}&salt={string}&sig={string}
쿼리 매개 변수:
매개 변수 설명 작업 위임 요청 유형을 식별합니다. 사용 가능한 작업: SignIn, SignUp, ChangePassword, ChangeProfile, CloseAccount, SignOut. returnUrl SignIn 또는 SignUp에서 사용자가 로그인 또는 가입 링크를 클릭하는 위치의 URL입니다. userId ChangePassword, ChangeProfile, CloseAccount 및 SignOut에서 관리하려는 계정의 사용자 ID salt 보안 해시를 계산하는 데 사용되는 특수 salt 문자열입니다. sig 자신의 계산된 해시와 비교하는 데 사용되는 계산된 보안 해시입니다. 요청이 Azure API Management에서 들어오는지 확인합니다(선택 사항이지만 보안을 위해 상당히 권장됨).
returnUrl(또는 UserId) 및 salt 쿼리 매개 변수에 따라 문자열의 HMAC-SHA512 해시를 컴퓨팅합니다. 예를 들어 예제 코드를 확인합니다.
SignIn 및 SignUp의 경우:
HMAC(salt + '\n' + returnUrl)ChangePassword, ChangeProfile, CloseAccount 및 SignOut의 경우:
HMAC(salt + '\n' + userId)위의 계산된 해시와 sig 쿼리 매개 변수 값을 비교합니다. 두 해시가 일치하면 다음 단계를 진행합니다. 일치하지 않으면 요청을 거부합니다.
로그인/가입 또는 계정 관리 작업에 대한 요청을 수신했는지 확인합니다.
사용자에게 로그인/가입 또는 계정 관리 UI를 제공합니다.
사용자 쪽에서 작업을 완료한 후 API Management에서 사용자를 관리합니다. 예를 들어 사용자가 가입하는 경우 API Management에서 해당 계정을 만듭니다.
- API Management REST API를 사용하여 사용자를 만듭니다.
- 사용자 ID를 사용자 저장소의 동일한 값 또는 쉽게 추적할 수 있는 새 ID로 설정합니다.
로그인 또는 가입 후 사용자가 성공적으로 인증되면 다음을 수행합니다.
API Management REST API를 통해 공유 액세스 토큰을 요청합니다.
위의 API 호출에서 받은 SSO URL에 returnUrl 쿼리 매개 변수를 추가합니다. 예시:
https://contoso.developer.azure-api.net/signin-sso?token=<URL-encoded token>&returnUrl=%2Freturn%2Furl사용자를 위에서 생성한 URL로 리디렉션합니다.
제품 구독 위임은 사용자 로그인/가입 위임과 비슷하게 작동합니다. 최종 워크플로는 다음과 같습니다.
- 개발자가 API Management 개발자 포털에서 제품을 선택하고 구독 단추를 클릭합니다.
- 브라우저가 위임 엔드포인트로 리디렉션됩니다.
- 위임 엔드포인트는 사용자가 디자인한 필수 제품 구독 단계를 수행합니다. 여기에는 다음이 포함될 수 있습니다.
- 청구 정보를 요청하기 위해 다른 페이지로 리디렉션.
- 추가 질문하기.
- 정보를 저장하고 사용자 작업이 필요하지 않음.
위임 페이지에서 제품 구독 위임을 클릭합니다.
사이트에서 구현할 새 위임 엔드포인트를 만드는 권장 단계는 다음과 같습니다.
작업에 따라 다음 형식으로 요청을 받습니다.
http://www.yourwebsite.com/apimdelegation?operation={operation}&productId={구독할 제품}&userId={요청을 수행하는 사용자}&salt={string}&sig={string}
-또는-
http://www.yourwebsite.com/apimdelegation?operation={operation}&subscriptionId={관리할 구독}&salt={string}&sig={string}
쿼리 매개 변수:
매개 변수 설명 작업 위임 요청 유형을 식별합니다. 유효한 제품 구독 요청 옵션은 다음과 같습니다. - Subscribe: 사용자가 제공된 ID를 사용하여 지정된 제품을 구독하도록 하는 요청입니다(아래 참조).
- Unsubscribe: 제품에서 사용자 구독을 취소하는 요청입니다.
productId Subscribe에서는 사용자가 구독을 요청한 제품 ID입니다. userId Subscribe에서는 요청하는 사용자의 ID입니다. subscriptionId Unsubscribe에서 제품 구독 ID입니다. salt 보안 해시를 계산하는 데 사용되는 특수 salt 문자열입니다. sig 자신의 계산된 해시와 비교하는 데 사용되는 계산된 보안 해시입니다. 요청이 Azure API Management에서 들어오는지 확인합니다(선택 사항이지만 보안을 위해 상당히 권장됨).
productId 및 userId(또는 subscriptionId) 및 salt 쿼리 매개 변수를 기준으로 하는 문자열의 HMAC-SHA512를 계산합니다.
Subscribe의 경우:
HMAC(salt + '\n' + productId + '\n' + userId)Unsubscribe의 경우:
HMAC(salt + '\n' + subscriptionId)위의 계산된 해시와 sig 쿼리 매개 변수 값을 비교합니다. 두 해시가 일치하면 다음 단계를 진행합니다. 일치하지 않으면 요청을 거부합니다.
operation에서 요청한 작업 유형(예: 청구, 추가 질문 등)에 따라 제품 구독을 처리합니다.
사용자 쪽에서 작업을 완료한 후 API Management에서 구독을 관리합니다. 예를 들어 구독에 대한 REST API를 호출하여 사용자를 API Management 제품에 구독시킵니다.
이러한 코드 샘플은 사용자 로그인 또는 가입을 위임할 때 returnUrl 쿼리 매개 변수의 해시를 생성하는 방법을 보여 줍니다.
returnUrl은 사용자가 로그인 또는 가입 링크를 클릭한 페이지의 URL입니다.
- Azure Portal의 위임 화면에서 설정한 위임 유효성 검사 키를 가져옵니다.
- HMAC를 만든 다음, 이를 통해 서명의 유효성을 검사하여 전달된 returnUrl의 유효성을 증명합니다.
약간의 수정으로 동일한 코드를 사용하여 제품 구독을 위임할 때 productId 및 userId 등의 다른 해시를 계산할 수 있습니다.
using System.Security.Cryptography;
string key = "delegation validation key";
string returnUrl = "returnUrl query parameter";
string salt = "salt query parameter";
string signature;
using (var encoder = new HMACSHA512(Convert.FromBase64String(key)))
{
signature = Convert.ToBase64String(encoder.ComputeHash(Encoding.UTF8.GetBytes(salt + "\n" + returnUrl)));
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter
}
var crypto = require('crypto');
var key = 'delegation validation key';
var returnUrl = 'returnUrl query parameter';
var salt = 'salt query parameter';
var hmac = crypto.createHmac('sha512', new Buffer(key, 'base64'));
var digest = hmac.update(salt + '\n' + returnUrl).digest();
// change to (salt + "\n" + productId + "\n" + userId) when delegating product subscription
// compare signature to sig query parameter
var signature = digest.toString('base64');
중요
위임 변경 내용을 적용하려면 개발자 포털을 다시 게시해야 합니다.
- 다음 문서를 통해 개발자 포털에 관해 자세히 알아보세요.
- Microsoft Entra ID 또는 Azure AD B2C를 사용하여 인증합니다.
- 개발자 포털에 대한 질문이 더 있나요? FAQ에서 답변 찾기.