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

Статья
01/11/2024

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. В таблице ниже перечислены обязательные утверждения. Остальные утверждения являются необязательными.

Имя	Утверждение	Пример значения	Description
Аудитория	`aud`	`a489fc44-3cc0-4a78-92f6-e413cd853eae`	Определяет целевого получателя маркера. Аудитория — это произвольная строка, определяемая издателем маркера. Azure AD B2C проверяет это значение и отклоняет маркер в случае несовпадения.
Издатель	`iss`	`https://localhost`	Идентифицирует службу маркеров безопасности (издателя маркеров). Издатель — это произвольный URI, определяемый издателем маркеров. Azure AD B2C проверяет это значение и отклоняет маркер в случае несовпадения.
Время окончания срока действия	`exp`	`1600087315`	Время окончания срока действия маркера в виде времени эпохи. Azure AD B2C проверяет это значение и отклоняет маркер в случае истечения срока его действия.
Не ранее	`nbf`	`1599482515`	Время начала срока действия маркера в виде времени эпохи. Оно обычно совпадает со временем выдачи маркера. Azure AD B2C проверяет это значение и отклоняет маркер, если время его существования является недопустимым.

Ниже приведен пример допустимого маркера идентификации:

{
  "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"
}

Протокол

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

<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. Может потребоваться сопоставить имя утверждения, определенное в политике, с именем, определенным в REST API. Также можете добавить утверждения, которые не возвращаются маркером JWT, установив атрибут DefaultValue.

Метаданные

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

Атрибут	Обязательное поле	Описание
Издатель	Да	Идентифицирует службу маркеров безопасности (издателя маркеров). Это значение должно совпадать с утверждением `iss` в утверждении маркера JWT.
IdTokenAudience	Да	Определяет целевого получателя маркера. Это значение должно совпадать с утверждением `aud` в утверждении маркера JWT.

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

Атрибут	Обязательное поле	Описание
МЕТАДАННЫЕ	Да	URL-адрес, указывающий на документ конфигурации издателя маркеров, который также называется известной конечной точкой конфигурации OpenID.
Издатель	No	Идентифицирует службу маркеров безопасности (издателя маркеров). Это значение можно использовать для перезаписи значения, настроенного в метаданных, и должно совпадать с утверждением `iss` в утверждении маркера JWT.
IdTokenAudience	No	Определяет целевого получателя маркера. Это значение должно совпадать с утверждением `aud` в утверждении маркера JWT.

Важно!

Ваши конечные точки должны соответствовать требованиям безопасности Azure AD B2C. Ранние версии и шифры TLS считаются нерекомендуемыми. Дополнительные сведения см. в статье Требования к комплекту шифров и TLS в Azure AD B2C.

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

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

Атрибут	Обязательное поле	Описание
client_secret	Да	Криптографический ключ, используемый для проверки подписи маркера JWT.

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

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

Шаг 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.

Войдите на портал Azure.
Если у вас есть доступ к нескольким клиентам, выберите значок Параметры в верхнем меню, чтобы переключиться на клиент Azure AD B2C из меню каталогов и подписок.
В портале Azure найдите и выберите Azure AD B2C.
На странице "Обзор" в разделе Политики выберите Identity Experience Framework.
Щелкните Ключи политики.
Выберите Вручную.
Для параметра Имя используйте значение IdTokenHintKey.
Префикс B2C_1A_ может быть добавлен автоматически.
В поле Секрет введите созданный ранее ключ для входа.
Для параметра Использование ключа задайте значение Шифрование.
Выберите Создать.
Проверьте, создан ли ключ 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">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. Подготовка политики

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

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

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

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

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

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

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

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

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

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

Выполните эту команду 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. Подготовка кода

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

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

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

Добавьте технический профиль IdTokenHint_ExtractClaims в cdj. политику расширения.
Добавьте следующий шаг оркестрации в свой путь взаимодействия пользователя в качестве первого элемента.
```
<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />
```

В политике проверяющей стороны воспроизведите те же входные утверждения, что были настроены в техническом профиле 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=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

Следующие шаги

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

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

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

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

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

Протокол

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

Метаданные

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

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

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

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

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

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

Шаг 4. Подготовка политики

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

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

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

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

Шаг 3. Подготовка политики

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

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

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

Следующие шаги

Дополнительные ресурсы