Определение технического профиля указания маркера идентификатора в пользовательской политике Azure Active Directory B2C

Azure AD B2C позволяет приложениям проверяющей стороны отправлять входящий JWT в рамках запроса авторизации OAuth2. JWT может быть выдан приложением проверяющей стороны или поставщиком удостоверений, и он может передать указание о пользователе или запросе авторизации. Azure AD B2C проверяет подпись, имя издателя и аудиторию маркеров и извлекает утверждение из входящего маркера.

Случаи использования

Это решение можно использовать для отправки данных в Azure AD B2C, инкапсулированных в одном JWT. РешениеSignup with email invitation, в котором системный администратор может отправить подписанное приглашение пользователям, основано на id_token_hint. Только пользователи с доступом к электронной почте приглашения могут создать учетную запись в каталоге.

Подход к подписи маркеров

При использовании id_token_hint издатель токена (приложение проверяющей стороны или поставщик удостоверений) создает маркер, а затем подписывает его с помощью ключа подписи, чтобы доказать, что маркер поступает из надежного источника. Ключ подписывания может быть симметричным или асимметричным. Симметричная криптография или криптография закрытого ключа использует общий секрет для подписи и проверки подписи. Асимметричная криптография или криптография открытого ключа — это криптографическая система, которая использует как закрытый ключ, так и открытый ключ. Закрытый ключ известен только издателю маркера и используется для подписи маркера. Открытый ключ предоставляется политике Azure AD B2C для проверки подписи маркера.

Формат токена

Id_token_hint должен быть допустимым JWT. В следующей таблице перечислены утверждения, которые являются обязательными. Дополнительные утверждения являются необязательными.

Следующий маркер является примером допустимого маркера идентификатора:

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "[email protected]",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

Протокол

Атрибуту Name элемента Protocol необходимо присвоить значение None. Например, протокол для технического профиля IdTokenHint_ExtractClaims:None

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

Технический профиль вызывается из шага оркестрации с типом GetClaims.

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

Исходящие утверждения

Элемент OutputClaims содержит список утверждений, извлекаемых из JWT. Возможно, потребуется сопоставить имя утверждения, определенного в политике, с именем, определенным в JWT. Кроме того, можно включить утверждения, которые не возвращаются JWT, если вы задали DefaultValue атрибут.

Метаданные

При использовании симметричного ключа важны следующие метаданные.

При использовании асимметричного ключа важны следующие метаданные.

Криптографические ключи

При использовании симметричного ключа элемент CryptographicKeys содержит следующий атрибут:

Практическое руководство

Выдача маркера с симметричными ключами

Шаг 1. Создание общего ключа

Создайте ключ, который можно использовать для подписи маркера. Например, используйте следующий код PowerShell для создания ключа.

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

Этот код создает строку секрета, например VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=.

Шаг 2. Добавление ключа подписи в Azure AD B2C

Тот же ключ, который используется издателем маркеров, необходимо создать в ключах политики Azure AD B2C.

1. Войдите на портал Azure.
2. Если у вас есть доступ к нескольким клиентам, щелкните значок Настройки в верхнем меню, чтобы переключиться на клиент Azure AD B2C из меню Каталоги и подписки.
3. В портале Azure найдите и выберите Azure AD B2C.
4. На странице обзора в разделе Политикивыберите Identity Experience Framework.
5. Выбор ключей политики
6. Выберите Вручную.
7. Для имени используйте IdTokenHintKey.
   Префикс B2C_1A_ может быть добавлен автоматически.
8. В поле "Секрет" введите ключ входа, созданный ранее.
9. Для использования ключей используйте шифрование.
10. Нажмите кнопку "Создать".
11. Убедитесь, что вы создали ключ B2C_1A_IdTokenHintKey.

Шаг 3. Добавление технического профиля указания маркера идентификатора

Следующий технический профиль проверяет маркер и извлекает утверждения.

<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">00001111-aaaa-2222-bbbb-3333cccc4444</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. Подготовка политики

Выполните шаг настройки политики .

Шаг 5. Подготовка кода

Пример GitHub — это ASP.NET веб-приложение и консольное приложение, которое создает маркер идентификатора, подписанный с помощью симметричного ключа.

Выдача маркера асимметричными ключами

С асимметричным ключом маркер подписывается с помощью сертификатов RSA. Это приложение размещает конечную точку метаданных OpenID Connect и конечную точку веб-ключей JSON (JWKs), которая используется Azure AD B2C для проверки подписи маркера идентификатора.

Издатель токена должен предоставить следующие конечные точки:

• /.well-known/openid-configuration — известная конечная точка конфигурации с соответствующими сведениями о маркере, например имя издателя маркера и ссылка на конечную точку JWK.
• /.well-known/keys — конечная точка веб-ключа JSON (JWK) с открытым ключом, который используется для подписи ключа (с частью закрытого ключа сертификата).

См. пример контроллера TokenMetadataController.cs .NET MVC.

Шаг 1. Подготовка самозаверяющего сертификата

Если у вас еще нет сертификата, вы можете использовать самозаверяющий сертификат для этого руководства. В Windows можно использовать командлет New-SelfSignedCertificate PowerShell для создания сертификата.

Выполните следующую команду PowerShell, чтобы создать самозаверяющий сертификат. Измените -Subject аргумент соответствующим образом для вашего приложения и имени клиента Azure AD B2C. Можно также изменить -NotAfter дату, чтобы указать другой срок действия сертификата.

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. Добавление технического профиля указания маркера идентификатора

Следующий технический профиль проверяет маркер и извлекает утверждения. Измените URI метаданных на общеизвестную конечную точку конфигурации издателя маркеров.

<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. Подготовка политики

Выполните шаг настройки политики .

Шаг 4. Подготовка кода

Этот пример GitHub ASP.NET веб-приложение создает маркеры идентификатора и размещает конечные точки метаданных, необходимые для использования параметра "id_token_hint" в Azure AD B2C.

Настройка политики

Для симметричных и асимметричных подходов id_token_hint технический профиль вызывается из шага оркестрации с типом GetClaims и должен указывать входные утверждения политики проверяющей стороны.

1. Добавьте IdTokenHint_ExtractClaims технический профиль в политику расширения.

2. Добавьте следующий шаг оркестрации в путешествие пользователя в качестве первого элемента.

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

3. В политике проверяющей стороны повторите те же входные утверждения, которые вы настроили в техническом профиле IdTokenHint_ExtractClaims. Рассмотрим пример.

   <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>
   

В зависимости от бизнес-требований может потребоваться добавить проверки маркеров, например проверить формат адреса электронной почты. Для этого добавьте шаги оркестрации, которые вызывают технический профиль преобразования утверждений. Кроме того, добавьте самоутверждаемый технический профиль , чтобы представить сообщение об ошибке.

Создание и подпись маркера

Примеры GitHub иллюстрируют создание такого маркера для JWT, который позже отправляется в качестве id_token_hint параметра строки запроса. Ниже приведен пример запроса авторизации с параметром id_token_hint

https://tenant-name.b2clogin.com/tenant-name.onmicrosoft.com/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=11112222-bbbb-3333-cccc-4444dddd5555&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

Дальнейшие шаги

• Проверьте регистрацию с помощью решения для приглашения электронной почты в репозитории GitHub сообщества Azure AD B2C.