Last update: March 7, 2024

Azure AD (MS Entra) Authentication Management¶

This guide provides information about the single sign-on (SSO) options available and introduces the process of planning a single sign-on deployment when using Azure Active Directory (Azure AD) with Virto Commerce.

Note

Azure Active Directory (Azure AD) has been renamed to Microsoft Entra ID. For the remainder of this guide, these terms are considered synonymous.

Readmore Azure App Configuration

By default, the Virto Commerce Platform Manager authenticates users with a login and password. However, this method has its drawbacks:

Each Virto Commerce Platform account must be manually created by an administrator.
Users are required to remember their login and password and input them each time they sign in to Virto Commerce Platform Manager.

These issues can be solved by enabling sign-in with Azure Active Directory, allowing users of a certain company to sign in or sign up using their Azure AD account.

Azure Active Directory authentication offers several advantages:

Virto Commerce Platform Manager automatically creates a new account the first time a user signs in, eliminating the need for manual creation by administrators.
Users do not need to remember another password, as they can use their existing Azure AD account.
Azure Active Directory employs the single sign-on flow, meaning users who already utilize Microsoft services such as Office 365 or Outlook.com do not need to enter their password to sign in to Virto Commerce Platform Manager.

To implement single sign-on, Virto Commerce Platform utilizes the OpenID Connect protocol provided by the Microsoft.AspNetCore.Authentication.OpenIdConnect library.

Prerequisites¶

Before enabling Azure Active Directory authentication, ensure the following:

Your company has a valid Azure Active Directory tenant. If not, follow the quickstart guide to create one.
You have an Azure account associated with your company's Azure Active Directory tenant. If you do not have an Azure account yet, start a free Azure subscription.
A Virto Commerce Platform instance is running, either locally or on Azure. Ensure you have privileges to modify its configuration.
If managing roles and privileges for users signed up with Azure AD is required, ensure you have administrator access to Virto Commerce Platform Manager.

Setup¶

To set up the Azure Active Directory based authentication in Virto Commerce Platform Manager:

Add Registration for Virto Commerce Platform in Azure Active Directory¶

Sign in to the Azure Portal using your Azure account.
Select Azure Active Directory to access the overview of your company's Azure AD tenant.
Navigate to App registrations and click the New registration button to register a new application.
Provide the necessary information on the Register an application screen:
- Name: Application name for your Virto Commerce Platform instance (visible to users on the Azure AD sign-in page).
- Supported account types: Leave the default value.
- Redirect URI: Select Web and enter the external sign-in URL of your Virto Commerce Platform (/signin-oidc), e.g., http://localhost:10645/signin-oidc.
Note

If your URL is not localhost, HTTPS is required.
After registration, copy the values from the Application (client) ID and Directory (tenant) ID fields for use in the next step:
In Authentication, enable ID tokens and save the changes:

Configure Virto Commerce Platform to Use Azure AD Authentication¶

To configure Virto Commerce Platform to use Azure AD authentication:

Open appsettings.json for the Virto Commerce Platform instance.

Navigate and find the AzureAd node:

appsettings.json

"AzureAd": {
    "Enabled": false,
    "AuthenticationType": "AzureAD",
    "AuthenticationCaption": "Azure Active Directory",
    "ApplicationId": "(Replace this with Application (client) ID, e.g. 01234567-89ab-cdef-0123-456789abcdef)",
    "TenantId": "(Replace this with Directory (tenant) ID, e.g. abcdef01-2345-6789-abcd-ef0123456789)",
    "AzureAdInstance": "https://login.microsoftonline.com/",
    "DefaultUserType": "Manager",
    "UsePreferredUsername": false
}

Modify the following settings:

Set Enabled to true.
Paste the value of Application (client) ID from app registration in Azure to ApplicationId.
Paste the value of Directory (tenant) ID to TenantId.

The updated configuration should look as follows:

appsettings.json

"AzureAd": {
    "Enabled": true,
    "AuthenticationType": "AzureAD",
    "AuthenticationCaption": "Azure Active Directory",
    "ApplicationId": "b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
    "TenantId": "fe353e8f-5f08-43b4-89d1-f4acec93df33",
    "AzureAdInstance": "https://login.microsoftonline.com/",
    "DefaultUserType": "Manager",
    "UsePreferredUsername": false,
    "Priority": 0
}

Restart your Virto Commerce Platform instance to apply the updated settings.

Test¶

