Skip to content

Commit 1eacfc7

Browse files
huypubhuypub
authored
Merge pull request #99123 from MicrosoftDocs/master
12/16 PM Publish
2 parents 5bef2eb + 442d0fa commit 1eacfc7

File tree

232 files changed

+2946
-1324
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

232 files changed

+2946
-1324
lines changed

‎articles/active-directory-b2c/TOC.yml

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,9 @@
163163
href: active-directory-b2c-reference-kmsi-custom.md
164164
- name: Password change
165165
href: active-directory-b2c-reference-password-change-custom.md
166+
- name: Phone sign-up & sign-in
167+
href: phone-authentication.md
168+
displayName: otp, passwordless, phone number
166169
- name: UX customization
167170
items:
168171
- name: Configure user input
@@ -262,6 +265,8 @@
262265
href: integer-transformations.md
263266
- name: JSON
264267
href: json-transformations.md
268+
- name: Phone number
269+
href: phone-number-claims-transformations.md
265270
- name: External accounts
266271
href: social-transformations.md
267272
- name: StringCollection
@@ -285,6 +290,9 @@
285290
items:
286291
- name: About technical profiles
287292
href: technical-profiles-overview.md
293+
- name: Azure Multi-Factor Authentication
294+
href: multi-factor-auth-technical-profile.md
295+
displayName: mfa
288296
- name: Claim resolvers
289297
href: claim-resolver-overview.md
290298
- name: Azure Active Directory

‎articles/active-directory-b2c/media/phone-authentication/assert-execution.png

51.4 KB
Loading

