🪢Connect Azure AD

This guide provides a step-by-step walkthrough for integrating Microsoft Azure Active Directory (AD) as an identity provider with Blockbrain Auth, streamlining the registration and login experience.

In the Blockbrain Auth system, you can connect an Identity Provider (IdP) like Azure AD to your tenant instance.

Azure AD Configuration

You need to have access to an Azure AD Tenant. If you do not yet have one follow this guide from Microsoft to create one for free.

Register a new client

Browse to the App registration menus create dialog to create a new app.
Give the application a name and choose who should be able to login (Single-Tenant, Multi-Tenant, Personal Accounts, etc.) This setting will also have an impact on how to configure the provider later on in Blockbrain Auth.
Choose "Web" in the redirect uri field and add the URL: https://auth.theblockbrain.ai/ui/login/login/externalidp/callback
Save the Application (client) ID and the Directory (tenant) ID from the detail page

Add client secret

Generate a new client secret to authenticate your user.

Click on client credentials on the detail page of the application or use the menu "Certificates & secrets"
Click on "+ New client secret" and enter a description and an expiry date, add the secret afterwards
Copy the value of the secret and store it in a safe place (Password Manager) for future usage. You will not be able to see the value again in Azure in the future.

If you lose your secret or if the secret is expired, you need to create a new secret again.

Token configuration

To allow Blockbrain Auth to get the information from the authenticating user you have to configure what kind of optional claims should be returned in the token.

Click on Token configuration in the side menu
Click on "+ Add optional claim"
Add email, family_name, given_name and preferred_username to the ID token

API permissions

To be able to get all the information that Blockbrain Auth needs, you have to configure the correct permissions.

Go to "API permissions" in the side menu
Make sure the permissions include "Microsoft Graph": email, profile and User.Read

Other permissions granted

OpenID authorization is essential for enabling the OpenID Connect protocol. This protocol is particularly important for managing user logins and issuing ID tokens in applications.

In the context of app registration, 'other permissions' refer to the specific access rights or 'scopes' required by an application. These Scopes determine what data and features the application can access on behalf of the user.

User Consent: On the user's first login, they will be prompted to grant these permissions. This step is crucial for ensuring user agreement and security compliance. Depending on your Organization setup, admin consent might be needed.
After the consent was fulfilled, the permissions will be active and listed in the App Registration - Authentication and signin is now possible, the application has the necessary access rights.
- The "Other permissions granted" should include "Microsoft Graph: openid"

Blockbrain Auth Configuration

Ensure External IdP allowed

You can configure the login policy in your organization in Blockbrain Auth. Choose your organization in the menu and go to https://auth.theblockbrain.ai/ui/console/org-settings?id=login

Go to the Settings
Modify your login policy in the menu "Login Behavior and Security"
Enable the attribute "External IDP allowed"

Add Azure AD Provider

Go to the settings page of your instance or organization and choose "Identity Providers".

In the table you can see all the providers you have configured. Also, you see all provider templates that are available.

Now, Select the "Microsoft" Provider template.

The Microsoft template has everything you need preconfigured. You only have to add the Client ID and secret, you have created in the Azure steps before.

You can configure the following settings if you like, a useful default will be filled if you don't change anything:

Scopes: The scopes define which scopes will be sent to the provider, openid, profile, and email are prefilled. This information will be taken to create/update the user within Blockbrain Auth. Make sure to also add User.Read. Blockbrain Auth ensures that at least openid and User.Read scopes are always sent.
Email Verified: Azure AD doesn't send the email verified claim in the users token, if you don't enable this setting. The user is then created with an unverified email, which results in an email verification message. If you want to avoid that, make sure to enable "Email verified". In that case, the user is created with a verified email address.
Tenant Type: Configure the tenant type according to what you have chosen in the settings of your Azure AD application previously.
- Common: Choose this if you want all Microsoft accounts being able to login. In this case, configure "Accounts in any organizational directory and personal Microsoft accounts" in your Azure AD App.
- Organizations: Choose this if you have Azure AD Tenants and no personal accounts. (You have configured either "Accounts in this organization" or "Accounts in any organizational directory" on your Azure App Registration).
- Consumers: Choose this if you want to allow public accounts. (In your Azure AD App you have configured "Personal Microsoft accounts only")
- Tenant ID: If you have selected Tenant ID as Tenant Type, you have to enter the Directory (Tenant) ID into the Tenant ID field, copied previously from the Azure App configuration.
Automatic creation: If this setting is enabled the user will be created automatically within Blockbrain Auth, if it doesn't exist yet. - recommended
Automatic update: If this setting is enabled, the user will be updated within Blockbrain Auth, if some user data is changed withing the provider. E.g if the lastname changes on the Microsoft account, the information will be changed on the Blockbrain Auth account on the next login. - recommended
Account creation allowed: This setting determines if account creation within Blockbrain Auth is allowed or not.
Account linking allowed: This setting determines if account linking is allowed. In this case, when logging in with a Microsoft account, a linkable Blockbrain Auth account has to exist already.

Either account creation or account linking have to be enabled. Otherwise, the provider can't be used.

Activate IdP

Once you created the provider, it is listed in the providers overview. Activate it by hovering over the provider and selecting the tick with the tooltip as available.

If you deactivate a provider, your users with links to it will not be able to authenticate anymore. You can reactivate it and the logins will work again.