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