Integrating with Microsoft Entra ID

This article explains how to connect your Microsoft Entra ID tenant (formerly Azure AD) to Valven for single sign-on over SAML 2.0. In Entra ID, Valven is registered as a non-gallery Enterprise Application.

You'll need Global Administrator or Application Administrator access in your Entra ID tenant, and permission to change SSO settings in Valven.

Connect Your Application

Visit Settings → Single Sign-On on the Valven sidebar, and open the Microsoft Entra ID tab:

The panel on the right — “Set these in Entra” — gives you the Identifier (Entity ID), Reply URL (ACS), and Sign on URL you'll need below.

Create an Enterprise Application

Step 1: In the Entra admin center, go to Identity → Applications → Enterprise applications → New application.

Step 2: Click Create your own application, give it a name, and choose “Integrate any other application you don't find in the gallery (Non-gallery)”.

Step 3: Click Create.

Configure Basic SAML Settings

Step 1: On the application's page, go to Single sign-on and select SAML.

Step 2: In the Basic SAML Configuration card, click Edit.

Step 3: Set Identifier (Entity ID) to the value from the Valven panel, Reply URL (Assertion Consumer Service URL) to the Reply URL (ACS) value, and (optionally) Sign on URL to the Sign on URL value.

Step 4: Click Save.

Configure Attributes & Claims

Entra's default claim names already match Valven's default configuration for email, first name, and last name, so this step is usually only needed for group information.

Step 1: In the Attributes & Claims card, click Edit → Add a group claim.

Step 2: Choose which groups to include (e.g. Security groups, or All groups).

Step 3: Under Source attribute, choose Group ID, unless your tenant is synced from an on-premises Active Directory via Azure AD Connect, in which case names may also be available.

Important: by default, Entra ID sends group object IDs (GUIDs), not group names, unless your directory is synced from on-premises AD with names supplied. A GUID will never match a role name configured in Valven. If your tenant is cloud-only, use App roles instead of security groups, and assign users to those roles — App roles are sent by name, not GUID.

Import the Metadata into Valven

Step 1: On the SAML configuration page, scroll to the SAML Certificates card.

Step 2: Copy the App Federation Metadata URL, or download the Federation Metadata XML.

Step 3: In Valven, paste (or upload) this metadata into the Federation metadata XML box. This automatically fills in the Identity Provider Entity ID, Login URL, and Signing Certificate fields.

Create a Test User and Assign Access

Entra ID blocks sign-in for any user not explicitly assigned to the application.

Step 1: In Entra ID, go to Identity → Users → New user and create a test user. If you plan to test username-based sign-in, note that a cloud-only Entra ID tenant identifies users by User Principal Name (UPN), which is email-shaped by design — a short, AD-style username is only available for accounts synced from an on-premises directory via Azure AD Connect:

Step2: Login Azure Portal, Create App Role, go to application and App roles, Create app role.

Step 3: Go back to the Enterprise Application, open Users and groups, and click Add user/group.

Step 3: Select the test user and a role, if prompted, then click Assign.

Verifying the Connection

Back in Valven, turn on Single sign-on enabled and Use this provider for sign-in, then click Save Changes. Test SSO Configuration confirms the connection details were read correctly.

From the Valven sign-in page, enter the test user's email address and choose “Sign in with SSO”, you should land on the Microsoft sign-in page. Signing in with the test user should bring you back to Valven with the correct name and, if configured, role.

Common Errors

• AADSTS700016 — application not found: the Identifier (Entity ID) registered in Entra doesn't exactly match what Valven sends — check for a trailing slash, http vs https, or a stale value from an earlier test.
• AADSTS50105 — user not assigned: revisit Step "Create a Test User and Assign Access" step, the signed-in user (or a group they belong to) must be assigned to the Enterprise Application.
• Role or group information arrives but doesn't match: check whether the value received is a GUID rather than a name — switch to App roles, or sync your directory with names via Azure AD Connect.