Skip to main content

Azure Active Directory

This page will help you configure Pomerium to use your Azure Active Directory as an IdP. It assumes you have already installed Pomerium

caution

While we do our best to keep our documentation up to date, changes to third-party systems are outside our control. Refer to Quickstart: Register an application with the Microsoft identity platform from Microsoft's documentation as needed, or let us know if we need to re-visit this page.

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 for free.

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

  1. Login to Microsoft Azure and choose Azure Active Directory. You may need to click on More Services first:

    Select Active Directory

  2. Under Manage, select App registrations.

    Select App registrations

    Then click on the + New registration button to add a new application.

  3. Enter a name for the application. Under Redirect URI select Web and set the value to https://${authenticate_service_url}/oauth2/callback. You can confirm your authenticate service URL from your Pomerium configuration.

    Create application form

    After you register the application, note the Application (client) ID, and Directory (tenant) ID.

  4. Under Client credentials, click Add a certificate or secret. The secret you create will be used as the Client Secret in Pomerium's configuration settings.

  5. Under Client secrets click + New client secret. Enter a name for the key and choose the desired duration.

    Creating a Key

    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 to ensure users don't experience a service interruption.

    Click on Add 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.

    note

    Confirm you are copying the Value, and not the ID.

API Permissions​

In order to retrieve group information from Active Directory, we need to enable the necessary permissions for the Microsoft Graph API.

Please note, Group ID not group name will be used to affirm group membership.

  1. From the application page, click API permissions.

    • Click the + Add a permission button and select Microsoft Graph API.
    • Select Application permissions.
    • Use the filter to select the checkboxes for Directory.Read.All, Group.Read.All and User.Read.All, then click Add permissions.

    Azure add group membership claims

    You can also optionally select Grant admin consent for Default Directory which will suppress the permission screen on first login for users.

  2. The 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

Pomerium Configuration​

Configure Pomerium with the identity provider settings retrieved in the previous steps.

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'

Getting Groups​

Custom Claim (Open Source)​

To authorize users based on their group membership, Azure supports adding a group claim to the identity token:

Add Groups Claim

Now when users login they will have a claim named groups that contains their groups and the claim PPL criterion can be used for authorization:

routes:
  - from: 'https://verify.localhost.pomerium.io'
    to: 'https://verify.pomerium.com'
    policy:
      - allow:
          and:
            - claim/groups: 'e14f56fd-b956-4009-b06c-dc8a5e9207c8'
tip

The groups claim contains group IDs, not group names.