Azure Active Directory B2C 사용자 지정 정책의 클레임 확인자 정보

아티클
01/19/2024

Azure AD B2C(Azure Active Directory B2C) 사용자 지정 정책 의 클레임 확인자는 정책 이름, 요청 상관 관계 ID, 사용자 인터페이스 언어 등 권한 부여 요청에 대한 컨텍스트 정보를 제공합니다.

입력 또는 출력 클레임에서 클레임 확인자를 사용하려면 ClaimsSchema 요소 아래에 문자열 ClaimType을 정의한 다음 DefaultValue를 입력 또는 출력 클레임 요소의 클레임 확인자로 설정합니다. Azure AD B2C는 클레임 확인자의 값을 읽고 기술 프로필의 값을 사용합니다.

다음 예제에서 명명 correlationId 된 클레임 형식은 DataType으로 string정의됩니다.

<ClaimType Id="correlationId">
  <DisplayName>correlationId</DisplayName>
  <DataType>string</DataType>
  <UserHelpText>Request correlation Id</UserHelpText>
</ClaimType>

기술 프로필에서 클레임 해결 프로그램을 클레임 유형으로 매핑합니다. Azure AD B2C는 클레임 확인자의 {Context:CorrelationId} 값을 클레임 correlationId 에 채우고 클레임을 기술 프로필로 보냅니다.

<InputClaim ClaimTypeReferenceId="correlationId" DefaultValue="{Context:CorrelationId}" />

문화권

다음 표에는 권한 부여 요청에 사용되는 언어에 대한 정보와 함께 클레임 확인자가 나와 있습니다.

클레임	설명	예시
{Culture:LanguageName}	언어에 대한 두 문자 ISO 코드입니다.	en
{Culture:LCID}	언어 코드의 LCID입니다.	1033
{Culture:RegionName}	지역에 대한 두 문자 ISO 코드입니다.	US
{Culture:RFC5646}	RFC5646 언어 코드	en-US

문화권 클레임 해결 프로그램의 라이브 데모를 확인하세요.

정책

다음 표에는 권한 부여 요청에 사용되는 정책에 대한 정보와 함께 클레임 확인자가 나와 있습니다.

클레임	설명	예시
{Policy:PolicyId}	신뢰 당사자 정책 이름입니다.	B2C_1A_signup_signin
{Policy:RelyingPartyTenantId}	신뢰 당사자 정책의 테넌트 ID입니다.	your-tenant.onmicrosoft.com
{Policy:TenantObjectId}	신뢰 당사자 정책의 테넌트 개체 ID입니다.	00000000-0000-0000-0000-000000000000
{Policy:TrustFrameworkTenantId}	트러스트 프레임워크의 테넌트 ID입니다.	your-tenant.onmicrosoft.com

정책 클레임 해결 프로그램의 라이브 데모를 확인하세요.

Context

다음 표에는 권한 부여 요청의 컨텍스트 클레임 확인자가 나와 있습니다.

클레임	설명	예시
{Context:BuildNumber}	ID 경험 프레임워크 버전(빌드 번호)입니다.	1.0.507.0
{Context:CorrelationId}	상관 관계 ID입니다.	00000000-0000-0000-0000-000000000000
{Context:DateTimeInUtc}	날짜 시간(UTC)입니다.	10/10/2021 12:00:00 PM
{Context:DeploymentMode}	정책 배포 모드입니다.	생산
{Context:HostName}	현재 요청의 호스트 이름입니다.	contoso.b2clogin.com
{Context:IPAddress}	사용자 IP 주소입니다.	11.111.111.11
{Context:KMSI}	로그인 유지 검사 상자가 선택되어 있는지 여부를 나타냅니다.	true

컨텍스트 클레임 해결 프로그램의 라이브 데모를 확인하세요.

클레임

이 섹션에서는 클레임 값을 클레임 확인자로 얻는 방법을 설명합니다.

클레임	설명	예시
{Claim:claim type}	정책 파일 또는 상위 정책 파일의 ClaimsSchema 섹션에 이미 정의된 클레임 유형의 식별자입니다. 예를 들면 `{Claim:displayName}` 또는 `{Claim:objectId}`입니다.	클레임 유형 값.

OpenID Connect

다음 표에는 OpenID Connect 권한 부여 요청에 대한 정보와 함께 클레임 확인자가 나와 있습니다.

