OpenID Connect (OIDC) Single Sign-On (SSO)

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0 that allows applications to verify user identities. It enables secure authentication through trusted identity providers while eliminating the need for separate credentials. Phase supports OIDC-based SSO integration with major providers like Google, allowing seamless and secure access to your applications.

This page walks through registering an application with each supported OIDC provider. Once you have the Client ID / Secret / Tenant values, you can plug them into Phase in two ways: the Per-organisation (recommended) path — configure SSO from the Console via SSO (Microsoft Entra ID and Okta today) — or the Instance-wide (legacy) path — inject them as environment variables on a self-hosted deployment. Each provider section below ends with tabs for both paths where available.

Google

Google's OAuth 2.0 APIs are compatible with OpenID Connect (OIDC) and can be used to set up SSO. In fact, you can use your existing Google OAuth 2.0 credentials for OIDC authentication as long as you set the 'Authorized redirect URIs' correctly.

Follow these steps to set up Google SSO for your Phase application:

1. Go to your Google Cloud Platform Console and click the Select a project dropdown.

   

2. Click New project. If you already have a project you want to use, select it from the list and skip to step 5.

   

3. Enter a valid Project Name and click Create.

   

4. Go to your newly created project by clicking SELECT PROJECT from the notifications.

   

5. In your console's search box, type "Credentials" and click on the result that says Credentials - APIs & Services.

   

6. Click on + CREATE CREDENTIALS and select OAuth client ID. If this is your first time creating an OAuth credential, you'll need to set up a consent screen. If you've already set up a consent screen, skip to Step 13.

   

7. When prompted to configure an OAuth consent screen, click the CONFIGURE CONSENT SCREEN button.

   

8. Choose External as the User Type for the OAuth consent screen.

   

9. Enter details for mandatory fields such as App name, User support email, and Developer contact information. Click SAVE AND CONTINUE.

   
   

10. Continue through the Scopes step by clicking SAVE AND CONTINUE.

    

11. Continue through the Test user setup screen by clicking SAVE AND CONTINUE.

    

12. Review the details of your Consent screen app registration and click BACK TO DASHBOARD.

    

13. In the APIs & Services dashboard, click + CREATE CREDENTIALS and select OAuth client ID from the dropdown.

    

