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 for the general instructions.

​
Prerequisites

As prerequisites you will need the following:

​
Create an OIDC application

  1. On the Microsoft Entra admin center, navigate to Identity > Applications
  2. Select New Registration
New Registration New Registration
  1. Specify General Settings
    • App name, e.g. Ona
    • Platform: Web
    • Redirect URI: https://app.gitpod.io/auth/oidc/callback
Register Application Register Application
  1. 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 New client secret
New client secret
  • Adjust the expiry of the client secret Client secret expiry
Client secret expiry
  • Then copy the value of the client secret to be pasted in Ona’s SSO setup Client secret copy
Client secret copy
  1. Configure OIDC Scopes
    • The default selection of OIDC scopes in Microsoft Entra ID doesn’t meet the requirements for Ona. Please navigate to API permissions > Add a permission to make the necessary changes.
Add a permission Add a permission
  • Select Delegated permissions and OpenId, then ensure to enable the following scopes:
    • email
    • openid
    • profile
OpenID Scopes OpenID Scopes
  • 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
Add email scope Add email scope
  1. Obtain Issuer URL from Endpoints tab
    • Navigate to the Overview page and select Endpoints
Endpoints tab Endpoints tab
  • Copy the Authority URL to be used as Issuer URL in Ona’s SSO setup
Endpoints issuer Endpoints issuer
Note: Validate the Issuer URL by checking the OIDC Discovery 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}, please 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.
  1. 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
Client ID Client ID
  1. Continue with the SSO configuration in Ona: Clicking Save & Test