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

# Microsoft Entra ID

You can set up Single Sign-on (SSO) with Microsoft Entra ID for your team.

This section helps you to create an OIDC application with Microsoft Entra ID. The *Client ID*, *Client Secret*, and *Issuer URL* of this OIDC application are required to setup SSO in Ona. See the [step-by-step guide](/ona/sso/overview#setting-up-single-sign-on) for the general instructions.

## Prerequisites

As prerequisites you will need the following:

* Access to [Microsoft Entra admin center](https://entra.microsoft.com/)

## Create an OIDC application

1. On the [Microsoft Entra admin center](https://entra.microsoft.com/), navigate to *Identity > Applications*.

2. Select **New Registration**.

3. Specify General Settings

   * App name, e.g. `Ona`
   * Platform: `Web`
   * Redirect URI: `https://app.gitpod.io/auth/oidc/callback`

4. Obtain *Client Secret* from the *Certificates & secrets* page

   * Once the application is registered, navigate to the subpage *Certificates & secrets* to create and obtain a new client secret.
     * Click the **New client secret** button.
     * Adjust the expiry of the client secret.
     * Then copy the value of the client secret to be pasted in Ona's SSO setup.

5. Configure OIDC Scopes

   * The default selection of OIDC scopes in Microsoft Entra ID doesn't meet the requirements for Ona. Navigate to *API permissions > Add a permission* to make the necessary changes.
     * Select *Delegated permissions* and *OpenId*, then ensure to enable the following scopes:
       * `email`
       * `openid`
       * `profile`

   * Although the `email` claim is part of the standard OIDC specification, depending on the setup, Microsoft Entra ID does not include it by default in ID tokens. Under *Manage*, select *Token configuration* and fix this:
     * Click **Add optional claim**.
     * Add the `email` scope.

6. Obtain *Issuer URL* from *Endpoints* tab

   * Navigate to the *Overview* page and select *Endpoints*.
   * Copy the *Authority URL* to be used as *Issuer URL* in Ona's SSO setup.

   <Note>
     Validate the **Issuer URL** by checking the [OIDC Discovery](https://learn.microsoft.com/en-us/entra/identity-platform/v2-protocols-oidc#find-your-apps-openid-configuration-document-uri) location. In some configurations, the **Issuer URL** needs to be adjusted.

     If the *Authority URL* reads like `https://login.microsoftonline.com/{tenant}/v2.0`, the OIDC Discovery location is `https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration`. Open this URL in your browser and check the `issuer` field.

     Check the `issuer` field in the OIDC Discovery output and ensure this matches the *Authority URL* (*Issuer URL*). If not, e.g. if it reads like `https://sts.windows.net/{tenant}`, try again with `{authority_url}/v2.0/.well-known/openid-configuration` and use `{authority_url}/v2.0` as *Issuer URL* in Ona's SSO setup.
   </Note>

7. Obtain the *Client ID* from the *Overview* page

   * Navigate to the *Overview* page and copy the *Application (client) ID* value to be used as *Client ID* in Ona's SSO setup.

8. Continue with the SSO configuration in Ona: [Clicking *Save & Test*](/ona/sso/overview#setting-up-single-sign-on)