Azure Active Directory B2C özel ilkesinde kimlik belirteci ipucu teknik profili tanımlama

Makale
01/11/2024

Azure AD B2C, bağlı olan taraf uygulamalarının OAuth2 yetkilendirme isteğinin bir parçası olarak gelen JWT göndermesine olanak tanır. JWT belirteci bağlı olan bir taraf uygulaması veya kimlik sağlayıcısı tarafından vererek kullanıcı veya yetkilendirme isteği hakkında bir ipucu iletebilir. Azure AD B2C imzayı, verenin adını ve belirteç hedef kitlesini doğrular ve gelen belirteçten talebi ayıklar.

Kullanım örnekleri

Tek bir JWT belirtecinde kapsüllenmiş Azure AD B2C'ye veri göndermek için bu çözümü kullanabilirsiniz. Sistem yöneticinizin Signup with email invitation kullanıcılara imzalı davet gönderebildiği çözüm, id_token_hint temel alır. Hesabı dizinde yalnızca davet e-postasına erişimi olan kullanıcılar oluşturabilir.

Belirteç imzalama yaklaşımı

id_token_hint ile belirteç veren (bağlı olan taraf uygulaması veya kimlik sağlayıcısı) belirteci oluşturur ve belirtecin güvenilir bir kaynaktan geldiğini kanıtlamak için bir imzalama anahtarı kullanarak imzalar. İmzalama anahtarı simetrik veya asimetrik olabilir. Simetrik şifreleme veya özel anahtar şifrelemesi, imzayı imzalamak ve doğrulamak için paylaşılan bir gizli dizi kullanır. Asimetrik şifreleme veya ortak anahtar şifrelemesi, hem özel anahtar hem de ortak anahtar kullanan bir şifreleme sistemidir. Özel anahtar yalnızca belirteç veren tarafından bilinir ve belirteci imzalamak için kullanılır. Ortak anahtar, belirtecin imzasını doğrulamak için Azure AD B2C ilkesiyle paylaşılır.

Belirteç biçimi

id_token_hint geçerli bir JWT belirteci olmalıdır. Aşağıdaki tabloda zorunlu talepler listeleniyor. Ek talepler isteğe bağlıdır.

Veri Akışı Adı	Talep	Örnek değer	Tanım
Hedef Kitle	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Belirtecin hedeflenen alıcısını tanımlar. Hedef kitle, belirteç veren tarafından tanımlanan rastgele bir dizedir. Azure AD B2C bu değeri doğrular ve eşleşmediği takdirde belirteci reddeder.
Sertifikayı veren	`iss`	`https://localhost`	Güvenlik belirteci hizmetini (belirteç veren) tanımlar. Veren, belirteç veren tarafından tanımlanan rastgele bir URI'dir. Azure AD B2C bu değeri doğrular ve eşleşmediği takdirde belirteci reddeder.
Sona erme zamanı	`exp`	`1600087315`	Belirtecin geçersiz hale geldiği zaman, dönem süresiyle gösterilir. Azure AD B2C bu değeri doğrular ve belirtecin süresi dolarsa belirteci reddeder.
Daha önce değil	`nbf`	`1599482515`	Belirtecin geçerli olduğu zaman, dönem süresiyle gösterilir. Bu süre genellikle belirtecin verildiği zamanla aynıdır. Azure AD B2C bu değeri doğrular ve belirteç ömrü geçerli değilse belirteci reddeder.

Aşağıdaki belirteç, geçerli bir kimlik belirteci örneğidir:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "a489fc44-3cc0-4a78-92f6-e413cd853eae"
}

Protokol

Protocol öğesinin Name özniteliği olarak ayarlanmalıdırNone. Örneğin, IdTokenHint_ExtractClaims teknik profilinin protokolü şöyledirNone:

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

Teknik profil, türüne sahip bir düzenleme adımından çağrılır GetClaims.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Çıkış talepleri

OutputClaims öğesi, JWT belirtecinden ayıklanacak taleplerin listesini içerir. İlkenizde tanımlanan talebin adını JWT belirtecinde tanımlanan adla eşlemeniz gerekebilir. Özniteliğini ayarladığınız DefaultValue sürece JWT belirteci tarafından döndürülmeyecek talepleri de ekleyebilirsiniz.

