OEE IntelliSuite · administrator guide

Connect Microsoft Entra ID

Register one Microsoft application for the suite sign-in broker, map Entra groups to suite roles, and verify access across Pulse and Explorer.

Before you start

This guide is for an Azure / Entra administrator and the person managing the suite deployment. The suite must have authentication and its shared sign-in broker enabled. Obtain the deployment's public HTTPS broker origin, for example https://auth.plant.example.com, and coordinate configuration changes with the suite operator.

The broker receives Microsoft sign-in once and shares the session with configured suite applications. Explorer is a separate OIDC client of the broker; it does not require a second Microsoft registration. The broker, app origins and Explorer origin must be under the configured cookie domain, with the edge routing the broker hostname to Pulse. The suite deploy configuration must use one shared authentication secret across the enabled apps.

Examples only. Replace all hostnames and UUIDs below with values from your tenant and deployment. Never put a real client secret in a ticket, screenshot, or source control.

1 · Register the application

  1. In Microsoft Entra admin center → App registrations → New registration, register a web application in the tenant that owns your users. Select Accounts in this organizational directory only (single tenant). Record the Application (client) ID and Directory (tenant) ID. Microsoft registration instructions
  2. Under Authentication, add a Web platform redirect URI, using the exact public broker origin:
    https://auth.plant.example.com/api/auth/callback/microsoft
    
    The origin must match the deployment, including any port. Add a separate exact URI for each environment that uses this registration; prefer separate registrations and credentials for separate environments. Microsoft redirect URI rules
  3. Under Certificates & secrets → Client secrets, create a secret and capture its value immediately in your approved secret store. Supply it securely to the suite operator and record an expiry and rotation owner. The current suite Microsoft provider accepts a client ID and client secret; an Entra certificate credential is not a drop-in replacement for this configuration. Microsoft credential instructions
  4. Apply your tenant's consent, guest, MFA and Conditional Access policies. A single-tenant registration can include guests admitted to that tenant. Test with the intended policy and accounts; app registration alone does not grant every user suite access.

2 · Configure groups and roles

Create or choose Entra security groups for the suite roles and record each group's Object ID, not its display name. In the app registration, configure group claims so the ID token contains a groups array of Entra group object IDs. For example, choose Security groups in the group-claim configuration; do not emit groups as roles or substitute names, SIDs or on-premises attributes. Verify the resulting token for a test user. Microsoft group-claim configuration

Suite role Typical access
viewer Read-only access to devices, jobs and reports.
employee Basic access, including job punches.
supervisor Team and operational management, reports and exports.
admin Full suite administration, including users and system settings.

These are suite roles. The current integration maps group IDs in suite configuration; it does not read the Entra roles claim. Defining Entra app roles or assigning a group to an Entra app role alone will not grant the corresponding suite role. The supported path is group membership → ID-token groups → suite mapping. Microsoft app roles reference

Keep the claim complete. Microsoft omits the groups array when the JWT group limit is exceeded (200 groups); the suite does not resolve an overage through Graph and will refuse that sign-in. If you restrict claims to Groups assigned to the application, assign the mapped groups to the enterprise app and make users direct members: nested memberships are not included in this mode. Group assignment requires the appropriate Entra licensing (P1/P2). Microsoft assignment and licensing details

3 · Configure the suite

Give the suite operator the tenant ID, client ID, secret through an approved secret channel, and the group Object ID → role mapping. In the deployment's client configuration, these values belong in the broker's Pulse env-vars. The broker configuration itself is deployment-owned; do not hand-author its derived AUTH_BROKER_JSON.

MICROSOFT_TENANT_ID=<tenant-uuid>
MICROSOFT_CLIENT_ID=<application-client-id>
MICROSOFT_CLIENT_SECRET=<secret-value>
AUTH_MICROSOFT_GROUP_ROLES_JSON={"aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa":"viewer","bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb":"admin"}

The map must be a nonempty JSON object of distinct group UUIDs and exact lowercase role names. The tenant setting must be the same single tenant's UUID. Mapping is opt-in: if AUTH_MICROSOFT_GROUP_ROLES_JSON is absent, existing Microsoft sign-in behavior remains and the unmapped-group refusal described here does not apply. The operator applies the configuration using the normal deployment process, then verifies the broker.

Multiple memberships: the highest mapped role wins, in this order: viewer → employee → supervisor → admin. Review overlapping membership before granting access.

4 · Grant and verify access

  1. Add each intended user to a mapped security group. If the enterprise app requires assignment, assign the user or eligible group there as well. Enterprise-app assignment and the suite's group-to-role map are separate checks.
  2. Open the suite sign-in page and select Continue with Microsoft. Authenticate with the tenant account and satisfy any tenant MFA or consent prompts. A new mapped Microsoft identity can be created on first sign-in even if AUTH_DISABLE_SIGN_UP=true.
  3. Check the user's role and expected access in Pulse, then open Explorer from Pulse and verify the intended dashboard and access. A user with no mapped group, a missing or malformed group claim, a foreign tenant or an overage response is refused rather than given a default role.
  4. Test an unmapped user, an overlapping-group user and an existing user as well as a new user. For an unlinked existing local account, the existing suite role must already match the mapped role for linking. Single-tenant email linking trusts the tenant's identity and guest admission controls; verify those controls are appropriate before relying on it.
SSO lab Pulse dashboard after a Microsoft account signs in
SSO lab: Pulse after Microsoft sign-in. In a separate lab group-role check, admin, supervisor and viewer mappings were exercised and unmapped users were refused; this image illustrates the sign-in destination, not the role claim.

For the end-user sign-in experience, see the Microsoft single sign-on user guide.

Operations & troubleshooting

  • Role change or removal: the suite refreshes a linked Microsoft user's role at the next Microsoft sign-in. When the role changes or the user is unmapped at sign-in, database sessions are removed; signed session caches can remain valid until expiry. This is not an immediate directory-driven revocation guarantee. Use your incident access controls and session-revocation procedures when urgency requires them.
  • Sign-in refused: inspect tenant and enterprise-app assignment, user membership, the exact mapped object IDs and the ID token's tid, oid and groups claims. Check for group overage and whether assigned-group filtering requires direct membership. Treat tokens as sensitive and do not paste them into support tickets.
  • Redirect error: compare the registered Web redirect URI character for character with the broker's public origin and callback path; verify HTTPS routing and the configured client and tenant IDs.
  • Existing account does not link: check the mapped role against the existing suite role and the account's email. When Microsoft does not return email, the broker may use preferred_username as an unverified sign-in name. Resolve account ownership with the suite administrator before changing a role or linking identities.
  • Rotate credentials: create a replacement client secret, update the suite's secure deployment configuration, apply it and verify sign-in before removing the old secret. Track expiry and do not expose its value in logs.

References

Microsoft Learn pages checked 9 November 2026. Product details reflect the suite broker and group-role implementation; the SSO lab verified mapped and unmapped examples on 6 November 2026.