클레임	설명	예시
{OIDC:AuthenticationContextReferences}	쿼리 문자열 매개 변수입니다 `acr_values` .	해당 없음
{OIDC:ClientId}	쿼리 문자열 매개 변수입니다 `client_id` .	00000000-0000-0000-0000-000000000000
{OIDC:Do기본Hint}	쿼리 문자열 매개 변수입니다 `domain_hint` .	facebook.com
{OIDC:LoginHint}	쿼리 문자열 매개 변수입니다 `login_hint` .	someone@contoso.com
{OIDC:MaxAge}	`max_age`.	해당 없음
{OIDC:Nonce}	쿼리 문자열 매개 변수입니다 `Nonce` .	defaultNonce
{OIDC:Password}	리소스 소유자 암호 자격 증명 흐름 사용자의 암호입니다.	password1
{OIDC:Prompt}	쿼리 문자열 매개 변수입니다 `prompt` .	login
{OIDC:RedirectUri}	쿼리 문자열 매개 변수입니다 `redirect_uri` .	https://jwt.ms
{OIDC:Resource}	쿼리 문자열 매개 변수입니다 `resource` .	해당 없음
{OIDC:Scope}	쿼리 문자열 매개 변수입니다 `scope` .	openid
{OIDC:Username}	리소스 소유자 암호 자격 증명 흐름 사용자의 사용자 이름입니다.	emily@contoso.com
{OIDC:IdToken}	쿼리 문자열 매개 변수입니다 `id token` .	해당 없음

OpenID Connect 클레임 확인 프로그램의 라이브 데모를 확인하세요.

OAuth2 키-값 매개 변수

OIDC 또는 OAuth2 요청의 일부로 포함된 모든 매개 변수 이름은 사용자 경험에서 클레임에 매핑될 수 있습니다. 예를 들어, 애플리케이션의 요청에는 이름이 app_session, loyalty_number 또는 사용자 지정 쿼리 문자열인 쿼리 문자열 매개 변수가 포함될 수 있습니다.

클레임	설명	예시
{OAUTH-KV:campaignId}	쿼리 문자열 매개 변수입니다.	하와이
{OAUTH-KV:app_session}	쿼리 문자열 매개 변수입니다.	A3C5R
{OAUTH-KV:loyalty_number}	쿼리 문자열 매개 변수입니다.	1234
{OAUTH-KV:any custom query string}	쿼리 문자열 매개 변수입니다.	해당 없음

SAML 키-값 매개 변수

SAML 인증 요청에서 요청에 포함되지만 프로토콜(예: SAMLRequest)과 관련이 없는 매개 변수 이름은 사용자 경험의 클레임에 매핑될 수 있습니다. 예를 들어 요청에는 .와 같은 username사용자 지정 매개 변수가 포함될 수 있습니다. SP 시작 및 IDP 시작 SAML 요청 모두에 적용됩니다.

클레임	설명	예시
{SAML-KV:username}	쿼리 문자열 또는 POST 본문 매개 변수입니다.	username@domain.com
{SAML-KV:loyalty_number}	쿼리 문자열 또는 POST 본문 매개 변수입니다.	1234
{SAML-KV:모든 사용자 지정 쿼리 문자열}	쿼리 문자열 또는 POST 본문 매개 변수입니다.	해당 없음

SAML

다음 표에는 SAML 권한 부여 요청에 대한 정보와 함께 클레임 확인자가 나와 있습니다.

클레임	설명	예시
{SAML:AuthnContextClassReferences}	`AuthnContextClassRef` SAML 요청의 요소 값입니다.	urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
{SAML:NameIdPolicyFormat}	`Format` SAML 요청 요소의 `NameIDPolicy` 특성입니다.	urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
{SAML:Issuer}	SAML `Issuer` 요청의 SAML 요소 값입니다.	`https://contoso.com`
{SAML:AllowCreate}	SAML 요청의 `NameIDPolicy` 요소에 있는 `AllowCreate` 특성 값입니다.	True
{SAML:ForceAuthn}	SAML 요청의 `AuthnRequest` 요소에 있는 `ForceAuthN` 특성 값입니다.	True
{SAML:ProviderName}	SAML 요청의 `AuthnRequest` 요소에 있는 `ProviderName` 특성 값입니다.	Contoso.com
{SAML:RelayState}	쿼리 문자열 매개 변수입니다 `RelayState` .
{SAML:Subject}	`Subject` SAML AuthN 요청의 NameId 요소에서 가져옵니다.
{SAML:Binding}	SAML 요청의 `AuthnRequest` 요소에 있는 `ProtocolBinding` 특성 값입니다.	urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST

SAML 클레임 해결 프로그램의 라이브 데모를 확인하세요.

OAuth2 ID 공급자

다음 표에는 OAuth2 ID 공급자 클레임 확인자가 나와 있습니다.

