Microsoft Entra ID Access

Use Microsoft Entra ID as the central source for employee login, group membership, and tenant access in Emporix.

Microsoft Entra ID Access lets you use Microsoft Entra ID as the central system for employee authentication, group membership, and permission management in Emporix. Employees sign in with their corporate Microsoft Entra ID accounts. Emporix then manages tenant access and role assignments based on the groups defined in Entra ID.

This integration applies to employee access to the Management Dashboard and Developer Portal. It does not replace or affect customer authentication for the storefront. For customer authentication options, see Customer Authentication.

Purpose

Keep identity governance centralized in Microsoft Entra ID and let Emporix apply the corresponding IAM groups and Developer Portal role at login. This reduces manual user administration and keeps commerce access aligned with your existing corporate identity processes.

For example, when a new employee joins your European sales team and is added to the appropriate Entra ID group, they automatically receive access to the relevant Emporix tenant and permissions. When they leave the team or the company, their access is removed through the existing corporate identity process. That change is reflected the next time they log in.

Features

Feature	Description
Single sign-on	Employees access Emporix with their existing Microsoft identity.
Group synchronization	Entra ID group memberships are mapped to Emporix IAM groups during login.
Tenant access	The mapping on each Emporix tenant determines which employees can sign in to that tenant.
Developer Portal role	The same mapping sets the Developer Portal role (ADMIN or USER).

Entra ID groups do not replace Emporix permissions. You still create employee groups, access controls, and scopes in Emporix. The entraid_mapping tenant configuration maps each Entra ID group to one or more Emporix IAM group IDs and to a Developer Portal role. Those IAM groups must exist before you create the mapping, because the configuration stores their IDs. Assign access controls to the IAM groups so mapped employees receive the intended permissions at login.

For the Emporix permission model, see the following documentation:

• Identity and Access Management (IAM)
• Users and Groups
• Access Controls
• Scopes

Prerequisites

Register an application for Emporix in Microsoft Entra ID so you can provide the client ID, directory ID, and client secret to Emporix Support.

For more details, refer to Microsoft documentation: Quickstart: Register an application with the Microsoft identity platform.

Set up Microsoft Entra ID Access

1

Prepare IAM groups and access controls

Using the Management Dashboard or the IAM Service API, create the employee groups you need and assign access controls to them. Note each group's ID. You use those IDs in entraid_mapping.

You can set a custom group ID when you create a group, or use the ID that Emporix generates.

2

Send Entra ID details to Emporix Support

Contact the Emporix Support Team and provide the following values:

• Application (client) ID
• Directory (tenant) ID
• The Value of the client secret from Certificates & secrets
• Administrator group object ID – object ID of the Administrator group defined in Microsoft Entra ID, used to grant administrator access

Send the client secret to Emporix Support only. Do not put the secret in the entraid_mapping configuration.

3

Add claims in Entra ID

In Microsoft Entra ID, open the app registration and go to Token configuration -> Optional claims. Add the following claims so the token includes the employee identity and group membership that Emporix uses at login:

• family_name and given_name — Emporix uses these to set the employee's last name and first name when the account is created or updated.
• groups — Emporix uses this to match Entra ID group membership to entraid_mapping and assign IAM groups and the Developer Portal role.

For Microsoft's own steps, see Optional claims.

4

Wait for Emporix to enable the integration

Emporix Support sets up SSO for your tenants if it is not already enabled, and configures the Entra ID integration details. Wait for confirmation before you create the mapping.

5

Create the group mapping

Create a tenant configuration with the key entraid_mapping using the Configuration Service API. Send the request to the Creating configurations endpoint.

To create the entraid_mapping tenant configuration, you need a service access token with the configuration.configuration_manage scope. For more information, see Manage API Keys.

The request body is an array. Each object key inside value is an Entra ID group object ID:

[
  {
    "key": "entraid_mapping",
    "version": 1,
    "secured": false,
    "restricted": false,
    "readOnly": false,
    "value": {
      "4ac5da17-6390-496b-b2a0-1db4211d5d8a": {
        "iamGroups": [
          "1gr5e52e-6e27-4ac5-9471-2467d3fb7504"
        ],
        "devPortalRole": "ADMIN"
      }
    }
  }
]

The value object consists of the following elements:

• Entra ID group object ID – object ID of the Microsoft Entra ID group, used as the property name in value (for example 4ac5da17-6390-496b-b2a0-1db4211d5d8a)

  • iamGroups – array of Emporix IAM group IDs. One Entra ID group can map to more than one IAM group.
  • devPortalRole – Developer Portal role for members of that Entra ID group: ADMIN or USER. See Manage Users.

To map further Entra ID groups, add more group object IDs inside the value object. Each Emporix tenant has its own entraid_mapping, so employees get access only to the tenants where their Entra ID groups are mapped.

For more information about creating tenant configurations, see the Configuration Service tutorial.

6

Sign in

After the mapping exists, employees can sign in to the Management Dashboard or Developer Portal with their corporate Microsoft account. At first login, they receive the IAM groups and Developer Portal role defined in entraid_mapping. They do not need a prior invitation email for Entra-mapped access.

Sign-in and synchronization

Group membership is applied at login. Emporix reads the groups from the Entra ID token, matches them to entraid_mapping, and assigns the mapped IAM groups and Developer Portal role.

Managing access after the integration is enabled

• Add or remove employees from Entra ID groups to change who can sign in and which permissions they receive. The change is applied at the next login.
• When Microsoft Entra ID Access is enabled, manual group assignment is disabled in the Management Dashboard.
• Update entraid_mapping when you introduce a new Entra ID group, retire a group, or change which IAM groups it maps to.
• To change what a mapped group can do in Emporix, update that group's access controls and scopes. To change who has that access, add or remove the employee in Entra ID directly.

Generic OpenID Connect SSO without Entra group mapping still uses invitation and account activation. See Emporix Single Sign-On (SSO).

API keys and scopes

Microsoft Entra ID Access does not create or manage API keys. Custom API keys stay in the Developer Portal. Align the scopes on those keys with the same scope model you use in the access controls assigned to mapped IAM groups. See Manage API Keys.