Skip to content

Commit 47eb455

Browse files
DennisLee-DennisLeeDennisLee-DennisLee
committed
Merge branch 'master' of https://github.com/MicrosoftDocs/azure-docs-pr into v-dele-1645361-011
2 parents bff8a87 + a5b8133 commit 47eb455

File tree

169 files changed

+2503
-1227
lines changed

Some content is hidden

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

169 files changed

+2503
-1227
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: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
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+
63+
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.
64+
65+
The **OutputClaimsTransformations** element may contain a collection of **OutputClaimsTransformation** elements that are used to modify the output claims or generate new ones.
66+
67+
### Metadata
68+
69+
| Attribute | Required | Description |
70+
| --------- | -------- | ----------- |
71+
| Operation | Yes | Must be **OneWaySMS**. |
72+
| UserMessageIfInvalidFormat | No | Custom error message if the phone number provided is not a valid phone number |
73+
| UserMessageIfCouldntSendSms | No | Custom error message if the phone number provided does not accept SMS |
74+
| UserMessageIfServerError | No | Custom error message if the server has encountered an internal error |
75+
76+
### Return an error message
77+
78+
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:
79+
80+
```XML
81+
<Item Key="en.UserMessageIfInvalidFormat">Invalid phone number.</Item>
82+
```
83+
84+
### Example: send an SMS
85+
86+
The following example shows an Azure MFA technical profile that is used to send a code via SMS.
87+
88+
```XML
89+
<TechnicalProfile Id="AzureMfa-SendSms">
90+
<DisplayName>Send Sms</DisplayName>
91+
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
92+
<Metadata>
93+
<Item Key="Operation">OneWaySMS</Item>
94+
</Metadata>
95+
<InputClaimsTransformations>
96+
<InputClaimsTransformation ReferenceId="CombinePhoneAndCountryCode" />
97+
<InputClaimsTransformation ReferenceId="ConvertStringToPhoneNumber" />
98+
</InputClaimsTransformations>
99+
<InputClaims>
100+
<InputClaim ClaimTypeReferenceId="userPrincipalName" />
101+
<InputClaim ClaimTypeReferenceId="fullPhoneNumber" PartnerClaimType="phoneNumber" />
102+
</InputClaims>
103+
</TechnicalProfile>
104+
```
105+
106+
## Verify code
107+
108+
The second mode of this technical profile is to verify a code. The following options can be configured for this mode.
109+
110+
### Input claims
111+
112+
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.
113+
114+
| ClaimReferenceId | Required | Description |
115+
| --------- | -------- | ----------- | ----------- |
116+
| phoneNumber| Yes | Same phone number as previously used to send a code. It is also used to locate a phone verification session. |
117+
| verificationCode | Yes | The verification code provided by the user to be verified |
118+
119+
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.
120+
121+
### Output claims
122+
123+
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.
124+
125+
The **OutputClaimsTransformations** element may contain a collection of **OutputClaimsTransformation** elements that are used to modify the output claims or generate new ones.
126+
127+
## Metadata
128+
129+
| Attribute | Required | Description |
130+
| --------- | -------- | ----------- |
131+
| Operation | Yes | Must be **Verify** |
132+
| UserMessageIfInvalidFormat | No | Custom error message if the phone number provided is not a valid phone number |
133+
| UserMessageIfWrongCodeEntered | No | Custom error message if the code entered for verification is wrong |
134+
| UserMessageIfMaxAllowedCodeRetryReached | No | Custom error message if the user has attempted a verification code too many times |
135+
| UserMessageIfThrottled | No | Custom error message if the user is throttled |
136+
| UserMessageIfServerError | No | Custom error message if the server has encountered an internal error |
137+
138+
### Return an error message
139+
140+
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:
141+
142+
```XML
143+
<Item Key="en.UserMessageIfWrongCodeEntered">Wrong code has been entered.</Item>
144+
```
145+
146+
### Example: verify a code
147+
148+
The following example shows an Azure MFA technical profile used to verify the code.
149+
150+
```XML
151+
<TechnicalProfile Id="AzureMfa-VerifySms">
152+
<DisplayName>Verify Sms</DisplayName>
153+
<Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.AzureMfaProtocolProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
154+
<Metadata>
155+
<Item Key="Operation">Verify</Item>
156+
</Metadata>
157+
<InputClaims>
158+
<InputClaim ClaimTypeReferenceId="phoneNumber" PartnerClaimType="phoneNumber" />
159+
<InputClaim ClaimTypeReferenceId="verificationCode" />
160+
</InputClaims>
161+
</TechnicalProfile>
162+
```

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

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
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 following directory:
38+
39+
`active-directory-b2c-custom-policy-starterpack/scenarios/`**`phone-number-passwordless`**
40+
41+
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`.
42+
43+
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). In this case, update `/phone-number-passwordless/`**`Phone_Email_Base.xml`** with the **Application (client) IDs** of the two applications you registered when completing the prerequisites, *IdentityExperienceFramework* and *ProxyIdentityExperienceFramework*.
44+
45+
## Upload the policy files
46+
47+
1. Sign in to the [Azure portal](https://portal.azure.com) and navigate to your Azure AD B2C tenant.
48+
1. Under **Policies**, select **Identity Experience Framework**.
49+
1. Select **Upload custom policy**.
50+
1. Upload the policy files in the following order:
51+
1. *Phone_Email_Base.xml*
52+
1. *SignUpOrSignInWithPhone.xml*
53+
1. *SignUpOrSignInWithPhoneOrEmail.xml*
54+
1. *ProfileEditPhoneOnly.xml*
55+
1. *ProfileEditPhoneEmail.xml*
56+
1. *ChangePhoneNumber.xml*
57+
1. *PasswordResetEmail.xml*
58+
59+
As you upload each file, Azure adds the prefix `B2C_1A_`.
60+
61+
## Test the custom policy
62+
63+
1. Under **Custom policies**, select **B2C_1A_SignUpOrSignInWithPhoneOrEmail**.
64+
1. Under **Select application**, select the *webapp1* application that you registered when completing the prerequisites.
65+
1. For **Select reply url**, choose `https://jwt.ms`.
66+
1. Select **Run now** and sign up using an email address or a phone number.
67+
1. Select **Run now** once again and sign in with the same account to confirm that you have the correct configuration.
68+
69+
## Next steps
70+
71+
You can find the phone sign-up and sign-in custom policy starter pack (and other starter packs) on GitHub:
72+
73+
[Azure-Samples/active-directory-b2c-custom-policy-starterpack/scenarios/phone-number-passwordless][starter-pack-phone]
74+
75+
The starter pack policy files use multi-factor authentication technical profiles and phone number claims transformations:
76+
77+
* [Define an Azure Multi-Factor Authentication technical profile](multi-factor-auth-technical-profile.md)
78+
* [Define phone number claims transformations](phone-number-claims-transformations.md)
79+
80+
<!-- LINKS - External -->
81+
[starter-pack]: https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack
82+
[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)