> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/user-guides/system-management/authentication-and-authorization/authentication/user-authentication/entra-id.md). # 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. {% hint style="warning" %} 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](/user-guides/system-management/authentication-and-authorization/authentication/customer-authentication.md). {% endhint %} ## 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. ```mermaid --- config: layout: fixed theme: base look: classic themeVariables: background: transparent lineColor: "#9CBBE3" arrowheadColor: "#9CBBE3" edgeLabelBackground: "#FFC128" edgeLabelTextColor: "#4C5359" --- flowchart LR EG["Entra ID group"] --> MAP["entraid_mapping"] MAP --> IG["Emporix IAM groups"] MAP --> DPR["Developer Portal role"] EG@{ shape: rounded} MAP@{ shape: rounded} IG@{ shape: rounded} DPR@{ shape: rounded} EG:::Class_01 MAP:::Class_map IG:::Class_iam DPR:::Class_01 classDef Class_01 fill:#F2F6FA, stroke:#4C5359 classDef Class_map fill:#FFC128, stroke:#4C5359 classDef Class_iam fill:#A1BDDC, stroke:#4C5359 ``` {% hint style="info" %} For the Emporix permission model, see the following documentation: * [Identity and Access Management (IAM)](/user-guides/system-management/authentication-and-authorization/authorization/iam.md) * [Users and Groups](/user-guides/management-dashboard/administration/usersandgroups.md) * [Access Controls](/user-guides/management-dashboard/administration/access-controls.md) * [Scopes](/user-guides/management-dashboard/administration/scopes.md) {% endhint %} ## 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. {% hint style="info" %} For more details, refer to Microsoft documentation: [Quickstart: Register an application with the Microsoft identity platform](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app). {% endhint %} ## Set up Microsoft Entra ID Access {% stepper %} {% step %} #### 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. {% endstep %} {% step %} #### Send Entra ID details to Emporix Support Contact the [Emporix Support Team](mailto:support@emporix.com) 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 {% hint style="warning" %} Send the client secret to Emporix Support only. Do not put the secret in the `entraid_mapping` configuration. {% endhint %} {% endstep %} {% step %} #### 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. {% hint style="info" %} For Microsoft's own steps, see [Optional claims](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims). {% endhint %} {% endstep %} {% step %} #### 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. {% endstep %} {% step %} #### 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](https://developer.emporix.io/api-references/api-guides/configuration/configuration-service/api-reference/tenant-configurations#post-configuration-tenant-configurations) endpoint. {% hint style="info" %} 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](/user-guides/getting-started/developer-portal/manage-apikeys.md). {% endhint %} The request body is an array. Each object key inside `value` is an Entra ID group object ID: ```json [ { "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](/user-guides/getting-started/developer-portal/manage-users.md). 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. {% hint style="info" %} For more information about creating tenant configurations, see the [Configuration Service tutorial](https://app.gitbook.com/s/d4POTWomuSS7d3dnh4Dg/api-guides/configuration/configuration-service/configuration-service-tutorial). {% endhint %} {% endstep %} {% step %} #### 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. {% endstep %} {% endstepper %} ## 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. ```mermaid --- config: layout: fixed theme: base themeVariables: primaryColor: '#DDE6EE' primaryTextColor: '#4C5359' primaryBorderColor: '#4C5359' actorBkg: '#DDE6EE' actorBorder: '#4C5359' actorTextColor: '#4C5359' actorLineColor: '#4C5359' signalColor: '#E86C07' signalTextColor: '#7B8B99' lineColor: '#9CBBE3' arrowheadColor: '#E86C07' noteBkgColor: '#FFC128' noteTextColor: '#4C5359' noteBorderColor: '#4C5359' activationBkgColor: '#A1BDDC' activationBorderColor: '#4C5359' background: transparent --- sequenceDiagram actor Employee participant Apps as Management Dashboard or Developer Portal participant Auth as Emporix authentication participant Entra as Microsoft Entra ID participant Config as Configuration Service participant IAM as IAM Service Employee->>Apps: Sign in with corporate account Apps->>Auth: Start SSO Auth->>Entra: Verify identity Entra-->>Auth: Token with groups claims Auth->>Config: Read entraid_mapping Config-->>Auth: Entra groups → tenant access + IAM groups Auth->>IAM: Synchronize tenant access and IAM group memberships Auth-->>Apps: Access granted Apps-->>Employee: Open tenant with mapped permissions ``` ## 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)](/user-guides/system-management/authentication-and-authorization/authentication/user-authentication/sso.md). ## 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](/user-guides/getting-started/developer-portal/manage-apikeys.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://developer.emporix.io/user-guides/system-management/authentication-and-authorization/authentication/user-authentication/entra-id.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.