> ## Documentation Index
> Fetch the complete documentation index at: https://docs.varios-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting up Microsoft Entra ID

> Configure sign-in, administrator roles and user synchronization for VARIOS AI in Microsoft Entra ID

VARIOS AI signs users in via OpenID Connect. This page describes the setup in Microsoft Entra ID and the corresponding values for the `.env`. You need a role that may register applications and grant permissions, usually Application Administrator plus consent from a Global Administrator.

Replace `<PROJECT_DOMAIN>` in all steps with the domain of your installation.

## Create the application

<Steps>
  <Step title="Create an enterprise application">
    In the Entra admin center, open **Enterprise applications → New application → Create your own application**. Enter a name such as "VARIOS AI" and choose **Integrate any other application you don't find in the gallery**. Entra automatically creates an app registration for it.

    On the overview page of the enterprise application, note the **Object ID**. It is needed for user synchronization (`SCIM_OBJECT_ID`).
  </Step>

  <Step title="Note the IDs">
    Switch to **App registrations** and open the application. Note the **Application (client) ID** for `OIDC_CLIENT_ID` and the **Directory (tenant) ID** for `OIDC_AUTHORITY`, `OIDC_CONFIGURATION_URL` and `SCIM_TENANT_ID`.
  </Step>

  <Step title="Enter the redirect URI">
    Under **Authentication → Add a platform**, choose **Web** (not Single-page application) and enter the redirect URI. Replace `<PROJECT_DOMAIN>` with the domain of your VARIOS AI installation, i.e. the value of `PROJECT_DOMAIN` from the `.env`; the path after it stays unchanged.

    ```text theme={null}
    https://<PROJECT_DOMAIN>/oauth2/oidc/oidc/finishauthorization
    ```

    Example for the domain `ai.example.com`: `https://ai.example.com/oauth2/oidc/oidc/finishauthorization`
  </Step>

  <Step title="Create a client secret">
    Under **Certificates & secrets → New client secret**, create a secret. Include the application in its description so that it is clear where it is used when it expires. Copy the **Value** immediately, it is shown only once, and enter it as `OIDC_CLIENT_SECRET`.

    <Warning>
      Client secrets expire after 24 months at most. Note the expiry date; an expired secret is the most common cause of sign-in suddenly failing.
    </Warning>
  </Step>

  <Step title="Add token claims">
    Under **Token configuration → Add optional claim**, choose the token type **ID** and the claims `email`, `family_name`, `given_name`, `preferred_username` and `upn`. Confirm the prompt to turn on the Graph permissions `email` and `profile`.
  </Step>

  <Step title="Grant API permissions">
    Under **API permissions → Add a permission → Microsoft Graph → Delegated permissions**, add: `openid`, `profile`, `email`, `offline_access`, `User.Read`.

    For the [Microsoft 365 Assistant](/en/extended-support/admin/global-assistants/microsoft365assistant) additionally: `Sites.Read.All`, `Mail.Read`, `Mail.Send`, `Chat.Read`, `ChannelMessage.Read.All`, `Calendars.Read`.

    Then click **Grant admin consent** and confirm.

    <Info>
      All permissions listed here are delegated: VARIOS AI acts on behalf of the signed-in user and only receives content that this user can access. `Sites.Read.All` too refers to the user's sites, not to the entire tenant. Application permissions without a user context are needed by VARIOS AI only optionally for user synchronization, see below.
    </Info>
  </Step>

  <Step title="Create app roles">
    Under **App roles → Create app role**, create four roles for **Users/Groups**. For the three administrator roles, the **Value** must exactly match the names in the `.env`:

    | Role                     | Value             | Variable                      |
    | ------------------------ | ----------------- | ----------------------------- |
    | User                     | `User`            | none                          |
    | Administrator            | `Admin`           | `ADMIN_GROUP_NAME`            |
    | Super administrator      | `SuperAdmin`      | `SUPERADMIN_GROUP_NAME`       |
    | Compliance administrator | `ComplianceAdmin` | `COMPLIANCE_ADMIN_GROUP_NAME` |
  </Step>

  <Step title="Assign users and groups">
    Go back to the **enterprise application → Users and groups → Add user/group**. Assign users or groups and choose the appropriate role per assignment. So that only assigned users can sign in, set **Assignment required** to **Yes** in the **Properties** of the enterprise application.

    Assigning entire **groups** requires a **Microsoft Entra ID P1** license or higher. Without P1, only individual users can be assigned; VARIOS AI then knows no groups from Entra ID.

    <Note>
      Entra does not resolve nested groups on assignment. Assign the groups in which the users are direct members.
    </Note>
  </Step>
