Azure Active Directory B2C 사용자 지정 정책에서 RESTful 기술 프로필 정의

  • 아티클

참고 항목

Azure Active Directory B2C에서 사용자 지정 정책은 주로 복잡한 시나리오를 해결하기 위해 설계되었습니다. 대부분의 시나리오에서 기본 제공 사용자 흐름을 사용하는 것이 좋습니다. 아직 수행하지 않았다면 Active Directory B2C에서 사용자 지정 정책 시작하기에서 사용자 지정 정책 스타터 팩에 대해 알아봅니다.

Azure AD B2C(Azure Active Directory B2C)는 사용자 고유의 RESTful 서비스 통합을 지원합니다. Azure AD B2C는 입력 클레임 컬렉션의 RESTful 서비스에 데이터를 보내고 출력 클레임 컬렉션에서 데이터를 다시 받습니다. 자세한 내용은 Azure AD B2C 사용자 지정 정책에서 REST API 클레임 교환 통합을 참조하세요.

프로토콜

Protocol 요소의 Name 특성을 .로 설정Proprietary해야 합니다. 처리기 특성은 Azure AD B2CWeb.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null에서 사용되는 프로토콜 처리기 어셈블리의 정규화된 이름을 포함해야 합니다.

다음 예제에서는 RESTful 기술 프로필을 보여 줍니다.

<TechnicalProfile Id="REST-UserMembershipValidator">
  <DisplayName>Validate user input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...

입력 클레임

InputClaims 요소에는 REST API로 보낼 클레임 목록이 포함되어 있습니다. 클레임 이름을 REST API에 정의된 이름에 매핑할 수도 있습니다. 다음 예제에서는 정책과 REST API 간의 매핑을 보여 줍니다. givenName 클레임은 rest API에 firstName으로 전송되고 성은 lastName으로 전송됩니다. 전자 메일 클레임이 있는 그대로 설정됩니다.

<InputClaims>
  <InputClaim ClaimTypeReferenceId="email" />
  <InputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="firstName" />
  <InputClaim ClaimTypeReferenceId="surname" PartnerClaimType="lastName" />
</InputClaims>

InputClaimsTransformations 요소에는 REST API로 보내기 전에 입력 클레임을 수정하거나 새 클레임을 생성하는 데 사용되는 InputClaimsTransformation 요소의 컬렉션이 포함될 수 있습니다.

JSON 페이로드 보내기

REST API 기술 프로필을 사용하면 복잡한 JSON 페이로드를 엔드포인트로 보낼 수 있습니다.

복잡한 JSON 페이로드를 보내려면 다음을 수행합니다.

  1. GenerateJson 클레임 변환을 사용하여 JSON 페이로드를 빌드합니다.
  2. REST API 기술 프로필에서:
    1. GenerateJson 클레임 변환에 대한 참조를 사용하여 입력 클레임 변환을 추가합니다.
    2. 메타데이터 옵션을 다음으로 SendClaimsIn 설정 body
    3. ClaimUsedForRequestPayload 메타데이터 옵션을 JSON 페이로드가 포함된 클레임 이름으로 설정합니다.
    4. 입력 클레임에서 JSON 페이로드를 포함하는 입력 클레임에 대한 참조를 추가합니다.

다음 예제 TechnicalProfile에서는 타사 이메일 서비스(이 경우 SendGrid)를 사용하여 확인 이메일을 전송합니다.

<TechnicalProfile Id="SendGrid">
  <DisplayName>Use SendGrid's email API to send the code to the user</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://api.sendgrid.com/v3/mail/send</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="ClaimUsedForRequestPayload">sendGridReqBody</Item>
    <Item Key="DefaultUserMessageIfRequestFailed">Cannot process your request right now, please try again later.</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_SendGridApiKey" />
  </CryptographicKeys>
  <InputClaimsTransformations>
    <InputClaimsTransformation ReferenceId="GenerateSendGridRequestBody" />
  </InputClaimsTransformations>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="sendGridReqBody" />
  </InputClaims>
</TechnicalProfile>

출력 클레임

OutputClaims 요소는 REST API에서 반환된 클레임 목록을 포함합니다. 정책에 정의된 클레임 이름을 REST API에서 정의된 이름에 매핑해야 할 수도 있습니다. 특성을 설정하는 DefaultValue 한 REST API에서 반환되지 않는 클레임을 포함할 수도 있습니다.

OutputClaimsTransformations 요소에는 출력 클레임을 수정하거나 새 클레임을 생성하는 데 사용되는 OutputClaimsTransformation 요소의 컬렉션이 포함될 수 있습니다.

다음 예제에서는 REST API에서 반환된 클레임을 보여 줍니다.

  • loyaltyNumber 클레임 이름에 매핑되는 MembershipId 클레임입니다.

또한 기술 프로필은 ID 공급자가 반환하지 않는 클레임도 반환합니다.

  • 기본값이 .로 설정된 trueloyaltyNumberIsNew 클레임입니다.
