--- title: Identity Providers description: >- This article describes how to connect pomerium to third-party identity providers / single-sign-on services. You will need to generate keys, copy these into your promerium settings, and enable the connection. --- # Identity Provider Configuration This article describes how to configure pomerium to use a third-party identity service for single-sign-on. There are a few configuration steps required for identity provider integration. Most providers support [OpenID Connect] which provides a standardized interface for authentication. In this guide we'll cover how to do the following for each identity provider: 1. Establish a **Redirect URL** with the identity provider which is called after authentication. 2. Generate a **Client ID** and **Client Secret**. 3. Configure pomerium to use the **Client ID** and **Client Secret** keys. ## Azure If you plan on allowing users to log in using a Microsoft Azure Active Directory account, either from your company or from external directories, you must register your application through the Microsoft Azure portal. If you don't have a Microsoft Azure account, you can [signup](https://azure.microsoft.com/en-us/free) for free. You can access the Azure management portal from your Microsoft service, or visit and sign in to Azure using the global administrator account used to create the Office 365 organization. ::: tip There is no way to create an application that integrates with Microsoft Azure AD without having **your own** Microsoft Azure AD instance. ::: If you have an Office 365 account, you can use the account's Azure AD instance instead of creating a new one. To find your Office 365 account's Azure AD instance: 1. [Sign in](https://portal.office.com) to Office 365. 2. Navigate to the [Office 365 Admin Center](https://portal.office.com/adminportal/home#/homepage). 3. Open the **Admin centers** menu drawer located in the left menu. 4. Click on **Azure AD**. This will bring you to the admin center of the Azure AD instance backing your Office 365 account. ### Create a new application Login to Microsoft Azure and choose **Azure Active Directory** from the sidebar. ![Select Active Directory](./microsoft/azure-dashboard.png) Then under **MANAGE**, select **App registrations**. ![Select App registrations](./microsoft/azure-app-registrations.png) Then click on the **+ ADD** button to add a new application. Enter a name for the application, select **Web app/API** as the **Application Type**, and for **Sign-on URL** enter your application URL. ![Create application form](./microsoft/azure-create-application.png) Next you will need to create a key which will be used as the **Client Secret** in Pomeriunm's configuration settings. Click on **Keys** from the **Settings** menu. Enter a name for the key and choose the desired duration. ::: tip If you choose an expiring key, make sure to record the expiration date in your calendar, as you will need to renew the key (get a new one) before that day in order to ensure users don't experience a service interruption. ::: Click on **Save** and the key will be displayed. **Make sure to copy the value of this key before leaving this screen**, otherwise you may need to create a new key. This value is used as the **Client Secret**. ![Creating a Key](./microsoft/azure-create-key.png) Next you need to ensure that the Pomerium's Redirect URL is listed in allowed reply URLs for the created application. Navigate to **Azure Active Directory** -> **Apps registrations** and select your app. Then click **Settings** -> **Reply URLs** and add Pomerium's redirect URL. For example, `https://sso-auth.corp.beyondperimeter.com/oauth2/callback`. ![Add Reply URL](./microsoft/azure-redirect-url.png) The final, and most unique step to Azure AD provider, is to take note of your specific endpoint. Navigate to **Azure Active Directory** -> **Apps registrations** and select your app. ![Application dashboard](./microsoft/azure-application-dashbaord.png) Click on **Endpoints** ![Endpoint details](./microsoft/azure-endpoints.png) The **OpenID Connect Metadata Document** value will form the basis for Pomerium's **Provider URL** setting. For example, if your **Azure OpenID Connect** is `https://login.microsoftonline.com/0303f438-3c5c-4190-9854-08d3eb31bd9f/v2.0/.well-known/openid-configuration` your **Pomerium Identity Provider URL** would be `https://login.microsoftonline.com/0303f438-3c5c-4190-9854-08d3eb31bd9f/v2.0`. ### Configure Pomerium At this point, you will configure the integration from the Pomerium side. Your [environmental variables] should look something like: ```bash # Azure REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" IDP_PROVIDER="azure" IDP_PROVIDER_URL="https://login.microsoftonline.com/{REPLACE-ME-SEE-ABOVE}/v2.0" IDP_CLIENT_ID="REPLACE-ME" IDP_CLIENT_SECRET="REPLACE-ME" ``` ## Gitlab :::warning Gitlab currently does not provide callers with a user email, under any scope, to a caller unless that user has selected her email to be public. Because Pomerium is by nature very centric, users are cautioned from using Pomerium until [this gitlab bug](https://gitlab.com/gitlab-org/gitlab-ce/issues/44435#note_88150387) is fixed. ::: Log in to your Gitlab account and go to the [APIs & services](https://console.developers.google.com/projectselector/apis/credentials). Navigate to **User Settings** then **Applications** using the left-hand menu. On the **Applications** page, add a new application by setting the following parameters: Field | Description ------------ | -------------------------------------------- Name | The name of your web app Redirect URI | `https://${redirect-url}/oauth2/callback` Scopes | **Must** select **read_user** and **openid** ![Create New Credentials](./gitlab/gitlab-create-application.png) 1.Click **Save Application** to proceed. Your `Client ID` and `Client Secret` will be displayed: ![Gitlab OAuth Client ID and Secret](./gitlab/gitlab-credentials.png) Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this. ```bash REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" IDP_PROVIDER="gitlab" # NOTE!!! Provider url is optional, but should be set if you are running an on-premise instance # defaults to : https://gitlab.com, a local copy would look something like `http://gitlab.corp.beyondperimeter.com` IDP_PROVIDER_URL="https://gitlab.com" IDP_CLIENT_ID="yyyy" IDP_CLIENT_SECRET="xxxxxx" ``` When a user first uses pomerium to login, they will be presented with an authorization screen similar to the following. ![gitlab access authorization screen](./gitlab/gitlab-verify-access.png) ## Google Log in to your Google account and go to the [APIs & services](https://console.developers.google.com/projectselector/apis/credentials). Navigate to **Credentials** using the left-hand menu. ![API Manager Credentials](./google/google-credentials.png) On the **Credentials** page, click **Create credentials** and choose **OAuth Client ID**. ![Create New Credentials](./google/google-create-new-credentials.png) On the **Create Client ID** page, select **Web application**. In the new fields that display, set the following parameters: Field | Description ------------------------ | ----------------------------------------- Name | The name of your web app Authorized redirect URIs | `https://${redirect-url}/oauth2/callback` ![Web App Credentials Configuration](./google/google-create-client-id-config.png) Click **Create** to proceed. Your `Client ID` and `Client Secret` will be displayed: ![OAuth Client ID and Secret](./google/google-oauth-client-info.png) Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this. ```bash REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" IDP_PROVIDER="google" IDP_PROVIDER_URL="https://accounts.google.com" IDP_CLIENT_ID="yyyy.apps.googleusercontent.com" IDP_CLIENT_SECRET="xxxxxx" ``` ## Okta [Log in to your Okta account](https://login.okta.com) and head to your Okta dashboard. Select **Applications** on the top menu. On the Applications page, click the **Add Application** button to create a new app. ![Okta Applications Dashboard](./okta/okta-app-dashboard.png) On the **Create New Application** page, select the **Web** for your application. ![Okta Create Application Select Platform](./okta/okta-create-app-platform.png) Next, provide the following information for your application settings: Field | Description ---------------------------- | ----------------------------------------------------- Name | The name of your application. Base URIs (optional) | The domain(s) of your application. Login redirect URIs | `https://${redirect-url}/oauth2/callback`. Group assignments (optional) | The user groups that can sign in to this application. Grant type allowed | **You must enable Refresh Token.** ![Okta Create Application Settings](./okta/okta-create-app-settings.png) Click **Done** to proceed. You'll be taken to the **General** page of your app. Go to the **General** page of your app and scroll down to the **Client Credentials** section. This section contains the **Client ID** and **Client Secret** to be used in the next step. ![Okta Client ID and Secret](./okta/okta-client-id-and-secret.png) At this point, you will configure the integration from the Pomerium side. Your [environmental variables] should look something like this. ```bash REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback" IDP_PROVIDER="okta" IDP_PROVIDER_URL="https://dev-108295-admin.oktapreview.com/" IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7" IDP_CLIENT_SECRET="xxxxxx" ``` [environmental variables]: https://en.wikipedia.org/wiki/Environment_variable [oauth2]: https://oauth.net/2/ [openid connect]: https://en.wikipedia.org/wiki/OpenID_Connect