Auth0
This page documents configuring an Auth0 Web Application and Machine to Machine Application for Pomerium to read user data. 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 Applications in Auth0 from Auth0's docs as needed, or let us know if we need to re-visit this page.
Log in to your Auth0 account and head to your dashboard. Select Applications → Applications on the left menu. On the Applications page, click the Create Application button to create a new app.
Create Regular Web Application
On the Create New Application page, name your application and select the Regular Web Application for your application. This is the application that your users will login to.
Under the Settings tab, note the Domain, Client ID, and Client Secret values. We'll provide these to Pomerium at the end of the process.
Provide the following information for your application settings:
Field Description Name The name of your application. Application Login URI Authenticate Service URL (e.g. https://${authenticate_service_url}
)Allowed Callback URLs Redirect URL (e.g. https://${authenticate_service_url}/oauth2/callback
).Allowed Logout URLs Sign Out URL (e.g. https://${authenticate_service_url}/.pomerium/signed_out
).Under Advanced Settings → OAuth, confirm that JSON Web Token (JWT) Signature Algorithm is set to "RS256".
Click Save Changes at the bottom of the page when you're done.
Configure Pomerium
You can now configure Pomerium with the identity provider settings retrieved in the previous steps. Your config.yaml
keys or environmental variables should look something like this.
- config.yaml
- Environment Variables
idp_provider: 'auth0'
idp_provider_url: 'https://awesome-company.auth0.com'
idp_client_id: 'REPLACE_ME' # from the web application
idp_client_secret: 'REPLACE_ME' # from the web application
IDP_PROVIDER="auth0"
IDP_PROVIDER_URL="https://awesome-company.auth0.com"
IDP_CLIENT_ID="REPLACE_ME" # from the web application
IDP_CLIENT_SECRET="REPLACE_ME" # from the web application
Remember to prepend the provider URL from Auth0 with https://
.
Groups
- Custom Claim (Open Source)
- Directory Sync (Enterprise)
Custom Claim
To authorize users based on their group membership (roles in Auth0), a claim can be added to the identity token with a login action.
Create an action named
add groups
with the following code:exports.onExecutePostLogin = async (event, api) => {
if (event.authorization) {
api.idToken.setCustomClaim(
'pomerium.io/groups',
event.authorization.roles,
);
}
};Deploy the action:
Add it to the login flow:
Now when users login they will have a claim named pomerium.io/groups
that contains their groups (Auth0 roles) 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/pomerium.io/groups: admin
Setting Up Directory Sync
Create a Machine to Machine Application. A different application is used for grabbing roles to keep things more secure.
Click Create.
On the next page select Auth0 Management API from the dropdown. Under Permissions use the filter on the right to narrow things down to
role
, and choose theread:roles
andread:role_members
roles.Then click Authorize.
Retrieve the Client ID and Client Secret from the Settings tab.
Configure Pomerium Enterprise Console
Under Settings → Identity Providers, select "Auth0" as the identity provider and set the Client ID, Client Secret and Domain.