클레임	설명	예시
{oauth2:access_token}	OAuth2 ID 공급자 액세스 토큰입니다. `access_token` 특성입니다.	`eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1Ni...`
{oauth2:token_type}	액세스 토큰의 형식입니다. `token_type` 특성입니다.	무기명
{oauth2:expires_in}	액세스 토큰이 유효한 시간(초)입니다. `expires_in` 특성입니다. 출력 클레임 DataType은 `int` 또는 `long`이어야 합니다.	960000
{oauth2:refresh_token}	OAuth2 ID 공급자 새로 고침 토큰입니다. `refresh_token` 특성입니다.	`eyJraWQiOiJacW9pQlp2TW5pYVc2MUY...`

OAuth2 ID 공급자 클레임 해결 프로그램을 사용하려면 출력 클레임의 PartnerClaimType 특성을 클레임 해결 프로그램으로 설정합니다. 다음 예제에서는 외부 ID 공급자 클레임을 가져오는 방법을 보여 줍니다.

<ClaimsProvider>
  <DisplayName>Contoso</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="Contoso-OAUTH">
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessToken" PartnerClaimType="{oauth2:access_token}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenType" PartnerClaimType="{oauth2:token_type}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderAccessTokenExpiresIn" PartnerClaimType="{oauth2:expires_in}" />
        <OutputClaim ClaimTypeReferenceId="identityProviderRefreshToken" PartnerClaimType="{oauth2:refresh_token}" />
      </OutputClaims>
      ...
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

클레임 해결 프로그램 사용

다음 요소와 함께 클레임 확인자를 사용할 수 있습니다.

Item	요소	설정
Application Insights 기술 프로필	`InputClaim`
Microsoft Entra 기술 프로필	`InputClaim`, `OutputClaim`	1, 2
OAuth2 기술 프로필	`InputClaim`, `OutputClaim`	1, 2
OpenID 커넥트 기술 프로필	`InputClaim`, `OutputClaim`	1, 2
클레임 변환 기술 프로필	`InputClaim`, `OutputClaim`	1, 2
RESTful 공급자 기술 프로필	`InputClaim`	1, 2
SAML ID 공급자 기술 프로필	`OutputClaim`	1, 2
자체 어설션된 기술 프로필	`InputClaim`, `OutputClaim`	1, 2
ContentDefinition	`LoadUri`
ContentDefinitionParameters	`Parameter`
RelyingParty 기술 프로필	`OutputClaim`	2

설정:

메타데이터는 IncludeClaimResolvingInClaimsHandling .로 true설정해야 합니다.
입력 또는 출력 클레임 특성 AlwaysUseDefaultValue를 true로 설정해야 합니다.

클레임 해결 프로그램 샘플

RESTful 기술 프로필

RESTful 기술 프로필에서 사용자 언어, 정책 이름, 범위 및 클라이언트 ID를 보낼 수 있습니다. 클레임에 따라 REST API는 사용자 지정 비즈니스 논리를 실행할 수 있으며 필요한 경우 지역화된 오류 메시지가 발생합니다.

다음 예제에서는 해당 시나리오의 RESTful 기술 프로필을 보여 줍니다.

<TechnicalProfile Id="REST">
  <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" />
  <Metadata>
    <Item Key="ServiceUrl">https://your-app.azurewebsites.net/api/identity</Item>
    <Item Key="AuthenticationType">None</Item>
    <Item Key="SendClaimsIn">Body</Item>
    <Item Key="IncludeClaimResolvingInClaimsHandling">true</Item>
  </Metadata>
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="userLanguage" DefaultValue="{Culture:LCID}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="policyName" DefaultValue="{Policy:PolicyId}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="scope" DefaultValue="{OIDC:Scope}" AlwaysUseDefaultValue="true" />
    <InputClaim ClaimTypeReferenceId="clientId" DefaultValue="{OIDC:ClientId}" AlwaysUseDefaultValue="true" />
  </InputClaims>
  <UseTechnicalProfileForSessionManagement ReferenceId="SM-Noop" />
</TechnicalProfile>

클레임 해결 프로그램을 사용하여 로그인 이름을 미리 채울 수도 있고 Facebook, LinkedIn 또는 Microsoft 계정과 같은 특정 소셜 ID 공급자에 직접 로그인할 수도 있습니다. 자세한 내용은 Azure Active Directory B2C를 사용하여 직접 로그인 설정을 참조하세요.

동적 UI 사용자 지정

