Agenda:
Introducing Custom Policies in Azure AD B2C
Custom Policy Components
Relying Party and User Journeys
Claims Definitions
Technical Profiles
Getting Started with Azure AD B2C Custom Policies
Azure AD B2C Webinar Series: Custom Policies Part 1
1. Azure AD B2C Webinar Series
Custom Policy Concepts
John Garland
VP Cloud Development & Instructor, Wintellect
Azure MVP, MCT, P-CSA
wintellect.com
@dotnetgator
Vinu Gunasekaran
Program Manager, Microsoft
3. Date Time (PDT) Topic
20-Apr
21-Apr
2-3 PM
8-9 AM
Identity Protocols – OIDC, OAuth2
Recording: https://aka.ms/B2CWebinarRecordings
27-Apr
28-Apr
2-3 PM
8-9 AM
B2C & App Integration (with MSAL)
Recording: https://aka.ms/B2CWebinarRecordings
4-May
5-May
2-3 PM
8-9 AM
Custom Policies Part 1: Concepts with Take-Home Lab
11-May
12-May
2-3 PM
8-9 AM
Custom Policies Part 2: Policy Walkthrough
18-May
19-May
2-3 PM
8-9 AM
Custom Policies Part 3: Troubleshooting
Calendar of Previous & Upcoming Sessions
4. Azure AD B2C Webinar Series
Custom Policy Concepts
John Garland
VP Cloud Development & Instructor, Wintellect
Azure MVP, MCT, P-CSA
wintellect.com
@dotnetgator
Vinu Gunasekaran
Program Manager, Microsoft
5. • Introducing Custom Policies in Azure AD B2C
• Custom Policy Components
• Relying Party and User Journeys
• Claims Definitions
• Technical Profiles
• Getting Started with Azure AD B2C Custom Policies
Agenda
Note – The content today assumes you are familiar with the pre-requisite material outlined in the
session description, including:
• What is Azure AD B2C
• Basic Azure AD B2C configuration and user flow creation
• Azure AD B2C Use Cases
Also, if you haven’t already, you may want to go back and watch the prior sessions in this series.
6. Recap:
Azure AD B2C policies
Issue a token
Read
user
profile
Create
an
account
Sign-Up
or Sign-
In
7. Types of policies
User flows
Built-in policies
Identity Experience Framework
Custom policies
8. BasePolicy Defines inheritance hierarchy among policy files.
BuildingBlocks Configures claims, transformations, content
definitions, and other policy features.
ClaimsProviders Defines items which obtain, modify, and validate
claims, expressed as units called Technical Profiles.
UserJourneys Defines the sequence of steps to be executed and
the conditions under which steps are invoked.
RelyingParty
Defines the behavior of the endpoint that is
exposed by the policy, including
which UserJourney is executed and which claims
are returned.
Policy Components
<TrustFrameworkPolicy xmlns=“…”
PolicySchemaVersion="0.3.0.0"
TenantId="YOUR_TENANT_NAME.
PolicyId="YOUR_POLICY_ID"
PublicPolicyUri="http://YOUR_TENA
_ID">
<BasePolicy>
<!-- Content -->
</BasePolicy>
<BuildingBlocks>
<!-- Content -->
</BuildingBlocks>
<ClaimsProviders>
<!-- Content -->
</ClaimsProviders>
<UserJourneys>
<!-- Content -->
</UserJourneys>
<RelyingParty>
<!-- Content -->
</RelyingParty>
</TrustFrameworkPolicy>
9. • A relying party application, such as a web, mobile, or desktop
application, calls the relying party (RP) policy.
• The RP policy configures the list of claims the relying party
application receives as part of the token that is issued.
• Multiple applications can use the same policy. All applications receive
the same token with claims and the user goes through the same user
journey.
• A single application can use multiple policies.
• A relying party policy, points to the user journey to be executed.
Relying party policy
10. • The explicit paths through which a policy allows a relying party
application to obtain the desired claims for a user.
• The user is taken through these paths to retrieve the claims that are
to be presented to the relying party.
• During the journey, Azure AD B2C exchanges claims with parties.
Sending input claims and receiving back output claims.
• Each user journey is a sequence of orchestration steps.
• Usually the last orchestration step issues the access token.
User journeys
11. Local
account
sign-in
REST API
Social
Identity
provider
MFA
Self asserted
(user input)
Application
insights
Directory
service
(AAD)
Relying party
application
Token
Claims
Claims
Claims
Claims
Claims
Claims
Claims
Claims bag (session)
Token
User
Journey
Step 1 Step 2 Step 3 Step 4 Step 5 Step 6 Step 7 Step 8
User journeys
12. 1
• Show the sign-in form, sign-up link and password reset
• If user provides credentials on screen, then login to local account
Validate credentials and return the user object Id
2
• If the user signed-in locally, skip this step
• Otherwise, register the user with a new local account
Create the account in the directory
3
• Read the desired attributes from the user directory for the current
user account
4
• Create a token with the desired claims collected from the current
activity and return the token to the calling app
Azure AD B2C directory services
Local account sign-up or sign-in user journey
13. • Store information about the user, such as first name, last name, or
display name.
• When the policy runs, Azure AD B2C sends and receives claims to and
from internal and external parties and then sends a set of claims to
your relying party application.
• Claims are used in these ways:
• Claims are read from, saved to, or updated in the Azure AD user profile.
• Claims can be received from an external identity provider.
• Claims are sent and/or received from calls to a custom REST API service.
• Data is collected as claims from users when they interact with User Interfaces
shown by policies.
Claims Definitions
14. Claims Definitions
• Id (required)
• Display name (required)
• Data type (required)
• User input type
• Mask
• User help text
• Restriction & Predicate validation
Text boxPasswordEmailDate pickerNumericDropdown list (single select)Checkbox list (multi select)Radio button (single select)ParagraphMaskUser help text
Self-asserted UX
Predicate validation
15. • Azure AD B2C supports many pre-built claims
• Given Name, Surname, City, Postal Code, Phone Number,
etc.
• Additional claims can be defined with Custom Claims
• Also known as Extension Property, Extension Attribute,
Custom Attribute, etc.
• Store additional user information like Loyalty Number,
external system ID, or status information like pending
migration.
• Use the syntax extension_name
Custom Claims
16. • Provides a framework with a built-in mechanism to communicate with
applications and identity providers via open standard protocols:
• OAuth1, OAuth2, OpenID Connect, SAML and WS-Fed
• Communicate with B2C parties, using internal Azure AD B2C protocols
• Azure Active Directory
• Phone factor provider
• Self-asserted
• Restful provider
• Session management
• Application insights
• Token issuer
• And more…
Technical profile
18. Claims bag
Technical profile
Input claims transformation
Input claims
Technical profile execution
Validation technical profiles
Output claims
Output Claims Transformations
Session manager
Identity provider
REST API
Azure AD directory service
MFA services
Issue a token
Self-asserted (user input)
Auditing
Technical profile
19. Self-asserted technical profile
• All interactions where a user is expected to provide input are
managed through self-asserted technical profiles.
• Configure input claims, claims to display/collect, and output claims
• User interface layout is defined by the Content Definition setting
• To customize the user interface, you specify a URL in the Content Definition
element with customized HTML content.
• Azure AD B2C runs code in your customer's browser that combines your
HTML file with Azure AD B2C HTML content
21. Validation technical profile
• A self-asserted technical profile may define one or more validation
technical profiles to be used to validate output claims.
• A validation technical profile is an ordinary technical profile from any
protocol, such as Azure Active Directory or a REST API.
• The validation technical profile returns output claims or returns an HTTP
error message
Examples:
• On Sign-in with a local account, Azure AD B2C invokes a validation technical profile
to validate the user’s credentials and return the user’s object id.
• On Sign-up, Azure AD B2C invokes a validation technical profile to check if the
account already exists. If it does not, the account is created, and the user object id is
returned.
• You can add additional validation technical profiles to check if a user exists in your
database or update your system when a user changes their account profile.
22. Examples of validation technical profile
Validation technical profile collection
Validate user credentials
Custom REST API
23. • Validate user input data
• Overwrite input claims
• Enrich user data by further integrating with corporate line-of-
business applications
• Run custom business logic
Call a REST API
24. Validate user input and enrich user data
PLACE A NEW ORDER
REVIEW EXISTING ORDER
WELCOME JAN!
IT’S APPLE
SEASON
THE MOST POPULAR VARIETIES
ARE
25. Relying Party policy
User Journey
Orchestration Step(s)
Technical
Profile(s)
if
Preconditions
Policy Execution
26. Getting Started with Azure AD B2C Custom Policies
https://docs.microsoft.com/azure/active-directory-b2c/custom-policy-get-started
• Create an Azure AD B2C tenant and link it to an Azure Subscription
• Define Signing and Encryption Keys to be used by your policies
• Register applications that allow you to sign in local accounts
• Retrieve values that are used to allow your policies to work with
Custom Claims
• If you are working with external identity providers (such as
Facebook), register an application with the identity provider
• Download the Custom Policy Starter Pack and update the policy
values
27. The Policy Starter Pack
Why a “starterpack”
• Common starting point
• Provides sample user journeys
• Structured for change management
• Maintained / Tested
Pack Use case
LocalAccounts Enables the use of local accounts only
SocialAccounts Social (or federated) accounts only
SocialAndLocalAccounts Both
SocialAndLocalAccountsWithMFA Adds Multi-Factor Authentication
29. • Create a custom policy that will:
• Allow new users to sign up or existing users to sign in
• Users will create credentials that are local to the application
• B2C user accounts should record a user’s Loyalty Number (grocery store
points club membership number)
• In order to keep the initial sign-up experience as simple as possible, the
Loyalty Number should be obtained progressively
• It is not collected when the user first signs up, but instead the policy should wait until
the user signs in a second time.
Exercise: Progressive Profiling
https://aka.ms/B2CWebinarLabs/
30. Please take a few minutes to complete the feedback survey,
and we'll prepare a few questions to discuss.
https://aka.ms/B2CTheoryPostCallSurvey/
Feedback and Q&A
31. Thank you!
Vinu Gunasekaran
Program Manager, Microsoft
John Garland
VP Cloud Development & Instructor, Wintellect
Azure MVP, MCT, P-CSA
wintellect.com
@dotnetgator
Hinweis der Redaktion
Green = “You are here”
Remaining sessions in blue.
Custom Policies Part 2 will focus on walking through the lab policy and reviewing the details involved in producing a real-world Azure AD B2C Custom Policy
Custom Policies Part 3 will discuss troubleshooting and other helpful techniques for working with Azure AD B2C custom policies
As we have discussed in the previous sessions, there are several common functions that applications use Azure AD B2C to accomplish. Applications integrate with Azure AD B2C by calling endpoints defined by policies or user flows, with each policy or user flow basically representing a unique identity server.
Azure AD B2C simplifies this process across all platforms - web, mobile, and desktop applications can use modern authentication standards exposed by an Azure AD B2C tenant. And the Microsoft Identity Platform provides libraries like the Microsoft Authentication Library (MSAL) that you can integrate into your application to simplify both the authentication process as well as token acquisition and management.
With Azure AD B2C, you can let your customers choose what identity to use to sign into your application, whether that be Social accounts (such as Facebook, Microsoft, Google, Amazon, or any other Social Identity provider), Enterprise accounts (such as ADFS, Salesforce, or even their company’s Azure AD tenant), or using new account-specific credentials known as local accounts
In the end, your application will allow the user to interact with policies configured in your Azure AD B2C tenant configuration, with the goal of having those policy endpoints return several different kinds of tokens to the calling application.
Azure AD B2C supports two kinds of policies – User-Flows, which are predefined built-in policies that you can quickly configure using the Azure Portal. They support several common identity needs, such as Sign-Up & Sign In with and without MFA, Profile Editing, and Self-Service Password Reset. They are customizable, allowing you to select the whether or not to include external Identity Providers, what information to collect from users, and what information to return in tokens. (We have seen these demonstrated in the previous sessions in this series.)
Azure Custom Policies allow you to go deeper in terms of the amount of configuration as well as the scenarios you may need to support.
With Azure AD B2C custom policy, you are not limited the sign-up or sign-in, password reset and edit profile. You can create any policy you would like.
Such as:
Link and unlink a social account to local or social account.
Policies that allows user to change the sign-in email address, or MFA phone number.
Invite a user to Azure AD B2C.
Validate user information with 3rd party services.
ROPC which is a none interactive flow, mostly use with mobile applications.
Or create a policy that runs just in time migration, allowing you to seamlessly migrate user accounts from a legacy identity solution to Azure AD B2C.
An Identity Experience Framework (IEF) policy is made up of several sections. You specify values in each section as well as reference elements from other sections in order to assemble the functionality that you want your policy to achieve. Custom policies are defined using one or more XML documents which you then upload to your Azure AD B2C tenant.
NOTE: The Policy “example” XML shown here is skeletal for illustration purposes. It might be better(?) to show a segment of a “real” XML file?
The Relying Party policy is another example of a policy that could be basic or custom.
This file executes a specific task, such as signing in, resetting a password, or editing a profile.
Now that you have a decent understanding on how Azure AD B2C manages claims and common policies, let’s switch gears and dive into the underlying technical profiles which acts as the backbone of Azure AD B2C policy.
User Journeys – that’s what we call it.
A user journey is defined by the business logic of what an end user goes through as the Azure AD B2C Identity Experience Framework processes the request. The user is taken through these paths to retrieve the claims that are to be presented to the relying party.
Each step has a defined type that specifies which step to be executed.
For example IDP selection - this lets the user select a list of identity providers (sign-in with local account, Facebook, Microsoft account, Twitter, Google, ect.)
Let’s say a user selects to sign-in with local account, there are orchestration step in which specifies the technical profile that validates the user credential and returns the user object Id. But when a user selects Facebook, the next orchestration step invokes the Facebook technical profile that takes the user to Facebook. Of course, last orchestration step type issues the token back to the application.
A user journey is set of orchestrated steps, that each one invokes a technical profile. In this example, we have 8 steps. But user may not run through all of them. Because a step may contain preconditions instructing the policy to skip to the next orchestration step, based on claim comparison.
This is very similar to an If and Else statement.
Let’s look at a few user journeys – starting with Local account sign-up or sign-in.
<<walk through points>
Let’s look at the elements used to assemble the User Journey steps. We’ll start the most fundamental element that we work with in Azure AD B2C policies – Claims. Claims are what we include in the tokens that are returned to the calling applications, but they’re also used in several other ways throughout the policy execution.
If you familiar with any programing language , a claim is resembled to variable. Just like a variable, it needs to be stored – and that’s exactly what Azure AD B2C can do with these values.
A claim should have at least following
Id An identifier that's used for the claim type. Other elements can use this identifier in the policy.
Display name - The title that's displayed to users on various screens. The value can be localized.
Data type The type of the claim. The data types of Boolean, date, date and time, int, long, string, string collection, and more.
If a claim is used in a self-asserted page, the claim may contain more information, such as:
User input type - The type of input control that should be available to the user when manually entering the claim data for the claim type. See the user input types defined later in this page.
Mask - An optional string of masking characters that can be applied when displaying the claim. For example, the phone number 324-232-4343 can be masked as XXX-XXX-4343.
User help text A description of the claim type that can be helpful for users to understand its purpose. The value can be localized.
Restriction - The value restrictions for this claim, such as a regular expression (Regex) or a list of acceptable values. The value can be localized.
Predicate validation reference - A reference to a predicate validations input element, that allows you to perform a validation process to ensure that only properly formed data is entered. For more information, see Predicates.
Here are some example of claims with a user interface
Azure AD B2C supports a long list of pre-built claims. These include user attributes such as Given Nam e and Surname (first and Last name), city, portal code, phone numbers and so on.
However, you may likely find that you want to store some information about a user account that is not included in these pre-defined user claims. To work with these kinds of additional information, Azure AD B2C supports Custom Claims (also sometimes known as Extension Properties, Extensions Attributes, Custom Attributes and so forth.) Custom Claims extend the schema of the user objects in the directory. Their definition is “attached” to an application object in the Microsoft Graph,
With Custom Claims, you can store and retrieve additional information about user accounts in the underlying Azure AD data store, including business specific values like Loyalty Numbers, IDs for user records in external 3rd party systems, or user status information like “the user is in the middle of being migrated from a legacy identity system.”
When you work with a custom claim, you will refer to it from your Azure AD B2C custom policy by the value name, prefixed with the phrase “extension_”. This allows the Identity Experience Framework runtime locate the registered value and the corresponding claim that is stored with the user’s account record.
Note - Built-in attribute listing: https://docs.microsoft.com/en-us/azure/active-directory-b2c/user-profile-attributes
Now that you have a decent understanding on how Azure AD B2C manages claims and common policies, let’s switch gears and dive into the underlying technical profiles which acts as the backbone of Azure AD B2C policies.
All the interactions that occur in User Journey steps are done via technical profiles. You can think of Technical profiles as the functions in your policies.
Technical Profiles can:
Accept input parameters from a partner or Azure AD B2C – also known as “input claims”
Execute some functionality – each type of Technical Profile has different functionality that it can execute
And return some values – what are called “output claims”
All types of technical profiles share the same core concepts:
Azure AD B2C reads a set of claims from the Claims Bag, runs claims transformations, and communicates with the configured party, such as an identity provider, REST API, or Azure AD directory services.
After the process finishes, the technical profile returns some number of claims as output claims and may also run one or more output claims transformations.
Regardless of the party the technical profile interacts with, after any claims transformation is executed, the output claims from the technical profile are immediately stored in the claims bag.
If we look back to the diagram, the communication with those parties is done through technical profiles. A technical profile is responsible to interact with the user, federates with open Id connect, OAuth2, SAML identity providers, call a REST API and so on.
Illustrated another way, all of the technical profiles types share the same concept. Azure AD B2C reads the claims from the claims bag, sends input claims, runs claims transformations, and communicates with the configured party, such as an identity provider, REST API, or Azure AD directory services.
After the process finishes, the technical profile returns the output claims and may run output claims transformations.
Regardless of the party the technical profile interacts with, after any claims transformation is executed, the output claims from the technical profile are immediately stored in the claims bag.
If broken down in each one of the components, you can see there are 7 primary steps in order to create a session. This diagram shows how a technical profile is processed. Regardless of which party the technical profile interacts with, after any technical profile is executed, the output claims from the technical profile are immediately stored in the claims bag.
Let’s quickly walk through the steps:
Step #1 - input claims transformation
Technical profiles allow you to run an input claims transformation. Transformations allow you to set or alter claims before the technical profile is executed.
Step #2 - input claims
For some technical profiles, you may need to specify a set of input claims. For example, when calling a REST API, input claims are used to specify the list of claims to be sent to the REST service. When collecting information from the user, input claims are used to pre-fill the claims on the screed (commonly used in edit profile policy). When reading or updating a user profile, input claim are used to specify the stored user unique id to work with, such as the user objectId, sign-in name, or user principal name.
Step #3 - technical profile execution
The technical profile executes the procedure. For example:
Take the user to a social identity provider to complete the sign-in. After successful sign-in, the user is returned back to Azure AD B2C and the technical profile execution continues to the next step
Call a REST API while sending parameters as input claims and getting information back as output claims.
Create or update the user account.
Sending and verifying an MFA text message.
Step #4 - validation technical profile
For a technical profile that present user interfaces (known as self-asserted technical profiles – these will be reviewed shortly), you can call an input validation technical profile. The validation technical profile validates the data provided by the user and may return an error message depending on the validity of the input; it may also optionally return one or more output claims. For example, when a user sign-in with a local account, Azure AD B2C calls a validation technical profile to verify the entered credentials. As another example, before Azure AD B2C creates a new account it checks whether the user already exists in the directory services.
Additionally:
You can configure input validation on the claim level, using restrictions and preconditions to determine if the validation step should run.
With validation technical profiles, you can call a REST API technical profile, adding your own business logic to the policy.
Step #5 - output claims
Claims to be returned to the claims bag are indicated. You can then use those claims in subsequent orchestration steps or output claims transformations.
Step #6 - output claims transformations
Like input claims transformations, a technical profile may contain a list of output claims transformation to be executed, resulting in additional being returned to the claims bag. For example when signing-in with a Facebook account, the technical profile that communicates with Facebook reads the Facebook user unique identifier and runs a claims transformation to create an Azure AD B2C user principal name and an Azure AD B2C social account unique identifier, which is a combination of the user id and Facebook provider name. This is then stored in the Claims Bag for later use.
Step #7 - session management
A technical profile may contain a reference to a session management technical profile that is responsible for the management of user SSO
The idea is to showcase that you can use self-asserted technical profiles to collect data from the users during their journeys, and you can configure the look and feel to match your needs and brand.
NOTE: Yuck. Need to perhaps have a few different input types – PWD reset, MFA, Profile Edit, etc. And need help finding someone with an eye for laying this out better.
Another example of an Azure AD B2C Technical Profile is the REST Technical Profile. This Technical Profile lets you make calls to an HTTP endpoint from within your policy’s execution.
Calls to external HTTP endpoints can be useful for several reasons:
Validate user input data: This action prevents malformed data from persisting into Azure AD. If the value from the user is not valid, your RESTful service returns an error message that instructs the user to provide an entry. For example, you can verify that the email address provided by the user exists in your customer's database.
Overwrite input claims: For example, if a user enters the first name in all lowercase or all uppercase letters, you can format the name with only the first letter capitalized.
Enrich user data by further integrating with corporate line-of-business applications: Your RESTful service can receive the user's email address, query the customer's database, and return the user's loyalty number to Azure AD B2C. The return claims can be stored in the user's Azure AD account, evaluated in the next Orchestration Steps, or included in the access token.
Run custom business logic: You can send push notifications, update corporate databases, run a user migration process, manage permissions, audit databases, and perform other actions
Validation technical profile: Calls to a REST Technical Profile very often happen within the validation technical profile of a Self-asserted technical profile. The validation technical profile validates the user-provided data before the user journey moves forward. With the validation technical profile, you can:
Send input claims.
Validate the input claims and return custom error messages.
Send back output claims.
Let’s put these concepts together -
Your application calls a relying party policy. The relying party policy specifies which user journey to execute
A user journey defines the business logic steps for the user’s experience.
Each user journey is made up of a set of orchestration steps. These steps in turn performs a series of actions in the indicated sequence.
The orchestration steps will evaluate “Preconditions” which will determine if step’s Technical Profile will be run or not.
A technical profile provides a framework with a built-in mechanism to communicate with different types of parties, which in turn may gather, modify, and/or store one or more claims.
Each starter pack in the following list contains the smallest number of technical profiles and user journeys needed to achieve the scenarios described:
LocalAccounts- Enables the use of local accounts only.
SocialAccounts- Enables the use of social (or federated) accounts only.
SocialAndLocalAccounts - Enables both the use of local accounts and social accounts.
SocialAndLocalAccountsWithMFA - Enables social, local, and Multi-Factor Authentication options.
The starterpack is ready to use. We teach you the details so you are empowered to make your own changes to accommodate your own business requirements.
An Azure AD B2C policy very much follows an inheritance model – one policy taking on some of the values of the previous tiered policy. This tiered system allows to make additional changes to underlying policies without impacting the base policy. This allows you to scale your design without impact other work that you have created and of course, add additional policies to leverage existing work.
Let’s look at a relying party application (at the bottom of the diagram). It calls the Relying Party policy file to execute a specific task to initiate the sign-in flow.
The Identity Experience Framework in Azure AD B2C adds all of the elements first from the Base file, and then from the Extensions file, and finally from the RP policy file to assemble the current policy in effect. Elements of the same type and name in the RP file override those elements in the Extensions, and Extensions overrides Base.
As described in the diagram, your application always call the relying party policy. You can think of the relying party policy as Azure AD B2C authorization and token endpoints
The child policy at any level can inherit from the parent policy and extend it by adding new elements or overriding some of the elements.
There is no limit on the number of levels.
You and add more levels. For example, you can have an extension file that contains most of your functionality, then add additional extension per application, which contains the customization for this application. Then a set of relying party policies for each application extension