<OutputClaims>
  <OutputClaim ClaimTypeReferenceId="loyaltyNumber" PartnerClaimType="MembershipId" />
  <OutputClaim ClaimTypeReferenceId="loyaltyNumberIsNew" DefaultValue="true" />
</OutputClaims>

메타데이터

Attribute Required 설명
ServiceUrl 예 REST API 엔드포인트의 URL입니다.
AuthenticationType 예 RESTful 클레임 공급자가 수행하는 인증 유형입니다. 가능한 값은 None, Basic, Bearer, ClientCertificate 또는 ApiKeyHeader입니다.
  • 이 값은 None REST API가 익명임을 나타냅니다.
  • 이 값은 Basic REST API가 HTTP 기본 인증으로 보호됨을 나타냅니다. Azure AD B2C를 포함하여 확인된 사용자만 API에 액세스할 수 있습니다.
  • (권장) 값은 ClientCertificate REST API가 클라이언트 인증서 인증을 사용하여 액세스를 제한한다는 것을 나타냅니다. Azure AD B2C와 같은 적절한 인증서가 있는 서비스만 API에 액세스할 수 있습니다.
  • 이 값은 Bearer REST API가 클라이언트 OAuth2 전달자 토큰을 사용하여 액세스를 제한한다는 것을 나타냅니다.
  • 값은 ApiKeyHeader REST API가 x-functions-key와 같은 API 키 HTTP 헤더로 보호됨을 나타냅니다.
AllowInsecureAuthInProduction 아니요 프로덕션 환경에서 설정할 none 수 있는지 여부를 AuthenticationType 나타냅니다(DeploymentModeTrustFrameworkPolicy의 설정 Production여부). 가능한 값: true 또는 false(기본값).
SendClaimsIn 아니요 입력 클레임이 RESTful 클레임 공급자에게 전송되는 방법을 지정합니다. 가능한 값은 Body(기본값), Form, Header, Url 또는 QueryString입니다.
값은 Body 요청 본문에서 JSON 형식으로 전송되는 입력 클레임입니다.
Form 값은 앰퍼샌드 '&'로 구분된 키 값 형식의 요청 본문에 전송되는 입력 클레임입니다.
값은 Header 요청 헤더에 전송되는 입력 클레임입니다.
값은 Url URL에서 전송되는 입력 클레임입니다. 예를 들면 다음과 같습니다 https://api.example.com/{claim1}/{claim2}?{claim3}={claim4}. URL의 호스트 이름 부분에는 클레임이 포함될 수 없습니다.
값은 QueryString 요청 쿼리 문자열에서 전송되는 입력 클레임입니다.
각각에 의해 호출되는 HTTP 동사는 다음과 같습니다.
  • Body:올리기
  • Form:올리기
  • Header: GET
  • Url: GET
  • QueryString: GET
ClaimsFormat 아니요 현재 사용되지 않으므로 무시할 수 있습니다.
ClaimUsedForRequestPayload 아니요 REST API에 전송될 페이로드가 포함된 문자열 클레임의 이름입니다.
DebugMode 아니요 디버그 모드에서 기술 프로필을 실행합니다. 가능한 값: true또는 false (기본값) 디버그 모드에서 REST API는 자세한 정보를 반환할 수 있습니다. 오류 메시지 반환 섹션을 참조하세요.
IncludeClaimResolvingInClaimsHandling 아니요 입력 및 출력 클레임의 경우 기술 프로필에 클레임 해결이 포함되는지 여부를 지정합니다. 가능한 값: true또는 false (기본값) 기술 프로필에서 클레임 해결 프로그램을 사용하려면 이를 true로 설정합니다.
ResolveJsonPathsInJsonTokens 아니요 기술 프로필이 JSON 경로를 확인하는지 여부를 나타냅니다. 가능한 값: true또는 false (기본값) 이 메타데이터를 사용하여 중첩된 JSON 요소에서 데이터를 읽습니다. OutputClaim에서 PartnerClaimType을 출력하려는 JSON 경로 요소로 설정합니다. 예를 들면 firstName.localized 또는 data[0].to[0].email입니다.
UseClaimAsBearerToken 아니요 전달자 토큰을 포함하는 클레임의 이름입니다.

오류 처리

다음 메타데이터를 REST API 실패 시 표시되는 오류 메시지를 구성하는 데 사용할 수 있습니다. 오류 메시지를 지역화할 수 있습니다.

Attribute Required 설명
DefaultUserMessageIfRequestFailed 아니요 모든 REST API 예외에 대한 사용자 지정된 기본 오류 메시지입니다.
UserMessageIfCircuitOpen 아니요 REST API에 연결할 수 없는 경우의 오류 메시지입니다. 지정하지 않으면 DefaultUserMessageIfRequestFailed가 반환됩니다.
UserMessageIfDnsResolutionFailed 아니요 DNS 확인 예외에 대한 오류 메시지입니다. 지정하지 않으면 DefaultUserMessageIfRequestFailed가 반환됩니다.
UserMessageIfRequestTimeout 아니요 연결 시간이 초과될 때의 오류 메시지입니다. 지정하지 않으면 DefaultUserMessageIfRequestFailed가 반환됩니다.