14. In the Application type dropdown, select Web application. Enter a recognizable name in the Name field, add the Authorized redirect URI (e.g., https://[YOUR_DOMAIN].com/api/auth/callback/google-oidc), and click CREATE.

You can copy the following path, please make sure to pre-fix it with scheme + your domain.

/api/auth/callback/google-oidc

15. You will be presented with the OAuth Client ID and Client secret. Copy these by clicking the clipboard icon next to each.

    

16. Supply these credentials to your Phase Console deployment as environment variables.

You can find detailed official instructions for setting up SSO with a Google OAuth Application here.

JumpCloud

You can use JumpCloud as an OIDC provider to set up SSO for your Phase instance. Follow these steps to set up a JumpCloud SSO application for Phase:

1. Log in to your JumpCloud Admin Console and click SSO Applications from the sidebar.

   

2. In the SSO Applications section, click Get Started if you haven't configured any apps before, or + Add New Application if you already have existing applications.

   

3. Select Custom Application from the available options (located at the bottom right).

   

4. On the custom application screen, click Next to proceed.

   

5. Choose Configure SSO with OIDC as your authentication method and click Next.

   

6. Fill in the general information for your application, including the Display Label and Description, then click Next.

   

7. Review your configuration settings and click Configure Application.

   

8. Add your Phase application's Redirect URI (e.g., https://[YOUR_DOMAIN].com/api/auth/callback/jumpcloud-oidc) and Login URL.

   You can copy the following path, please make sure to pre-fix it with scheme + your domain.

   /api/auth/callback/jumpcloud-oidc
   

   Copy

   Copied!
   

9. Under the Standard Scopes section, ensure Email and Profile are selected. (This information is required for user provisioning.)

   

10. Click the Activate button at the bottom right of screen to enable the application.

    

11. Please copy the Client ID and Client Secret provided. You'll need to supply these as environment variables to your Phase instance. Please see deployment configuration.

    

12. Next, we need to provision user access to your JumpCloud application. Please navigate to the User Groups tab to manage access.

    

13. Select the user groups that should have access to Phase by clicking the checkbox.

    

14. Click Save to provision access.

    

Your JumpCloud SSO integration is now configured! Users can access Phase through their JumpCloud application launchpad.

For more detailed information about JumpCloud SSO configuration, refer to the official JumpCloud documentation.

Microsoft Entra ID / Azure AD

You can integrate Microsoft Entra ID (formerly Azure Active Directory) as an OIDC provider for your Phase instance. Follow these steps to set up Microsoft Entra ID SSO for Phase:

1. Sign in to the Azure Portal with your Microsoft account.

   

2. Select Microsoft Entra ID from the side navigation blade or from Azure services. You can also search for Microsoft Entra ID in the search bar.

   

3. In the Microsoft Entra ID dashboard, select App registrations from the Manage dropdown section in the sidebar.

   

4. Click the New registration button in the top menu.

   

5. Provide a name for your application, select the supported account types, you will have a choice between:

   1. Accounts in this organizational directory only (Single tenant)
   2. Accounts in any organizational directory (Any Azure AD directory - Multitenant)
   3. Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (Multi-tenant)

   For most users this will be Option 1: Accounts in this organizational directory only - Single tenant

   In the Redirect URI section, select Web and add the appropriate redirect URI for your Phase instance. This will be the hostname of your instance, followed by:

   /api/auth/callback/entra-id-oidc
   

   Copy

   Copied!

   (e.g., https://[YOUR_PHASE_HOST]/api/auth/callback/entra-id-oidc).

   Click Register to create the application.

   

6. Once your application is registered, copy the Application (client) ID from the Overview page. This will be used as your ENTRA_ID_OIDC_CLIENT_ID.

   

7. Still on the Overview page, copy the Directory (tenant) ID. This will be used as your ENTRA_ID_OIDC_TENANT_ID.

   

8. Select Certificates & secrets under the Manage dropdown section in the sidebar.

   

9. In the Client secrets tab, click New client secret.

   

10. Provide a description for your client secret and select an appropriate expiration period, we suggest >= 730 days (24 months) then click Add.

11. Immediately copy the generated client secret value. This will be used as your ENTRA_ID_OIDC_CLIENT_SECRET. Note that you will not be able to view this value again after leaving this page.

    

12. You now have the three values needed to configure Phase — Tenant ID, Client ID, and Client Secret. See the Per-organisation / Instance-wide tabs at the end of this section for where to plug them in.

13. (Optional) Configure additional application properties by navigating to Entra ID > Enterprise Applications > All applications > select the app you just created (Phase Console) > under the Manage dropdown in the left sidebar, select Properties. These settings help customize the appearance and access controls for your application.

    

    You can configure:

    • Homepage URL: Set this to your Phase application's homepage (e.g., https://acme.com)

    • Logo: Upload a custom logo for your application that will appear in the Microsoft Entra ID portal and user sign-in experiences

    • Assignment required: This important setting controls access to your application:

      • If set to Yes: Users or groups must be explicitly assigned to the application before they can access it
      • If set to No: All users or groups in your directory can access the application without assignment

    • Visibility options: These settings control whether the application appears in user portals (e.g., https://myapplications.microsoft.com)

Your Microsoft Entra ID SSO application is now configured! You can now provision user access to your Phase instance by adding the application to individual users in your Microsoft Entra ID directory or to groups of users.

For more detailed information about Microsoft Entra ID application registration and OIDC configuration, refer to the official Microsoft documentation.

Troubleshooting: Microsoft Entra ID

Issue: Need Admin Approval

If users encounter a "Need admin approval" screen while trying to log into the Phase Console, asking them to either sign in with an admin account or return to the application without granting consent:

Resolve this by following these steps:

1. Log into the Azure Portal as an administrator
2. Navigate to Entra ID > Enterprise Applications
3. Select the application you have set up (Phase Console)
4. Under the Security dropdown in the left sidebar, select Permissions
5. Click Grant admin consent for <Your Organization> as shown in the screenshot below

After granting admin consent, users should be able to log in without seeing the "Need admin approval" message on the consent screen.

Issue: User Email Missing

If a user is unable to log in to the Phase Console and upon reviewing the frontend logs you see the following error:

phase-frontend-dev | message: 'User does not have a valid email'.

This error suggests that the Phase Console was unable to fetch the user's email during authentication. This is most common for users that have been created in Entra ID manually by an administrator without an email address.

To resolve this:

1. Log into the Azure Portal as an Administrator
2. Navigate to Entra ID
3. Select Users under the Manage dropdown
4. Select the user who is having trouble logging in
5. Click Edit properties
6. Click Contact information
7. Add the user's email address
8. Click Save

After adding the email address to the user's profile, they should be able to log in successfully.

Okta

You can use Okta as an OIDC provider to set up SSO for your Phase instance. Follow these steps to set up an Okta SSO application for Phase:

1. Go to the Okta Admin Dashboard, enter your organization URL, and log in. In the sidebar, navigate to Applications > Applications.

   

2. Click on the Create App Integration button.

   

3. For the Sign-in method, select OIDC - OpenID Connect. For the Application type, choose Web Application. Then, click Next.

   

4. On the New Web App Integration page, configure the following:

   • Enter an App integration name (e.g., "Phase Console").
   • Under Sign-in redirect URIs, add your Phase application's redirect URI. This will be the hostname of your instance followed by:

   /api/auth/callback/okta-oidc
   

   Copy

   Copied!

   (e.g., https://[YOUR_PHASE_HOST]/api/auth/callback/okta-oidc).

   • For sign-out redirect URIs, add your Phase application's sign-out redirect URI. This will be the hostname of your instance. e.g., https://[YOUR_PHASE_HOST].
   

5. Next, scroll down to view the Assignments section, select who should have access to this application. For the purposes of this guide we are going to choose Allow everyone in your organization to access. Please feel free to scope this down to a specific group of users if you prefer. Click Save.

   

6. After the application is created, you will be taken to its settings page. In the General tab, under Client Credentials, copy the Client ID and Client secret.

   

7. To find your Okta domain, click the drop-down in the top right corner. Copy the host listed under your name and email (e.g., acme-1234567.okta.com). Prefix it with https:// — this is your Issuer URL.

   

You now have the three values needed to configure Phase — Issuer URL, Client ID, and Client Secret. See the Per-organisation / Instance-wide tabs below for where to plug them in.

You can find more detailed information in the official Okta documentation.