Microsoft Entra ID

Microsoft Entra ID (formerly Azure Active Directory) is Microsoft's cloud-based identity platform. Integrating it with GAccess allows your users to sign in with their Microsoft organisational accounts, and enables GAccess to automatically provision, update, and deactivate user accounts based on your directory.

GAccess supports the following two standards to provision and authenticate federated users in EntraID:

• OpenID Connect (OIDC) — Authentication and SSO protocol built on top of OAuth 2.0.
• SCIM 2.0 — Entra ID pushes user and group changes to GAccess in real time as they occur in the directory.

Prerequisites

Before configuring GAccess, register an application in the Azure portal:

1. Sign in to the Azure portal and navigate to Microsoft Entra ID → Enterprise Applications → New Application → Create your Own Application.
2. Type a meaningful for your app and select "Integrate any other application you don’t find in the gallery (Non-gallery application)".
3. Now go to App Registration menu and set the Redirect URI to: https://<your-gaccess-domain>/api/v1/sso/entra/callback
4. After registration, note the Application (client) ID and Directory (tenant) ID — you will need both during GAccess configuration.
5. Navigate to Certificates & secrets → New client secret. Set an appropriate expiry and note the secret value immediately — it is only shown once.
6. Under API permissions, add the following Microsoft Graph delegated permissions and grant admin consent:
   • openid
   • profile
   • email
   • offline_access
   • User.Read
   • User.Read.All
   • Group.Read.All

Configuration

Navigate to Settings → Identity Providers → Add and select Microsoft Entra ID.

SCIM 2.0 provisioning

SCIM (System for Cross-domain Identity Management) allows Entra ID to push user and group changes to GAccess in real time — creating, updating, and deactivating accounts as they change in the directory, without requiring a user to log in first.

Enabling SCIM

1. In GAccess, open the identity source and navigate to the SCIM section.
2. Click Generate token. Copy the token — it is shown only once.
3. In the Azure portal, navigate to your enterprise application and open Provisioning.
4. Set Provisioning Mode to Automatic.
5. Enter the following in the Admin Credentials section:
   • Tenant URL: https://api-<your-gaccess-domain>/scim/v2
   • Secret Token: the token generated in step 2.
6. Click Test Connection to verify, then save and start provisioning.

SCIM token management

The SCIM bearer token can be rotated at any time from the GAccess identity source settings without reconfiguring the full integration — only the token in Azure needs to be updated. Revoking the token immediately disables all SCIM provisioning until a new token is generated and configured.

How SSO authentication works

When a user clicks Sign in with Microsoft on the GAccess login page:

1. GAccess redirects the user to the Microsoft login endpoint for the configured tenant.
2. The user authenticates with Microsoft, including any MFA or conditional access policies defined in Entra ID.
3. Microsoft redirects back to GAccess with an authorisation code.
4. GAccess exchanges the code for an ID token and validates it (signature, audience, and nonce).
5. GAccess fetches the user's profile from Microsoft Graph.
6. GAccess links the login to an existing GAccess account matched by Entra Object ID or email. If no matching account is found, the login is rejected — user accounts must be provisioned via SCIM before they can sign in.
7. A GAccess session token is issued and the user is redirected to their original destination.

All steps are recorded in the GAccess audit log under the SSO_LOGIN and SSO_USER_UPDATED event types.

Account auto-linking

When a user signs in via SSO for the first time, GAccess attempts to match their Entra ID identity to an existing account in two steps:

1. Match by Entra Object ID — if a GAccess account already has the same externalId, the login succeeds and the SSO profile is refreshed.
2. Match by email address — if no Object ID match is found, GAccess looks for a local account with the same email. If one exists, it is automatically converted to a federated account: the Entra Object ID is stored, the identity source is updated, and the account's existing roles, group memberships, and permissions are fully preserved. This event is recorded in the audit log as SSO_USER_AUTO_LINKED.

If neither match succeeds, the login is rejected. The user must be provisioned via SCIM before they can sign in.

Auto-linking is a one-time migration path for pre-existing local accounts. Once a user is federated, all future logins match by Object ID.

Attribute mapping

GAccess maps Entra ID attributes to user fields in two contexts: during SCIM provisioning and during SSO login.

SCIM provisioning attributes

These attributes are sent by Entra ID when a user is created or updated via SCIM:

SSO login attributes

On each successful SSO login, GAccess refreshes the following fields from the Microsoft Graph user profile:

SSO login does not update core account fields such as username, email, name, or externalId — those are managed exclusively by SCIM to ensure consistency. The externalId is written once during the initial account link and never overwritten.

Troubleshooting