암호화 키

인증 유형을 설정None하면 CryptographicKeys 요소가 사용되지 않습니다.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
</TechnicalProfile>

인증 형식이 Basic으로 설정된 경우 CryptographicKeys 요소에 다음 특성이 포함됩니다.

Attribute Required 설명
BasicAuthenticationUsername 예 인증하는 데 사용되는 사용자 이름입니다.
BasicAuthenticationPassword 예 인증에 사용되는 암호입니다.

다음 예제에서는 기본 인증을 사용하는 기술 프로필을 보여줍니다.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Basic</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BasicAuthenticationUsername" StorageReferenceId="B2C_1A_B2cRestClientId" />
    <Key Id="BasicAuthenticationPassword" StorageReferenceId="B2C_1A_B2cRestClientSecret" />
  </CryptographicKeys>
</TechnicalProfile>

인증 유형이 설정된 ClientCertificate경우 CryptographicKeys 요소에는 다음 특성이 포함됩니다.

Attribute Required 설명
ClientCertificate 예 인증에 사용할 X509 인증서(RSA 키 집합)입니다. 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ClientCertificate</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="ClientCertificate" StorageReferenceId="B2C_1A_B2cRestClientCertificate" />
  </CryptographicKeys>
</TechnicalProfile>

인증 유형이 설정된 Bearer경우 CryptographicKeys 요소에는 다음 특성이 포함됩니다.

Attribute Required 설명
BearerAuthenticationToken 아니요 OAuth 2.0 전달자 토큰입니다. 
<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">Bearer</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="BearerAuthenticationToken" StorageReferenceId="B2C_1A_B2cRestClientAccessToken" />
  </CryptographicKeys>
</TechnicalProfile>

인증 유형이 설정된 ApiKeyHeader경우 CryptographicKeys 요소에는 다음 특성이 포함됩니다.

Attribute Required 설명
HTTP 헤더의 이름(예: x-functions-key또는 x-api-key. 예 인증에 사용되는 키입니다.

참고 항목

현재 Azure AD B2C에서는 인증에 HTTP 헤더 하나만 지원합니다. RESTful 호출에 헤더 여러 개(예: 클라이언트 ID 및 클라이언트 암호 값)가 필요한 경우 어떤 식으로든 요청에 프록시를 사용해야 합니다.

<TechnicalProfile Id="REST-API-SignUp">
  <DisplayName>Validate user's input data and return loyaltyNumber claim</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app-name.azurewebsites.NET/api/identity/signup</Item>
    <Item Key="AuthenticationType">ApiKeyHeader</Item>
    <Item Key="SendClaimsIn">Body</Item>
  </Metadata>
  <CryptographicKeys>
    <Key Id="x-functions-key" StorageReferenceId="B2C_1A_RestApiKey" />
  </CryptographicKeys>
</TechnicalProfile>

유효성 검사 오류 메시지 반환

REST API는 'CRM 시스템에서 사용자를 찾을 수 없습니다.'와 같은 오류 메시지를 반환해야 할 수 있습니다. 오류가 발생하면 REST API는 400(잘못된 요청) 또는 409(충돌) 응답 상태 코드와 같은 HTTP 4xx 오류 메시지를 반환해야 합니다. 응답 본문에는 JSON 형식의 오류 메시지가 포함됩니다.

{
  "version": "1.0.0",
  "status": 409,
  "code": "API12345",
  "requestId": "50f0bd91-2ff4-4b8f-828f-00f170519ddb",
  "userMessage": "Message for the user",
  "developerMessage": "Verbose description of problem and how to fix it.",
  "moreInfo": "https://restapi/error/API12345/moreinfo"
}
Attribute Required 설명
version 예 REST API 버전입니다. 예: 1.0.1
status 예 HTTP 응답은 코드와 같은 숫자로 상태 409여야 합니다. REST 서비스는 HTTP 4XX 상태 코드를 반환할 수 있지만 JSON 형식 응답 status 본문에 제출된 값은 있어야 409합니다.
코드 아니요 활성화되면 표시되는 DebugMode RESTful 엔드포인트 공급자의 오류 코드입니다.
requestId 아니요 활성화되면 표시되는 DebugMode RESTful 엔드포인트 공급자의 요청 식별자입니다.
userMessage 예 사용자에게 표시되는 오류 메시지입니다.
developerMessage 아니요 문제에 대한 자세한 설명과 문제를 해결하는 방법은 활성화된 경우 DebugMode 표시됩니다.
moreInfo 아니요 사용하도록 설정된 경우 DebugMode 표시되는 추가 정보를 가리키는 URI입니다.

다음 예제에서는 오류 메시지를 반환하는 C# 클래스를 보여줍니다.

public class ResponseContent
{
  public string Version { get; set; }
  public int Status { get; set; }
  public string Code { get; set; }
  public string UserMessage { get; set; }
  public string DeveloperMessage { get; set; }
  public string RequestId { get; set; }
  public string MoreInfo { get; set; }
}

다음 단계

RESTful 기술 프로필 사용 예제에 대해서는 다음 문서를 참조하세요.