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
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 sign up 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.
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:
- Sign in to Office 365.
- Navigate to the Office 365 Admin Center.
- Open the Admin centers menu drawer located in the left menu.
- 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. You may need to click on More Services first:
Under Manage, select App registrations.
Then click on the + New registration button to add a new application.
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.After you register the application, note the Application (client) ID, and Directory (tenant) ID.
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.
Under Client secrets click + New client secret. Enter a name for the key and choose the desired duration.
tipIf 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.
noteConfirm 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.
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.
You can also optionally select Grant admin consent for Default Directory which will suppress the permission screen on first login for users.
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.
Click on Endpoints
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.
- config.yaml
- Environment Variables
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'
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)
- Directory Sync (Enterprise)
Custom Claim (Open Source)
To authorize users based on their group membership, Azure supports adding a group
claim to the identity token:
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'
The groups
claim contains group IDs, not group names.
Directory Sync (Enterprise)
Azure uses the same Client ID and Client Secret used in Pomerium Core.
Configure Pomerium Enterprise Console
Under Settings → Identity Providers, select "Azure" as the identity provider and set the Client ID, Client Secret and Directory (Tenant) ID.
Troubleshooting
- In our testing, we found that users could be created in an Active Directory without an email address as part of their user claim. Pomerium user identity depends largely on the associated email address.
- If your default user in the Active Directory is unauthorized (403) even when specified as allowed in a policy by user, you can mitigate by creating a group membership and corresponding policy.