Why Be Excited about Azure AD B2C?
Creating a tenant, configuring “Sign Up and Sign In” user flow, and digging into the JWT token.
Why Azure Active Directory B2C?
Because of the 50,000 MEOWs… what else?
Actually, those are MAUs, not MEOWs. Occasionally, the two get mixed up in my brain. It all started when the gray-haired neighbor’s cat jumped into my garden and asked for something to chew on.
For clarity’s sake, MAUs are not related to cats, unless they are. In the context of Azure AD B2C, they represent Monthly Active Users.
Imagine that each month you get 50,000 MAUs authenticating for free when you don’t have to worry about the accessibility of your identity server. And those are the active users. This doesn’t include the dormant ones who create a profile and forget about your site. The total number of free users in your active directory can be much larger, as you pay only for unique users who “jump into your garden” and actively authenticate after their number exceeds 50,000 per month. Subsequent authentications of the same users don’t cost you anything within a calendar month. Isn’t that exciting?
Comparing the Azure AD B2C free tier to a competing product from Auth0.com, which gives you only up to 7000 active monthly users for free, reveals that this is, indeed, a stunning offer from Microsoft. For many startups, it will take quite some time to cross the boundary of 50,000 MAUs per month.
If you are looking for a painless way to implement user sign-up and sign-in, read claims from a JSON web token (JWT), and next to the local account option also support Social Identity Providers, then Azure Active Directory B2C might be the right solution for your project.
As a bonus, you can easily change the look and feel of the provided templates by uploading custom HTML and CSS. You can store them in a Blob Storage container or on a static Web Site attached to your Azure storage account.
Want to experience a working demo of the “Sign Up and Sign In” user flow and see Azure Active Directory B2C authentication in action before you go through the configuration steps in this article? You can do that by signing up for my blog at danielloran.com. It happily runs on Azure using the techniques outlined below.
Which Social IDPs Are Supported?
As of this writing, Azure Active Directory B2C offers a straightforward way to configure Amazon, Facebook, GitHub, Google, LinkedIn, Microsoft, QQ, Twitter, WeChat, and Weibo. You can add any other provider, albeit with more effort.
Create an Azure AD B2C Tenant
When you select the name of your tenant, think about how many environments your project will have. I prefer to create one tenant per environment. For instance, my blog has two environments: development and production. A more complex project may also need a staging environment.
The Azure AD B2C tenant is hosted as a sub-domain of onmicrosoft.com. Therefore, you can claim the desired name for your tenant only if nobody else has it already.
Following are the steps to create an Azure AD B2C tenant for a production environment called fakesystem. You could follow the same procedure later to create another tenant for a development environment called fakesystemdev or similar.
On the dashboard, under “Azure services,” click on “Create a resource.” In the search box, enter “Azure Active Directory B2C.” Then press the “Create” button. You should now see a page that looks like this:
We will use both options available on this page in the order they appear. First, click on “Create a new Azure AD B2C Tenant.”
“Organization name” is what users will see in the verification e-mail sent during sign-up. When ready, hit “Review + create” and, finally, the “Create” button.
Wait until the tenant has been created. You will then receive a notification offering to navigate to your tenant. Avoid the urge to click on it. It’s too early to navigate to the new tenant because it’s not linked to any subscription yet. In this state, you can’t do anything useful with it. If you couldn’t resist the urge and navigated to the new tenant, then you should switch back to your “Default Directory” as described in the “Switch between tenants” section further in this article. Otherwise, click on the “Create new B2C Tenant or Link to existing Tenant” on top:
Link the Tenant to Your Subscription
You should now see the page you encountered before. This time, select the second option: “Link an existing Azure AD B2C Tenant to my Azure subscription.”
Select or create a resource group to organize all your related resources together. Then hit “Create.”
Switch between Tenants
So far, we have created a tenant and linked it to our Azure subscription without switching the active directory. Because we finished all the preparations, we can now switch the directory to a newly created tenant. One way to do that is by clicking on the “Directory + Subscription” icon in the top menu.
Make sure you can see all the tenants by clicking on “All Directories.” The newly created tenant should appear there, as shown below.
You can now select the tenant to which you want to navigate. If you don’t see it in the list, refresh the page and reopen this menu. Sometimes it takes a while for things to propagate on Azure.
An Alternative Way to Navigate to Your Tenant
If you ever get lost inside Azure, you can always find your tenant in “All resources” by resource group. When taking this route, you will encounter yet another layout in which you need to click on the “Azure AD B2C Settings fakesystem.onmicrosoft.com” icon to navigate to your tenant.
Register Your Application
Once you are inside the fakesystem tenant, in the left menu, select “App registrations,” then “New registration.”
You can now do the following:
- Enter a display name for your application (e.g., fakesystem-web).
- Under “Who can use this application or access this API?”, select “Accounts in any identity provider or organizational directory (for authenticating users with user flows).” This option will make it possible to use all identity providers, inclusive social IDPs.
- Set “Redirect URI” to “Web” and temporarily use the value https://jwt.ms. The tool available via this URL makes it possible to look inside the generated JWT token without hosting the application to which it will be returned in a more practical scenario. This way, you can easily test the flow.
When done, press “Register.”
Configure Authentication
After your app is registered, select “Authentication” in the left menu. This is the place where you can change “Redirect URIs” or add new ones. To implement OAuth Implicit Flow, select both “Access tokens” and “ID tokens” under the “Implicit grant” section. What you select here will find its way into the JWT token. Don’t forget to “Save” your changes.
To go back to the main tenant page, use the “Azure AD B2C” link in the “breadcrumb trail” at the top.
Setup of the “Sign Up and Sign In” User Flow
After you return to the main tenant page, select “User flows” under “Policies,” then “New user flow.” In the subsequent page, select the “Sign up and sign in” user flow type and the “Recommended” version. Then hit “Create.”
After you create the user flow, you need to give it a policy name. It’s recommended that you select a short name here because, as you will notice later, your policy name will become part of the endpoint URLs and the JWT token, which you want to keep as light as possible, especially if you pay for the egress traffic. In your application, you may want to know what flow produced the token to trigger a specific logic. By default, the policy name is included in the token and can be accessed via the “tfp” claim. We will see later how this works.
Let’s enter the name “susi” — a short version of “Sign Up and Sign In.” Notice that Azure AD B2C will always attach a prefix “B2C_1_” to it. So, the full policy name will be B2C_1_susi.
Under “Identity providers,” select “Email signup” so that users can register after they verify their e-mail address. Azure AD B2C will store user accounts locally. You can always browse those accounts via the “Users” left-menu option on your main tenant page.
If you don’t modify anything in the “Multifactor authentication” section and leave all the default values as they are, then MFA will be disabled for user sign-ups.
The section “User attributes and token claims” is where you define what information to collect from users during the sign-up (see the “Collect attribute” column) and what to return to your application inside the JWT token (see the “Return claim” column). Click “Show more…” to change those attributes.
Each application may have specific needs in terms of which attributes to collect from users and which claims to request from identity providers. If you intend to add a sign-up via social IDPs at some point, then at the bare minimum you will need the following return claims: “Display Name,” “Email Addresses,” and “User is new.” You can always change those attributes later, after experimenting with them.
Avoid Unpleasant Surprises
Asking for an attribute doesn’t always materialize in the receipt of it from all IDPs. It’s a good practice to test the flow and get a sense of which attributes are in the token with each IDP you intend to support.
For example, if you add support for Facebook and Twitter, you can’t always rely on getting user e-mail inside the JWT token, because it’s possible to create an account on those platforms using a mobile phone and without providing an e-mail. As a result, many sites that require user e-mails avoid social IDPs that can’t be guaranteed to always return this claim. Be aware of the fact that if an attribute doesn’t have a value, Azure AD B2C will not include it in the token.
After specifying user attributes and token claims, you can hit the “Create” button.
The next page should look like this:
Click on the B2C_1_susi link.
If you ever need to change user attributes and application claims, this is where you can do it. But, for now, let’s just “Run user flow” to test it.
Endpoint Evaluation
Because OAuth is very heavy on details, and troubleshooting errors can be a tedious process, it’s usually a good practice to get familiar with what goes into the endpoint URLs. When things go wrong, as they occasionally do, you will most likely need to check the redirect URLs and the parameters you pass to Azure AD B2C from the client application.
The first important endpoint to visit and check appears at the top: https://fakesystem.b2clogin.com/fakesystem.onmicrosoft.com/v2.0/.well-known/openid-configuration?p=B2C_1_susi
This is where you will find the “issuer” id and other endpoints required to configure OAuth in your client application so that it can connect to Azure AD B2C.
Notice that our policy name is attached to all endpoints (except the “issuer” one) and appears in lowercase letters. Case sensitivity is important when referencing a policy, so in your client application, use the same casing as below.
{
"issuer": "https://fakesystem.b2clogin.com/4bd4d349-4cc8-4b57-83a8-3f0430842e5e/v2.0/",
"authorization_endpoint": "https://fakesystem.b2clogin.com/fakesystem.onmicrosoft.com/oauth2/v2.0/authorize?p=b2c_1_susi",
"token_endpoint": "https://fakesystem.b2clogin.com/fakesystem.onmicrosoft.com/oauth2/v2.0/token?p=b2c_1_susi",
"end_session_endpoint": "https://fakesystem.b2clogin.com/fakesystem.onmicrosoft.com/oauth2/v2.0/logout?p=b2c_1_susi",
"jwks_uri": "https://fakesystem.b2clogin.com/fakesystem.onmicrosoft.com/discovery/v2.0/keys?p=b2c_1_susi",
"response_modes_supported": [
"query",
"fragment",
"form_post"
],
"response_types_supported": [
"code",
"code id_token",
"code token",
"code id_token token",
"id_token",
"id_token token",
"token",
"token id_token"
],
"scopes_supported": [
"openid"
],
"subject_types_supported": [
"pairwise"
],
"id_token_signing_alg_values_supported": [
"RS256"
],
"token_endpoint_auth_methods_supported": [
"client_secret_post",
"client_secret_basic"
],
"claims_supported": [
"name",
"emails",
"newUser",
"sub",
"idp",
"tfp",
"iss",
"iat",
"exp",
"aud",
"acr",
"nonce",
"auth_time"
]
}The “Run User Flow” Endpoint
Notice that the query string of “Run user flow endpoint” has the “B2C_1_susi” policy name, the client_id of the application we created earlier, and the redirect_uri we specified.
Run User Flow
It’s about time to click the “Run user flow” button and see the results of all those configuration efforts.
This will take you to the page where you can sign in, or if you don’t have an account yet, sign up for the application. If you don’t like the blue background or the styling of this page, don’t worry, as there is a way to customize it later. Click on “Sign up now.”
Enter your email address, then press “Send verification code.” Check your e-mail, enter the received verification code, and hit the “Verify code” button.
By default, strong password complexity is enabled. You can change this in B2C_1_susi > Settings > Properties > Password complexity.
Look Inside the Decoded Token
If everything went well, you should see the returned claims inside the decoded token. The “iss” claim is the issuer endpoint of your tenant. The “sub” claim is by default filled with Object Id, which uniquely identifies the user. This value is immutable and cannot be reassigned or reused. You can safely store it in a database to assert information about the user of your application. The “emails” array will contain the sign-up e-mail. The “tfp” claim has the name of the user flow policy via which we got the token.
By now, you should have noticed that we also asked for “Display Name” but it’s not included in the token. This is because we didn’t configure collection for this user attribute. Because Azure AD B2C never collected this attribute, it can’t return it in the token. How, then, is it useful to us? If you add a social identity provider to the mix later, this value will be filled by a social provider and added to the token.
If you switch to the “Claims” tab, you can see additional details about each claim in the token.
Administer Your Users
From the main tenant page, navigate to “Users.”
You should see two users: a user that created the tenant and a user that signed up into the application with an “unknown” name because we didn’t configure to collect “Display Name,” only to return it from other ISPs if available. You can now click on the “unknown” user and compare “Object Id” under the “Identity” section to the “sub” claim inside the JWT token. The value should be the same.
Finally
If you followed all the steps in this article, then creating an Azure AD B2C tenant and configuring the “Sign Up and Sign In” user flow shouldn’t be a mystery to you.
As you have seen, there is a way to administer your users in the Azure portal. If you prefer to do it in your application, check out the MS Graph API.
Originally published at https://danielloran.com.
You are welcome to sign up to my blog at danielloran.com so you won’t miss any future updates. I may send out exclusive goodies from time to time.
