Developing an AAD B2C app with MSAL Python

This page is currently a preview. The actual feature in MSAL Python has NOT been implemented yet.

Use MSAL Python to work with B2C

Summary

You can use MSAL Python to sign-in users with social identities, acquire token, customize the sign-in experience, by using Azure AD B2C. AAD B2C is built around the notion of User Flows (formerly known as policies). In MSAL Python, specifying a user flow translates to providing an authority.

• When you instantiate the client application, you need to specify the user flow in authority as https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{user_flow}. And then every usual acquire_token_by_xyz(...) would work with that user flow. There is no API surface difference between B2C and non-B2C scenarios.
• Some user flows are essentially customized user experience, such as Edit Profile user flow or Reset Password user flow. You create a PublicClientApplication with the authority containing that {user_flow}, and then call the get_authorization_request_url(...) accordingly.

Authority for a B2C tenant and user flow

The authority to use is https://{tenant_name}.b2clogin.com/{tenant_name}.onmicrosoft.com/{user_flow} where:

• tenant_name is the name of the Azure AD B2C tenant, such as "contoso"
• user_flow is the name of the user flow to apply (for instance you might have "b2c_1_susi" for sign-in/sign-up).

When building the application, you need to provide, as usual, the authority, built as above

app = msal.PublicClientApplication(  # Or ConfidentialClientApplication(...)
    "your_client_id",
    authority="https://contoso.b2clogin.com/contoso.onmicrosoft.com/b2c_1_susi",
    ...)

You may also use your own customized domain name, so that your authority would look like "https://contoso.com/{tenant_name}.onmicrosoft.com/{user_flow}".

Under the hood, MSAL Python will automatically adjust the validate_authority check behavior for all B2C domains. So that you do not have to do anything extra.

Acquiring a token

Acquiring a token for an Azure AD B2C protected API, based on the user flow already provided as part of the authority, are exactly the same as what you would do in non-B2C scenario.

app.acquire_token_by_xyz(...)  # Same as in non-B2C scenarios

There is no need to filter accounts by user flow, as long as you are following a pattern of "create different msal app for different user flow" (because the B2C user flow is designed to behave like an isolated authority). In practice, you will still typically reuse same MSAL app and its token cache for the SignIn user flow, and only create new one-time MSAL app when invoking EditProfile or ResetPassword user flows, whose returned token (if any) would not be useful anyway.

Example of EditProfile and ResetPassword user flows

When you want to provide a customized experience when your B2C end users edit their profile or reset password, you want to apply the B2C EditProfile user flow, or Reset Password user flow, respectively. The way to do this, is by creating an MSAL app instance with the specific authority for that user flow, and then call get_authorization_request_url(...).

def profile():  # This is a web app controller using Flask framework
    app = _build_msal_app(authority=app_config.B2C_PROFILE_AUTHORITY)
    return redirect(app.get_authorization_request_url([], state=..., redirect_uri=...))

Resource Owner Password Credentials (ROPC) With B2C

There is still no API difference here between B2C and non-B2C scenario. The following content serves as a mini-tutorial.

• In your AzureAD B2C tenant, create a new user flow and select Sign in using ROPC. This will enable the ROPC user flow for your tenant. See Configure the resource owner password credentials flow for more details.
• Once you create the msal instance with the authority which contains the ROPC user flow, the acquire_token_by_username_password(...) would work as usual.
• Limitations: This only works for local accounts (where you register with B2C using an email or username). This flow does not work if federating to any of the IdPs supported by B2C (Facebook, Google, etc...).
• Normal caveats on ROPC flow still applies. Please see this wiki page.

Caching with B2C in MSAL Python

Known issue with Azure B2C:

MSAL Python token cache usage pattern starts with querying all existing accounts by get_accounts(...), which supports a username parameter as filter. That username data is populated by a preferred_username claim inside the ID Token.

By default, that claim is missing in many of the Azure AD B2C scenarios.

The customer impact is that when trying to display the accounts, their username field would be empty. This may not bother you, if you are using Auth Code flow in your web app, and dealing with only one account per user. But if you are using ROPC flow and feels you already know the end user's username, accounts = app.get_accounts(username="[email protected]") would still give you an empty result, because "[email protected]" won't match "".

The workaround is to customize your B2C user flow to populate and return a preferred_username claim, or simply call your app.get_accounts() without a specific username parameter.

Samples illustrating acquiring tokens interactively with MSAL Python for B2C applications

Sample	Platform	Description
Microsoft Identity Python Web App	All platforms supporting Python	A web app showcasing how to use MSAL Python to authenticate users via Azure Active Directory B2C, and access a Web API with the resulting tokens.