Navigate to the login page of Virto Commerce Platform Manager and locate the Sign in with Azure Active Directory link:
Click the link to be redirected to the Microsoft sign-in page. You might be asked to sign in with your Microsoft account if you did not sign in with it earlier. Sign in with your Azure account credentials. Make sure this account belongs to the same domain where you registered the application.
If prompted, grant permission for the application to sign you in and read your account information.
Upon successful sign-in, you will be redirected back to Virto Commerce Platform Manager, where you will be authenticated:

Note

The account created via Azure AD sign-in is a regular Virto Commerce Platform account with default roles and permissions. Adjustments may be required by the administrator.

Multitenant Azure AD¶

If you use the Azure AD authentication and want to allow users from any tenant to connect to your Virto Commerce application, you need to configure the Azure AD app as multi-tenant and use a wildcard tenant ID, such as organizations or common in the authority URL.

You also need to switch Validate Issuer from Default to MultitenantAzureAD mode.

appsettings.json

    "AzureAd": {
        "TenantId": "common",
        "ValidateIssuer" : "MultitenantAzureAD",
    },

The updated configuration might look like this:

appsettings.json

    "AzureAd": {
        "Enabled": true,
        "AuthenticationType": "AzureAD",
        "AuthenticationCaption": "Azure Active Directory",
        "ApplicationId": "b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
        "TenantId": "common",
        "ValidateIssuer" : "MultitenantAzureAD",
        "AzureAdInstance": "https://login.microsoftonline.com/",
        "DefaultUserType": "Manager",
        "UsePreferredUsername": false,
        "Priority": 0
    },

Advanced Details¶

As mentioned above, when a user signs in with Azure Active Directory for the first time, Virto Commerce Platform automatically creates a new account for them. But what happens if the Virto Commerce Platform account with the same login already exists?

To answer this question, let's explore the Azure Active Directory authentication in Virto Commerce Platform deeper.

VC Platform trigegrs Microsoft.AspNetCore.Authentication.OpenIdConnect to verify the user's identity. This initiates a standard OpenID Connect flow, redirecting the user to the Azure Active Directory sign-in page and then back to the Virto Commerce Platform.
When this flow is over, Virto Commerce Platform receives Azure Active Directory account information for the current user and extracts the upn claim value from it.
Virto Commerce Platform then attempts to find an existing Virto Commerce Platform account with a login that matches that upn claim value. This search can lead to three possible outcomes:
1. If the account already exists and is associated with the Azure Active Directory account of the signed-in user, no further action is taken, and Virto Commerce Platform authenticates the user using the existing account.
2. If the account exists but lacks external sign-in information for Azure Active Directory, Virto Commerce Platform updates the account to include this information. All other account details, such as roles, permissions, and personal information, remain unchanged.
3. If no such account exists yet, Virto Commerce Platform creates a new one and links it to the Azure Active Directory account.
If the upn claim is not transferred, resulting in an error message like Received external login info does not have an UPN claim or DefaultUserName, you can configure the system to use either the preferred username or email address claims instead. Use the following settings in the appsettings.json file:
appsettings.json
```
    {
        "UsePreferredUsername": true
    }
```
or:
appsettings.json
```
    {
        "UseEmail": true
    }
```

Warning

If you see the IDX10205: Issuer validation failed error, this means you forgot to switch ValidateIssuer to MultitenantAzureAD.

Configuration with Custom Azure AD App Signing Keys¶

If your app has custom signing keys, you can receive the following error upon the POST https://localhost:5001/signin-oidc request:

appsettings.json

Microsoft.IdentityModel.Tokens.SecurityTokenSignatureKeyNotFoundException: IDX10501: Signature validation failed. Unable to match key

If your app uses custom signing keys due to the claim mapping feature, you need to append an appid query parameter containing the app ID. This ensures you receive a jwks_uri pointing to your app's signing key information.

For instance, the URL https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid=6731de76-14a6-49ae-97bc-6eba6914391e contains a jwks_uri of https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys?appid=6731de76-14a6-49ae-97bc-6eba6914391e.

Here is an example of the updated configuration that resolves the above issue:

appsettings.json

    "AzureAd": {
        "Enabled": true,
        "AuthenticationType": "AzureAD",
        "AuthenticationCaption": "Azure Active Directory",
        "ApplicationId": "b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
        "TenantId": "fe353e8f-5f08-43b4-89d1-f4acec93df33",
        "AzureAdInstance": "https://login.microsoftonline.com/",
        "MetadataAddress": "https://login.microsoftonline.com/fe353e8f-5f08-43b4-89d1-f4acec93df33/v2.0/.well-known/openid-configuration?appid=b6d8dc6a-6ddd-4497-ad55-d65f91ca7f50",
        "DefaultUserType": "Manager",
        "UsePreferredUsername": false
    }