‎articles/active-directory-b2c/multi-factor-auth-technical-profile.md

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
---
2+
title: Azure MFA technical profiles in custom policies
3+
titleSuffix: Azure AD B2C
4+
description: Custom policy reference for Azure Multi-Factor Authentication (MFA) technical profiles in Azure AD B2C.
5+
services: active-directory-b2c
6+
author: mmacy
7+
manager: celestedg
8+
9+
ms.service: active-directory
10+
ms.workload: identity
11+
ms.topic: conceptual
12+
ms.date: 12/17/2019
13+
ms.author: marsma
14+
ms.subservice: B2C
15+
---
16+
17+
# Define an Azure MFA technical profile in an Azure AD B2C custom policy
18+
19+
[!INCLUDE [active-directory-b2c-advanced-audience-warning](../../includes/active-directory-b2c-advanced-audience-warning.md)]
20+
21+
Azure Active Directory B2C (Azure AD B2C) provides support for verifying a phone number by using Azure Multi-Factor Authentication (MFA). Use this technical profile to generate and send a code to a phone number, and then verify the code.
22+
23+
The Azure MFA technical profile may also return an error message. You can design the integration with Azure MFA by using a **Validation technical profile**. A validation technical profile calls the Azure MFA service. The validation technical profile validates the user-provided data before the user journey continues. With the validation technical profile, an error message is display on a self-asserted page.
24+
25+
[!INCLUDE [b2c-public-preview-feature](../../includes/active-directory-b2c-public-preview.md)]
26+
27+
## Protocol
28+
29+
The **Name** attribute of the **Protocol** element needs to be set to `Proprietary`. The **handler** attribute must contain the fully qualified name of the protocol handler assembly that is used by Azure AD B2C:
30+
31+
```
32+
Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
33+
```
34+
35+
The following example shows an Azure MFA technical profile:
36+
37+
```XML
38+
<TechnicalProfile Id="AzureMfa-SendSms">
39+
<DisplayName>Send Sms</DisplayName>
40+
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
41+
...
42+
```
43+
44+
## Send SMS
45+
46+
The first mode of this technical profile is to generate a code and send it. The following options can be configured for this mode.
47+
48+
### Input claims
49+
50+
The **InputClaims** element contains a list of claims to send to Azure MFA. You can also map the name of your claim to the name defined in the MFA technical profile.
51+
52+
| ClaimReferenceId | Required | Description |
53+
| --------- | -------- | ----------- |
54+
| userPrincipalName | Yes | The identifier for the user who owns the phone number. |
55+
| phoneNumber | Yes | The phone number to send an SMS code to. |
56+
| companyName | No |The company name in the SMS. If not provided, the name of your application is used. |
57+
| locale | No | The locale of the SMS. If not provided, the browser locale of the user is used. |
58+
59+
The **InputClaimsTransformations** element may contain a collection of **InputClaimsTransformation** elements that are used to modify the input claims or generate new ones before sending to the Azure MFA service.
60+
61+
### Output claims
62+
The Azure MFA protocol provider does not return any **OutputClaims**, thus there is no need to specify output claims. You can, however, include claims that aren't returned by the Azure MFA identity provider as long as you set the `DefaultValue` attribute.
63+
64+
The **OutputClaimsTransformations** element may contain a collection of **OutputClaimsTransformation** elements that are used to modify the output claims or generate new ones.
65+
66+
### Metadata
67+
68+
| Attribute | Required | Description |
69+
| --------- | -------- | ----------- |
70+
| Operation | Yes | Must be **OneWaySMS**. |
71+
| UserMessageIfInvalidFormat | No | Custom error message if the phone number provided is not a valid phone number |
72+
| UserMessageIfCouldntSendSms | No | Custom error message if the phone number provided does not accept SMS |
73+
| UserMessageIfServerError | No | Custom error message if the server has encountered an internal error |
74+
75+
### Return an error message
76+
77+
As described in [Metadata](#metadata), you can customize the error message shown to the user for different error cases. You can further localize those messages by prefixing the locale. For example:
78+
79+
```XML
80+
<Item Key="en.UserMessageIfInvalidFormat">Invalid phone number.</Item>
81+
```
82+
83+
### Example: send an SMS
84+
85+
The following example shows an Azure MFA technical profile that is used to send a code via SMS.
86+
87+
```XML
88+
<TechnicalProfile Id="AzureMfa-SendSms">
89+
<DisplayName>Send Sms</DisplayName>
90+
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
91+
<Metadata>
92+
<Item Key="Operation">OneWaySMS</Item>
93+
</Metadata>
94+
<InputClaimsTransformations>
95+
<InputClaimsTransformation ReferenceId="CombinePhoneAndCountryCode" />
96+
<InputClaimsTransformation ReferenceId="ConvertStringToPhoneNumber" />
97+
</InputClaimsTransformations>
98+
<InputClaims>
99+
<InputClaim ClaimTypeReferenceId="userPrincipalName" />
100+
<InputClaim ClaimTypeReferenceId="fullPhoneNumber" PartnerClaimType="phoneNumber" />
101+
</InputClaims>
102+
</TechnicalProfile>
103+
```
104+
105+
## Verify code
106+
107+
The second mode of this technical profile is to verify a code. The following options can be configured for this mode.
108+
109+
### Input claims
110+
111+
The **InputClaims** element contains a list of claims to send to Azure MFA. You can also map the name of your claim to the name defined in the MFA technical profile.
112+
113+
| ClaimReferenceId | Required | Description |
114+
| --------- | -------- | ----------- | ----------- |
115+
| phoneNumber| Yes | Same phone number as previously used to send a code. It is also used to locate a phone verification session. |
116+
| verificationCode | Yes | The verification code provided by the user to be verified |
117+
118+
The **InputClaimsTransformations** element may contain a collection of **InputClaimsTransformation** elements that are used to modify the input claims or generate new ones before calling the Azure MFA service.
119+
120+
### Output claims
121+
122+
The Azure MFA protocol provider does not return any **OutputClaims**, thus there is no need to specify output claims. You can, however, include claims that aren't returned by the Azure MFA identity provider as long as you set the `DefaultValue` attribute.
123+
124+
The **OutputClaimsTransformations** element may contain a collection of **OutputClaimsTransformation** elements that are used to modify the output claims or generate new ones.
125+
126+
## Metadata
127+
128+
| Attribute | Required | Description |
129+
| --------- | -------- | ----------- |
130+
| Operation | Yes | Must be **Verify** |
131+
| UserMessageIfInvalidFormat | No | Custom error message if the phone number provided is not a valid phone number |
132+
| UserMessageIfWrongCodeEntered | No | Custom error message if the code entered for verification is wrong |
133+
| UserMessageIfMaxAllowedCodeRetryReached | No | Custom error message if the user has attempted a verification code too many times |
134+
| UserMessageIfThrottled | No | Custom error message if the user is throttled |
135+
| UserMessageIfServerError | No | Custom error message if the server has encountered an internal error |
136+
137+
### Return an error message
138+
139+
As described in [Metadata](#metadata), you can customize the error message shown to the user for different error cases. You can further localize those messages by prefixing the locale. For example:
140+
141+
```XML
142+
<Item Key="en.UserMessageIfWrongCodeEntered">Wrong code has been entered.</Item>
143+
```
144+
145+
### Example: verify a code
146+
147+
The following example shows an Azure MFA technical profile used to verify the code.
148+
149+
```XML
150+
<TechnicalProfile Id="AzureMfa-VerifySms">
151+
<DisplayName>Verify Sms</DisplayName>
152+
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
153+
<Metadata>
154+
<Item Key="Operation">Verify</Item>
155+
</Metadata>
156+
<InputClaims>
157+
<InputClaim ClaimTypeReferenceId="phoneNumber" PartnerClaimType="phoneNumber" />
158+
<InputClaim ClaimTypeReferenceId="verificationCode" />
159+
</InputClaims>
160+
</TechnicalProfile>
161+
```

‎articles/active-directory-b2c/phone-authentication.md

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
title: Phone sign-up and sign-in with custom policies
3+
titleSuffix: Azure AD B2C
4+
description: Learn how to send one-time passwords in text messages to your application users' phones with custom policies in Azure Active Directory B2C.
5+
services: active-directory-b2c
6+
author: mmacy
7+
manager: celestedg
8+
9+
ms.service: active-directory
10+
ms.workload: identity
11+
ms.topic: conceptual
12+
ms.date: 12/17/2019
13+
ms.author: marsma
14+
ms.subservice: B2C
15+
---
16+
17+
# Set up phone sign-up and sign-in with custom policies in Azure AD B2C
18+
19+
Phone sign-up and sign-in in Azure Active Directory B2C (Azure AD B2C) enables your users to sign up and sign in to your applications by using a one-time password (OTP) sent in a text message to their phone. One-time passwords can help minimize the risk of your users forgetting or having their passwords compromised.
20+
21+
Follow the steps in this article to use the custom policies to enable your customers to sign up and sign in to your applications by using a one-time password sent to their phone.
22+
23+
[!INCLUDE [b2c-public-preview-feature](../../includes/active-directory-b2c-public-preview.md)]
24+
25+
## Prerequisites
26+
27+
* [Azure AD B2C tenant](tutorial-create-tenant.md)
28+
* [Web application registered](tutorial-register-applications.md) in your tenant
29+
* [Custom policies](active-directory-b2c-get-started-custom.md) uploaded to your tenant
30+
31+
## Get the phone sign-up & sign-in starter pack
32+
33+
Start by updating the phone sign-up and sign-in custom policy files to work with your Azure AD B2C tenant.
34+
35+
The following steps assume that you've completed the [prerequisites](#prerequisites) and have already cloned the [custom policy starter pack][starter-pack] repository to your local machine.
36+
37+
1. Find the [phone sign-up and sign-in custom policy files][starter-pack-phone] in your local clone of the starter pack repo, or download them directly. The XML policy files are located in the `active-directory-b2c-custom-policy-starterpack/scenarios/phone-number-passwordless` directory.
38+
1. In each file, replace the string `yourtenant` with the name of your Azure AD B2C tenant. For example, if the name of your B2C tenant is *contosob2c*, all instances of `yourtenant.onmicrosoft.com` become `contosob2c.onmicrosoft.com`.
39+
1. Complete the steps in the [Add application IDs to the custom policy](active-directory-b2c-get-started-custom.md#add-application-ids-to-the-custom-policy) section of [Get started with custom policies in Azure Active Directory B2C](active-directory-b2c-get-started-custom.md). That is, update the files in the `/phone-number-passwordless` directory with the **Application (client) IDs** of the two applications you registered when completing the prerequisites, *IdentityExperienceFramework* and *ProxyIdentityExperienceFramework*.
40+
41+
## Upload the policy files
42+
43+
1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to your Azure AD B2C tenant.
44+
1. Under **Policies**, select **Identity Experience Framework**.
45+
1. Select **Upload custom policy**.
46+
1. Upload the policy files in the following order:
47+
1. *Phone_Email_Base.xml*
48+
1. *SignUpOrSignInWithPhone.xml*
49+
1. *SignUpOrSignInWithPhoneOrEmail.xml*
50+
1. *ProfileEditPhoneOnly.xml*
51+
1. *ProfileEditPhoneEmail.xml*
52+
1. *ChangePhoneNumber.xml*
53+
1. *PasswordResetEmail.xml*
54+
55+
As you upload each file, Azure adds the prefix `B2C_1A_`.
56+
57+
## Test the custom policy
58+
59+
1. Under **Custom policies**, select **SignUpOrSignInWithPhoneOrEmail**.
60+
1. Under **Select application**, select the *webapp1* application that registered when completing the prerequisites.
61+
1. For **Select reply url**, choose `https://jwt.ms`.
62+
1. Select **Run now** and sign up using an email address or a phone number.
63+
1. Select **Run now** once again and sign in with the same account to confirm that you have the correct configuration.
64+
65+
## Next steps
66+
67+
You can find the phone sign-up and sign-in custom policy starter pack (and other starter packs) on GitHub:
68+
69+
[Azure-Samples/active-directory-b2c-custom-policy-starterpack/scenarios/phone-number-passwordless][starter-pack-phone]
70+
71+
<!-- LINKS - External -->
72+
[starter-pack]: https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack
73+
[starter-pack-phone]: https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/tree/master/scenarios/phone-number-passwordless

0 commit comments

Comments
 (0)