Azure AD B2C를 사용하면 HTML 콘텐츠 정의 엔드포인트에 쿼리 문자열 매개 변수를 전달하여 페이지 콘텐츠를 동적으로 렌더링할 수 있습니다. 예를 들어 이 기능을 사용하면 웹 또는 모바일 애플리케이션에서 전달하는 사용자 지정 매개 변수를 기반으로 Azure AD B2C 등록 또는 로그인 페이지에서 배경 이미지를 수정할 수 있습니다. 자세한 내용은 Azure Active Directory B2C에서 사용자 지정 정책을 사용하여 동적으로 UI 구성을 참조하세요. 언어 매개 변수를 기반으로 HTML 페이지를 지역화하거나 클라이언트 ID를 기반으로 콘텐츠를 변경할 수도 있습니다.

다음 예제에서는 값, 언어 코드 및 클라이언트 ID를 나타내는 앱을 사용하여 campaignIdHawaii라는 쿼리 문자열 매개 변수를 전달합니다.en-US

<UserJourneyBehaviors>
  <ContentDefinitionParameters>
    <Parameter Name="campaignId">{OAUTH-KV:campaignId}</Parameter>
    <Parameter Name="language">{Culture:RFC5646}</Parameter>
    <Parameter Name="app">{OIDC:ClientId}</Parameter>
  </ContentDefinitionParameters>
</UserJourneyBehaviors>

따라서 Azure AD B2C는 위의 매개 변수를 HTML 콘텐츠 페이지로 보냅니다.

/selfAsserted.aspx?campaignId=hawaii&language=en-US&app=0239a9cc-309c-4d41-87f1-31288feb2e82

콘텐츠 정의

ContentDefinitionLoadUri에서 클레임 해결 프로그램을 전송하여 사용된 매개 변수에 따라 여러 위치에서 콘텐츠를 풀할 수 있습니다.

<ContentDefinition Id="api.signuporsignin">
  <LoadUri>https://contoso.blob.core.windows.net/{Culture:LanguageName}/myHTML/unified.html</LoadUri>
  ...
</ContentDefinition>

Application Insights 기술 프로필

Azure 애플리케이션 Insights 및 클레임 해결 프로그램을 사용하면 사용자 동작에 대한 인사이트를 얻을 수 있습니다. Application Insights 기술 프로필에서 Azure 애플리케이션 Insights에 유지되는 입력 클레임을 보냅니다. 자세한 내용은 Application Insights를 사용하여 Azure AD B2C 경험의 사용자 동작 추적을 참조하세요. 다음 예제에서는 정책 ID, 상관 관계 ID, 언어 및 클라이언트 ID를 Azure 애플리케이션 Insights로 보냅니다.

<TechnicalProfile Id="AzureInsights-Common">
  <DisplayName>Alternate Email</DisplayName>
  <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.Insights.AzureApplicationInsightsProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
  ...
  <InputClaims>
    <InputClaim ClaimTypeReferenceId="PolicyId" PartnerClaimType="{property:Policy}" DefaultValue="{Policy:PolicyId}" />
    <InputClaim ClaimTypeReferenceId="CorrelationId" PartnerClaimType="{property:CorrelationId}" DefaultValue="{Context:CorrelationId}" />
    <InputClaim ClaimTypeReferenceId="language" PartnerClaimType="{property:language}" DefaultValue="{Culture:RFC5646}" />
    <InputClaim ClaimTypeReferenceId="AppId" PartnerClaimType="{property:App}" DefaultValue="{OIDC:ClientId}" />
  </InputClaims>
</TechnicalProfile>

신뢰 당사자 정책

신뢰 당사자 정책 기술 프로필에서 테넌트 ID 또는 상관 관계 ID를 JWT 내의 신뢰 당사자 애플리케이션으로 보낼 수 있습니다.

<RelyingParty>
    <DefaultUserJourney ReferenceId="SignUpOrSignIn" />
    <TechnicalProfile Id="PolicyProfile">
      <DisplayName>PolicyProfile</DisplayName>
      <Protocol Name="OpenIdConnect" />
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="displayName" />
        <OutputClaim ClaimTypeReferenceId="givenName" />
        <OutputClaim ClaimTypeReferenceId="surname" />
        <OutputClaim ClaimTypeReferenceId="email" />
        <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
        <OutputClaim ClaimTypeReferenceId="identityProvider" />
        <OutputClaim ClaimTypeReferenceId="tenantId" AlwaysUseDefaultValue="true" DefaultValue="{Policy:TenantObjectId}" />
        <OutputClaim ClaimTypeReferenceId="correlationId" AlwaysUseDefaultValue="true" DefaultValue="{Context:CorrelationId}" />
      </OutputClaims>
      <SubjectNamingInfo ClaimType="sub" />
    </TechnicalProfile>
  </RelyingParty>

다음 단계

Azure AD B2C 커뮤니티 GitHub 리포지토리에서 더 많은 클레임 해결 프로그램 샘플 찾기