Meta veri

Simetrik anahtar kullanılırken aşağıdaki meta veriler geçerlidir.

Öznitelik	Zorunlu	Tanım
yayınlayan	Evet	Güvenlik belirteci hizmetini (belirteç veren) tanımlar. Bu değer JWT belirteci talebi içindeki taleple aynı `iss` olmalıdır.
IdTokenAudience	Evet	Belirtecin hedeflenen alıcısını tanımlar. JWT belirteci talebi içindeki taleple aynı `aud` olmalıdır.

Aşağıdaki meta veriler, asimetrik anahtar kullanılırken geçerlidir.

Öznitelik	Zorunlu	Tanım
META VERİ	Evet	OpenID iyi bilinen yapılandırma uç noktası olarak da bilinen belirteç veren yapılandırma belgesine işaret eden bir URL.
yayınlayan	Hayır	Güvenlik belirteci hizmetini (belirteç veren) tanımlar. Bu değer meta verilerde yapılandırılan değerin üzerine yazmak için kullanılabilir ve JWT belirteci talebi içindeki taleple `iss` aynı olmalıdır.
IdTokenAudience	Hayır	Belirtecin hedeflenen alıcısını tanımlar. JWT belirteci talebi içindeki taleple aynı `aud` olmalıdır.

Önemli

Uç noktalarınız Azure AD B2C güvenlik gereksinimlerine uygun olmalıdır. Eski TLS sürümleri ve şifreleri kullanım dışıdır. Daha fazla bilgi için bkz . Azure AD B2C TLS ve şifre paketi gereksinimleri.

Şifreleme anahtarları

Simetrik anahtar kullanırken, CryptographicKeys öğesi aşağıdaki özniteliği içerir:

Öznitelik	Zorunlu	Tanım
client_secret	Evet	JWT belirteç imzasını doğrulamak için kullanılan şifreleme anahtarı.

Nasıl yapılır kılavuzu

Simetrik anahtarlarla belirteç verme

1. Adım: Paylaşılan anahtar oluşturma

Belirteci imzalamak için kullanılabilecek bir anahtar oluşturun. Örneğin, bir anahtar oluşturmak için aşağıdaki PowerShell kodunu kullanın.

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

Bu kod gibi VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=bir gizli dizi oluşturur.

2. Adım: İmzalama anahtarını Azure AD B2C'ye ekleme

Belirteç veren tarafından kullanılan anahtarın Azure AD B2C ilke anahtarlarınızda oluşturulması gerekir.

Azure Portal oturum açın.
Birden çok kiracıya erişiminiz varsa, Dizinler + abonelikler menüsünden Azure AD B2C kiracınıza geçmek için üstteki menüden Ayarlar simgesini seçin.
Azure portalında Azure AD B2C'yi arayın ve seçin.
Genel bakış sayfasındaki İlkeler'in altında Kimlik Deneyimi Çerçevesi'ni seçin.
İlke Anahtarları'nı seçin
El ile'yi seçin.
Ad için kullanınIdTokenHintKey.
Ön ek B2C_1A_ otomatik olarak eklenebilir.
Gizli Dizi kutusuna daha önce oluşturduğunuz oturum açma anahtarını girin.
Anahtar kullanımı için Şifreleme'yi kullanın.
Oluştur seçeneğini belirleyin.
anahtarını B2C_1A_IdTokenHintKeyoluşturduğunuzu onaylayın.

3. Adım: Kimlik belirteci ipucu teknik profilini ekleme

Aşağıdaki teknik profil belirteci doğrular ve talepleri ayıklar.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">a489fc44-3cc0-4a78-92f6-e413cd853eae</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

4. Adım: İlkenizi hazırlama

İlkenizi yapılandırın adımını tamamlayın.

5. Adım: Kodu hazırlama

GitHub örneği, simetrik anahtar kullanılarak imzalanan bir kimlik belirteci oluşturan ASP.NET bir web uygulaması ve konsol uygulamasıdır.

