Skip to main content

Okta

Okta is a popular identity provider used by businesses of all sizes. Integrating Pomerium with Okta allows you to use the identity Okta provides to apply context-driven policies from Pomerium to your infrastructure.

This page covers configuring Okta to communicate with Pomerium as an IdP. It assumes you have already installed Pomerium before you begin.

caution

While we do our best to keep our documentation up to date, changes to third-party systems are outside our control. Refer to Create an Okta app Integration from Okta's developer docs as needed, or let us know if we need to re-visit this page.

Create OpenID Connect Application​

  1. Log in to your Okta account From the left-hand menu, Select Applications → Applications on the top menu.

    Okta Applications Dashboard

  2. Click the Create App Integration button. Select OIDC as the sign-in method. and Web Application as the application type:

    Okta new app integration modal

    Click Next to continue.

  3. Provide the following information for your application settings:

    FieldDescription
    NameThe name of your application.
    Grant type allowedYou must enable Refresh Token.
    Base URIsOptional: The domain(s) of your application.
    Sign-in redirect URIsRedirect URL (e.g.https://${authenticate_service_url}/oauth2/callback).
    Controlled AccessThe user groups that can sign in to this application. See Group ID for more information.

    Okta Create Application Settings

    Click Save to proceed. You'll be taken to the General tab of your app.

  4. From the General tab, scroll down to the Client Credentials section. This section contains the Client ID and Client Secret. Temporarily save these values to apply to the Pomerium configuration.

    Okta Client ID and Secret

Configure Pomerium​

Finally, configure Pomerium with the identity provider settings retrieved in the previous steps. Your environmental variables should look something like this.

idp_provider: 'okta'
idp_provider_url: 'https://awesomecompany.okta.com'
idp_client_id: 'REPLACE ME'
idp_client_secret: 'REPLACE ME'

Custom Claim (Open Source)​

Groups​

A groups claim can be added to tokens returned from Okta by following the Okta documentation.

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: admin