Set up SSO with Microsoft

This page is for organization owners and admins who want members to sign in to Actagate with their Microsoft Entra ID work account. The deployment that runs Actagate registers one sign-in app. On the organization settings screen you only allow sign-in and choose the allowed tenant IDs.

The operator who runs Actagate registers the app and sets the environment variables (steps 1 and 2). The product vendor does not provide a shared OAuth app. Register this app separately from the Entra app that grants access during execution.

1. Register the app in Entra ID

1. In the Microsoft Entra admin center, open “App registrations” and press “New registration”
2. For supported account types, choose “Accounts in any organizational directory” and register. Personal Microsoft accounts are not supported. The app Overview opens
3. Copy the Application (client) ID from the Overview
4. Under “Certificates & secrets”, create a client secret and copy its Value, not the secret ID. Note the expiry date and create a new secret before it expires
5. Under “API permissions”, add the delegated permissions openid, email and profile. Grant admin consent if your tenant’s consent policy requires it
6. Copy the Directory (tenant) ID from the Overview of the users’ tenant. You use it in step 3

Official documentation: OpenID Connect on the Microsoft identity platform

2. Set the environment variables

1. Set the Web app environment variables MICROSOFT_OIDC_CLIENT_ID and MICROSOFT_OIDC_CLIENT_SECRET to the values from step 1
2. Restart the Web app. “Microsoft” appears in the Single sign-on list under Settings > Security

Keep the secret in the deployment’s secret store, not in the repository. If either variable is missing, Microsoft does not appear on the settings screen or the login screen. Set WEB_BASE_URL to the public HTTPS origin that users open.

3. Save the Microsoft settings in Actagate

1. Open Settings > Security (/ws/settings/security). Under Single sign-on, in “Pick a provider to add a connection”, open “Microsoft”. The Microsoft form opens
2. Enter the tenant ID (GUID) in “Allowed Microsoft tenant IDs”. Separate several IDs with newlines or commas
3. Leave “Allow Microsoft sign-in” cleared and press “Save”. “Redirect URI to register in Entra ID” appears below the form

An organization has one Microsoft connection. Unlike OIDC connections, it has no test stage.

4. Register the redirect URI

1. Copy the displayed https://<host>/api/auth/sso/callback/<connection ID>
2. Under “Authentication” of the Entra app, register it as a redirect URI for the “Web” platform. Match the displayed value exactly, including the connection ID

5. Allow Microsoft sign-in

1. Select “Allow Microsoft sign-in” and press “Save”. The login screen shows a “Continue with Microsoft” button

Turning it on requires at least one tenant ID. Accounts from other tenants cannot sign in. Tokens whose tid (tenant ID) and iss do not match are rejected too.

6. Check sign-in

1. An invited member who is not an admin presses “Continue with Microsoft” on the login screen and signs in with Microsoft. The Actagate screen opens
2. Check that an account from a tenant you did not allow sees “This Microsoft tenant is not allowed.”

Actagate identifies a Microsoft user by the pair of tenant ID and object ID (tid and oid). Only on the first sign-in, it matches the UPN (preferred_username) from an allowed tenant against the invited member’s email address. The UPN must be in email format and match the registered email address. From the second sign-in on, the account stays the same even if the UPN changes. Owners and admins sign in with an existing method first, then link Microsoft with “Add Microsoft” under Settings > Login methods.

7. Troubleshooting

• Microsoft is not in the list: check that both MICROSOFT_OIDC_CLIENT_ID and MICROSOFT_OIDC_CLIENT_SECRET are set and that the Web app was restarted
• Microsoft reports a redirect URI mismatch: check that the URI registered in Entra matches the settings screen exactly
• “This Microsoft tenant is not allowed.” (tenant_forbidden): add that tenant ID to “Allowed Microsoft tenant IDs”
• The login screen shows an error after a successful Microsoft sign-in: check that you set the Value of the client secret and that it has not expired

Other reason codes are listed in SSO troubleshooting.