This page documents how to configure an [Auth0] application for use with Pomerium. It assumes you have already [installed Pomerium](https://www.pomerium.com/docs/get-started/quickstart.md).

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](https://auth0.com/docs/applications) from Auth0's docs as needed, or [let us know](https://github.com/pomerium/documentation/issues/new?assignees=\&labels=\&template=doc-error.md) if we need to re-visit this page.

## Create an Auth0 Application

1. [Log in to your Auth0 account](https://manage.auth0.com/) and head to your dashboard. Select **Applications → Applications** on the left menu. On the Applications page, click the **Create Application** button.

   \[Auth0 Applications Dashboard]

2. On the **Create New Application** page, name your application and select the type **Native**, then click **Create**. This is the application that your users will log in to.

   \[Auth0 Create Application Select Platform]

3. Switch to the **Settings** tab, and note the **Domain**, **Client ID**, and **Client Secret** values. We'll need these later to configure Pomerium.

4. 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://auth.example.com`) |
   | Allowed Callback URLs | Redirect URL (e.g. `https://auth.example.com/oauth2/callback`). |
   | Allowed Logout URLs | Sign Out URL (e.g. `https://auth.example.com/.pomerium/signed_out`). |

5. In pomerium versions 0.31.X and below, if you want to use Pomerium's [**native SSH access**](https://www.pomerium.com/docs/capabilities/native-ssh-access.md): scroll down to **Advanced Settings** near the bottom of the page, then select the **Grant Types** tab. Make sure the **Device Code** box is checked:

   \[Auth0 Applications Dashboard]

The device code support is not needed in 0.32.0 and above.

1. Click **Save** 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 file keys:**

```yaml
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
```

**Environment Variables:**

```bash
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 Auth0 **Domain** with `https://` to get the provider URL.

## Groups

**Custom Claim (Open Source):**

### 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](https://auth0.com/docs/customize/actions).

1. Create an action named `add groups` with the following code:

   ```javascript
   exports.onExecutePostLogin = async (event, api) => {
     if (event.authorization) {
       api.idToken.setCustomClaim(
         'pomerium.io/groups',
         event.authorization.roles,
       );
     }
   };
   ```

2. Deploy the action:

   \[Auth0 Create Login Action]

3. Add it to the login flow:

   \[Auth0 Create 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:

```yaml
routes:
  - from: 'https://verify.localhost.pomerium.io'
    to: 'https://verify.pomerium.com'
    policy:
      - allow:
          and:
            - claim/pomerium.io/groups: admin
```

**Directory Sync (Enterprise):**

### Setting Up Directory Sync

1. Create a **Machine to Machine Application**. A different application is used for grabbing roles to keep things more secure.

   \[Auth Create Application Select Service Account Platform]

   Click **Create**.

2. 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 the `read:roles`, `read:role_members`, `read:users`, and `read:user_idp_tokens` roles.

   \[Auth0 Management API Scopes]

   Then click **Authorize**.

3. 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.

\[Auth0 Settings]

[auth0]: https://auth0.com/

[authenticate service url]: https://www.pomerium.com/docs/reference/service-urls.md#authenticate-service-url

[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable

[auth0]: https://auth0.com/

[authenticate service url]: https://www.pomerium.com/docs/reference/service-urls.md#authenticate-service-url

[environmental variables]: https://en.wikipedia.org/wiki/Environment_variable