</Steps>

## Values for the .env

```bash theme={null}
OIDC_PROVIDER=azure
OIDC_AUTHORITY=https://login.microsoftonline.com/<Directory ID>/v2.0
OIDC_CONFIGURATION_URL=https://login.microsoftonline.com/<Directory ID>/v2.0/.well-known/openid-configuration
OIDC_CLIENT_ID=<Application ID>
OIDC_CLIENT_SECRET=<Client secret>
OIDC_SCOPE=openid profile email offline_access User.Read
OIDC_USER_IDENTIFIER=upn
OIDC_ROLES_CLAIM=roles
ADMIN_GROUP_NAME=Admin
SUPERADMIN_GROUP_NAME=SuperAdmin
COMPLIANCE_ADMIN_GROUP_NAME=ComplianceAdmin
```

If you use the Microsoft 365 Assistant, extend `OIDC_SCOPE` with the additional permissions listed above. `OIDC_LOGOUT_URL` can remain empty; VARIOS AI then uses the sign-out URL from the Entra configuration.

## Synchronize users and groups

Roles come from the token at every sign-in. So that VARIOS AI also knows groups, for example to share assistants, users and groups are synchronized. There are two ways.

<Tabs>
  <Tab title="Entra pushes to VARIOS AI (SCIM)">
    Entra ID transfers users and groups to VARIOS AI via SCIM. For this, VARIOS AI must be reachable from Entra ID via port 443. Provisioning users works with any Entra edition; provisioning **groups** requires **Microsoft Entra ID P1** or higher.

    In the **enterprise application → Provisioning**, set the mode to **Automatic** and enter:

    * **Tenant URL:** `https://<PROJECT_DOMAIN>/scim/<SCIM_MANDANT>/v2`
    * **Secret token:** the value of `SCIM_TOKEN` from your `.env`, a long secret of your choice

    Under **Settings → Scope** you define whether only the assigned users and groups or all users and groups of the directory are transferred. Test the connection, save and start provisioning. In the `.env`:

    ```bash theme={null}
    SCIM_DIRECTION=push
    SCIM_MANDANT=<short name of your choice>
    SCIM_TOKEN=<long secret>
    ```
  </Tab>

  <Tab title="VARIOS AI reads from Entra (Graph)">
    VARIOS AI reads users and groups itself via Microsoft Graph. It reads the user and group list of the entire directory, but only the users and groups assigned to the enterprise application are transferred, users either directly or via an assigned group. For this, the app registration needs the **application permissions** `User.Read.All`, `Group.Read.All` and `Application.Read.All` under **API permissions**, with admin consent.

    No Entra provisioning is needed for this path. Since only assigned groups are transferred and assigning groups requires Entra ID P1, without P1 only individually assigned users arrive and no groups.

    ```bash theme={null}
    SCIM_DIRECTION=pull
    SCIM_TENANT_ID=<Directory ID>
    SCIM_OBJECT_ID=<Object ID of the enterprise application>
    ```
  </Tab>
</Tabs>

## Verification

* A user from an assigned group can sign in.
* A user with the `SuperAdmin` role sees the Administration menu.
* The synchronized entries appear under Administration → Users and Groups.

If sign-in fails, first check the redirect URI, the expiry date of the client secret and the user's group assignment.