Quick overview of how to setup Azure AD B2C (AADB2C)

Posted on Jul 11, 2022

Azure
ADB2C

Note: This article was written a while ago and may contain outdated information. Please verify the details before relying on it. If I express opinions or recommendations, they might not reflect my current views. For this reason, I recommend checking for more recent articles on the same topic.

Azure ADB2C (or: AADB2C) is a whitelabel authentication solution by Microsoft Azure.

You can use AADB2C to implement a whole authentication flow within your Azure Cloud subscription with your own branding.

This series describes the components of Azure ADB2C, which resources you need and how they do work together.

How Azure ADB2C works

AADB2C acts a central authority for your web/mobile applications or API.

You can bind many identity providers like Facebook, Google, LinkedIN or E-Mail, Phone Call, SMS, … with ADB2C. All that without any implementation of an API!

This is done by the Identity Experience Framework (IEF) which helps with claiming the needed data by your user and the communication with the identity providers. Also, the Identity Experience Framework is processing the claims and manages the profiles.

On top of the IEF you as a developer are builiding the Trust Framework Policies which describe the needed data and the authentication/registration flow. This flows are called User Journeys.

The Relying Party Application is the application which calls the IEF and Framework policies. This can be a web or mobile app or an API.

The basics

You need to upload a configuration of the claims which you want to retrieve by your user. With that you can configure:

Registration Pages
Login Pages
MFA Login Pages
User setting Pages and whatever you want!

You do this via template files which are configured via XML.

An example can be found within the Azure ADB2C starter pack.

Some of the important ones are described in the following sections. But beside of that you can also check the Microsoft documentation of the TrustFrameworkPolicy for the properties.

Beware! You’ll see a lot of XML. And you don’t need to understand it fully now. You’ll understand it as soon as you will use it. Just check out the syntax and that you have some links for the docs.

ClaimsSchema

A ClaimsSchema defines the claim types that you will need in your policy. This can be for example the name, email address or phone number.

A ClaimsSchema element usually consists the ClaimTypes, like in the following example:

<BuildingBlocks>
    <ClaimsSchema>
        <ClaimType Id="username">
        <DisplayName>The username</DisplayName>
            <DataType>string</DataType>
            <DefaultPartnerClaimTypes>
            <Protocol Name="OAuth2" PartnerClaimType="tid" />
            <Protocol Name="OpenIdConnect" PartnerClaimType="tid" />
            <Protocol Name="SAML2" PartnerClaimType="http://schemas.microsoft.com/identity/claims/username" />
            </DefaultPartnerClaimTypes>
            <UserHelpText>The username of the user</UserHelpText>
        </ClaimType>
    </ClaimsSchema>
</BuildingBlocks>

Microsoft documentation of the ClaimsSchema

ClaimsTransformation

The ClaimsTransformation describes the manipulation of a Claim. A manipulation can be: Converting the data type, changing the format or setting a claim.

The following code shows the skeleton of a claim transformation:

<ClaimsTransformation Id="<identifier>" TransformationMethod="<method>">
  <InputClaims>
    ...
  </InputClaims>
  <InputParameters>
    ...
  </InputParameters>
  <OutputClaims>
    ...
  </OutputClaims>
</ClaimsTransformation>

You can see that it expects an identifier and a reference to a method. Then it needs the InputClaims which are the claim types which are taken as an input. The InputParameters are ther parameters which are provided as an input to the claims transformation. And the OutputClaims which describe the produced output claims after a transformation was invoked.

The available methods can be found in the Microsoft documentation

UserJourney

UserJourneys describe the way of the policy and which paths an user needs to go to fullfill the journey. In an UserJoruney the user will provide the claims for the trust framework.

One UserJoruney is represented by a sequence of OrchestrationSteps, like shown in the following example:

<TrustFrameworkPolicy  ...>
  ...
  <UserJourneys>
    <UserJourney Id="UserInfoJourney" DefaultCpimIssuerTechnicalProfileReferenceId="UserInfoIssuer">
      <Authorization>
        <AuthorizationTechnicalProfiles>
          <AuthorizationTechnicalProfile ReferenceId="UserInfoAuthorization" />
        </AuthorizationTechnicalProfiles>
      </Authorization>
      <OrchestrationSteps>
        <OrchestrationStep Order="1" Type="ClaimsExchange">
        </OrchestrationStep>
      </OrchestrationSteps>
    </UserJourney>
  </UserJourneys>
</TrustFrameworkPolicy>

Microsoft documentation of UserJoruneys

Make things work

However, these are just some of the components which the Trust Framework gives you for usage.

If you want to make the Policies work, you need a Reyling Party, which can be for example a web page. Azure ADB2C injects your configured templates into the HTML page.

For this you need to give it a *.html file which has the following div tag with the id="api" field:

<div id="api"></div>

The last step is to stick this HTML page with your user journeys. In Azure, you’ll upload the HTML-file to the Azure Blob Storage. Get the url.

In your policices make use of the ContentDefinitions and add a reference to this HTML-file!

      <ContentDefinition Id="api.signuporsignin">
        <LoadUri>YOUR_BLOBL_URL</LoadUri>
        <DataUri>urn:com:microsoft:aad:b2c:elements:selfasserted:1.1.0</DataUri>
        <Metadata>
          <Item Key="DisplayName">Signin!</Item>
        </Metadata>
        <LocalizedResourcesReferences MergeBehavior="Prepend">
          <LocalizedResourcesReference Language="en" LocalizedResourcesReferenceId="api.localaccountsignup.en" />
        </LocalizedResourcesReferences>
      </ContentDefinition>

How to set up Azure AD B2C

The following image shows the setup of your own policicies in ADB2C.

First, you create a new ADB2C tenant. ADB2C itself contains your registered applications, the IEF policies, the used identity providers (IdP) and your registered users.

You can upload your IEF-policies either manually or via Infrastructure as a Code (for example with terraform).

The same can be applied to your HTML pages. But in this case you upload it to a separate Blob storage.

The configuration of the policies is a task for itself. For most basic usages, you can use the ADB2C starter pack.

Conclusion

This should have give you a quick overview of how ADB2C works and an understanding for some common problems while setting up and changing your flow! You create own Policies and customize the UI with an HTML5 page, which lays in the Blob storage. To make it available, you need to seed the URL.

There are some more resources and things to show: For example how you can get a token by ADB2C and use it in your application or how to use the ADB2C API to create and edit users and create multi-tenancy in your application. This is the first step in this direction.