Pomerium

# Azure Active Directory

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 (opens new window) for free.

You can access the Azure management portal from your Microsoft service, or visit https://portal.azure.com (opens new window) 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 (opens new window) to Office 365.
  2. Navigate to the Office 365 Admin Center (opens new window).
  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

Then under MANAGE, select App registrations.

Select App registrations

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

Next you will need to create a key which will be used as the Client Secret in Pomerium's configuration settings. Click on Certificates and Secrets from the Settings menu, then click new client secret.

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

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 Manage -> Authentication --> Add a platform -> Select Web

Add a platform

On the following screen, then add Pomerium's redirect URL. For example, https://${authenticate_service_url}/oauth2/callback.

Add Reply URL

Next, in order to retrieve group information from Active Directory, we need to enable the necessary permissions for the Microsoft Graph API (opens new window).

Please note, Group ID (opens new window) not group name will be used to affirm group membership.

On the App registrations page, click API permissions. Click the Add a permission button and select Microsoft Graph API, select Application permissions. Select the checkboxes for Directory.Read.All, Group.Read.All and User.Read.All.

Azure add group membership claims

You can also optionally select grant admin consent for all users which will suppress the permission screen on first login for users.

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

Click on Endpoints

Endpoint details

The OpenID Connect Metadata Document value will form the basis for Pomerium's Provider URL setting.

For example if the Azure OpenID Connect url is:

https://login.microsoftonline.com/0303f438-3c5c-4190-9854-08d3eb31bd9f/v2.0/.well-known/openid-configuration`

Pomerium Identity Provider URL would be

https://login.microsoftonline.com/0303f438-3c5c-4190-9854-08d3eb31bd9f/v2.0

# Service Account (Optional)

TIP

By default, this information will be inferred from your provider URL. If you are using a different OAuth2 (opens new window) credential set, you may need to set these values separately.

To use allowed_groups in a policy an idp_service_account needs to be set in the Pomerium configuration. The service account for Azure AD uses the same client ID and client secret configured above, as well as the directory (tenant) ID:

Application dashboard

The format of the idp_service_account for Azure AD is a base64-encoded JSON document:

{
  "client_id": "...",
  "client_secret": "...",
  "directory_id": "..."
}

# Pomerium Configuration

Finally, configure Pomerium with the identity provider settings retrieved in the previous steps. Your environmental variables (opens new window) should look something like:

# Azure
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"
# Optional, if service account credentials are different
# or cannot be inferred from the above credential set.
# IDP_SERVICE_ACCOUNT="REPLACE-ME-SEE-ABOVE"

← Cognito →