Asimetrik anahtarlarla belirteç verme

Asimetrik anahtarla belirteç RSA sertifikaları kullanılarak imzalanır. Bu uygulama, Kimlik belirtecinin imzasını doğrulamak için Azure AD B2C tarafından kullanılan bir OpenID Bağlan meta veri uç noktasını ve JSON Web Anahtarları (JWK) uç noktasını barındırır.

Belirteç veren aşağıdaki uç noktaları sağlamalıdır:

/.well-known/openid-configuration - Belirteç hakkında, belirteç verenin adı ve JWK uç noktasının bağlantısı gibi ilgili bilgilere sahip iyi bilinen bir yapılandırma uç noktası.
/.well-known/keys - anahtarı imzalamak için kullanılan ortak anahtarla (sertifikanın özel anahtar bölümüyle) JSON Web Anahtarı (JWK) uç noktası.

TokenMetadataController.cs .NET MVC denetleyici örneğine bakın.

1. Adım: Otomatik olarak imzalanan sertifikayı hazırlama

Henüz bir sertifikanız yoksa, bu nasıl yapılır kılavuzu için otomatik olarak imzalanan bir sertifika kullanabilirsiniz. Windows'da, sertifika oluşturmak için PowerShell'in New-SelfSignedCertificate cmdlet'ini kullanabilirsiniz.

Otomatik olarak imzalanan bir sertifika oluşturmak için bu PowerShell komutunu çalıştırın. -Subject Bağımsız değişkeni uygulamanız ve Azure AD B2C kiracı adı için uygun şekilde değiştirin. Ayrıca, sertifika için -NotAfter farklı bir süre sonu belirtmek üzere tarihi ayarlayabilirsiniz.

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.onmicrosoft.com" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

2. Adım: Kimlik belirteci ipucu teknik profilini ekleme

Aşağıdaki teknik profil belirteci doğrular ve talepleri ayıklar. Meta veri URI'sini belirteç veren iyi bilinen yapılandırma uç noktanızla değiştirin.

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.azurewebsites.net/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

3. Adım: İlkenizi hazırlama

İlkenizi yapılandırın adımını tamamlayın.

4. Adım: Kodu hazırlama

Bu GitHub örnek ASP.NET web uygulaması, Kimlik belirteçleri oluşturur ve Azure AD B2C'de "id_token_hint" parametresini kullanmak için gereken meta veri uç noktalarını barındırıyor.

İlkenizi yapılandırma

Hem simetrik hem de asimetrik yaklaşımlar id_token_hint için, teknik profil türüne GetClaims sahip bir düzenleme adımından çağrılır ve bağlı olan taraf ilkesinin giriş taleplerini belirtmesi gerekir.

uzantı ilkenize IdTokenHint_ExtractClaims teknik profili ekleyin.

Kullanıcı yolculuğunuza ilk öğe olarak aşağıdaki düzenleme adımını ekleyin.

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

Bağlı olan taraf ilkenizde, IdTokenHint_ExtractClaims teknik profilinde yapılandırdığınız giriş taleplerini yineleyin. Örnek:

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

İş gereksinimlerinize bağlı olarak, belirteç doğrulamaları eklemeniz gerekebilir, örneğin e-posta adresinin biçimini denetleyin. Bunu yapmak için, talep dönüştürme teknik profilini çağıran düzenleme adımları ekleyin. Ayrıca hata iletisi sunmak için kendi kendine onaylanan bir teknik profil ekleyin.

Belirteç oluşturma ve imzalama

GitHub örnekleri, daha sonra sorgu dizesi parametresi olarak gönderilen bir JWT böyle bir id_token_hint belirteç sorununun nasıl oluşturulacağını gösterir. Aşağıda, id_token_hint parametresine sahip bir yetkilendirme isteği örneği verilmiştir

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=63ba0d17-c4ba-47fd-89e9-31b3c2734339&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

Sonraki adımlar

Azure AD B2C topluluk GitHub deposunda davet e-postası çözümüyle kaydolmayı denetleyin.