Skip to main content

🔐 OIDC SSO Setup Guide (Azure AD / Entra ID)

This guide walks through the complete setup of Single Sign-On (SSO) for X-AutoMate using Microsoft Entra ID (Azure AD) as the Identity Provider (IdP) via OpenID Connect (OIDC).

Throughout this guide, <your-backend-url> is the public URL of your X-AutoMate backend (for example https://devxautomate.bos.no) and <your-frontend-url> is the public URL users open in the browser. Always use the real deployment URLs — never localhost.

☁️ 1. Azure AD App Registration​

  1. Go to Azure Portal → Microsoft Entra ID → Add → App Registration → New Registration.

  2. Configure:

    • Name: x-automate (or x-automate-dev)
    • Supported account types: Single Tenant (or Multi-Tenant)
    • Redirect URI:
      • Platform: Web
      • URI: https://<your-backend-url>/main/api_v2/login/sso/callback
    Include the /main prefix

    The backend API is served under the /main base path. A redirect URI without it (https://<your-backend-url>/api_v2/login/sso/callback) will not work — Azure will redirect to a path that does not exist and the login will fail.

  3. Save:

    • 🆔 Client ID
    • 🏢 Tenant ID

  4. Create a Client Secret under Manage → Certificates & Secrets (we'll need Secret ID value for AZURE_AD_CLIENT_SECRET env).

🎫 Enable ID Tokens​

Enable ID Tokens under Manage → Authentication → Settings → Implicit Grant and Hybrid Flows.

👥 2. App Roles Setup​

On Manage → App roles → Create app role

Display name, Value, Description Role values follow:

{project}_{role} (lower case project name and role with underscore separation)

Available roles:

  • admin
  • tester
  • dq_admin
  • dq_tester
  • test_admin

Examples:

  • default_admin
  • default_tester
  • default_dq_admin
  • default_dq_tester
  • default_test_admin
  • myproject_tester etc

For Allowed member types field select Both (Users/Groups + Applications)

Role names must match X-AutoMate exactly

The {role} part of the Azure app role value is matched against the project role name in X-AutoMate exactly, and the comparison is case-sensitive. Use the same spelling and the same case on both sides:

  • Azure value default_admin → project default, role admin → X-AutoMate must have an OIDC project role named exactly admin — not Admin, and not a synonym such as administrator.

See ProjectRole Mapping for how to create the matching roles.

👤 Assign Users​

On Enterprise Applications:

  • Manage → All applications
  • Select the app you created at App registration step
  • Manage → Users and Groups → Add User/Group → Assign App Roles (select user and assign role)
Email addresses must match

The email address of the X-AutoMate user must be identical to the email address of the account in Entra ID. Users are matched by email when they log in through SSO, so a mismatch (a different domain, an alias, or a typo) means the login will not resolve to the expected user.

⚙️ 3. Environment Variables​

SSO_ENABLED=True
AZURE_AD_TENANT_ID=<tenant-id>
AZURE_AD_CLIENT_ID=<client-id>
AZURE_AD_CLIENT_SECRET=<client-secret>
AZURE_AD_REDIRECT_URI=https://<your-backend-url>/main/api_v2/login/sso/callback
AZURE_AD_AUTHORITY=https://login.microsoftonline.com
FRONTEND_BASE_URL=https://<your-frontend-url>

AZURE_AD_REDIRECT_URI must be the backend URL of the deployment you are configuring and must be identical to the redirect URI registered in Azure (step 1), including the /main prefix.

FRONTEND_BASE_URL is where the backend sends the browser back to after the SSO callback, including when the login fails. If it is not set it falls back to localhost, so a failed login redirects to an address the user's browser cannot reach — the login appears to end in a bare 302 with no indication of what went wrong. Always set it explicitly.

🧩 Role Claim Pattern​

Default:

^(?P<project>[^_]+)_(?P<role>.+)$

🗄️ 4. ProjectRole Mapping​

Every Azure App Role must have a matching ProjectRole entry with source OIDC.

OIDC roles are not created automatically

A newly created project — including the default project — has no OIDC project roles. Until an administrator creates them, every SSO login fails because the role from Azure has nothing to match against in the project. Create the OIDC roles before the first SSO login.

Create one entry per Azure app role, using the {role} part of the Azure value verbatim (lower case, exactly as it appears in Azure):

{
  "project_role_name":"admin",
  "project_role_source":"OIDC"
}

So an Azure app role with value default_admin requires the project default to have an OIDC project role named admin. Because the match is case-sensitive, a role named Admin or administrator will not match default_admin.

🔄 5. SSO Login Flow​

  1. Frontend calls /api_v2/login/sso/authorize
  2. User authenticates with Azure AD
  3. Azure redirects to callback
  4. Backend validates token
  5. User is auto-provisioned
  6. Roles are synchronized
  7. ID token is returned

🧪 SSO Test Page​

Available at:

https://<your-backend-url>/sso-test

Features:

  • 🔑 Login testing
  • 👀 View claims
  • 🧩 View parsed roles
  • 🛠️ API testing

🚨 Troubleshooting​

❌ SSO is not enabled​

Verify:

SSO_ENABLED=True

❌ Login ends in a 302 with no error message​

FRONTEND_BASE_URL is not set, so the backend redirects errors to localhost instead of your frontend. Set it to your frontend URL and retry — the actual error will then be shown:

FRONTEND_BASE_URL=https://<your-frontend-url>

❌ Signature verification failed​

Use the id_token instead of access_token.

❌ Redirect fails after authenticating with Azure​

Verify the redirect URI includes the /main prefix and is identical in Azure and in AZURE_AD_REDIRECT_URI:

https://<your-backend-url>/main/api_v2/login/sso/callback

❌ A user with this email already exists​

The email address returned by Entra ID already belongs to a local (username/password) X-AutoMate account, and SSO does not currently link an existing local account to an SSO identity. Either remove the local account before the first SSO login, or use a different email address for the SSO user.

❌ User has no project access​

Verify:

  • Azure App Role assignment
  • Matching ProjectRole entry exists in the project with source OIDC (these are not created by default — see ProjectRole Mapping)
  • The role name matches the Azure value exactly, including case (default_admin → admin)
  • The user's email in X-AutoMate matches the email in Entra ID
  • Correct claim pattern

❌ Roles not appearing​

Verify:

  • App Roles exist
  • App Roles are enabled
  • User is assigned to the role