Skip to main content

Identity Provider Settings

This reference covers all of Pomerium's Identity Provider Settings:

Note:

Pomerium uses the Hosted Authenticate Service by default.

If you want to run Pomerium with a self-hosted authenticate service, include an identity provider and authenticate service URL in your configuration.

See Self-Hosted Authenticate Service for more information.

Supported identity providers​

Pomerium supports all major single-sign on (SSO) identity providers. See the identity providers page for a list of supported SSO providers and guides to integrate each provider with Pomerium.

Pomerium can also integrate with any identity provider that supports OAuth 2.0 and OIDC protocols.

Identity Provider Client ID​

Identity Provider Client ID is the OAuth 2.0 Client Identifier retrieved from your identity provider. See your identity provider's documentation, and Pomerium's identity provider docs for details.

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_client_idIDP_CLIENT_IDstringrequired (if self-hosting)

Examples​

# config file key
idp_client_id: idp_client_id

# environment variable
IDP_CLIENT_ID=idp_client_id

Identity Provider Client Secret​

Identity Provider Client Secret is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and Pomerium's identity provider docs for details.

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_client_secretIDP_CLIENT_SECRETstringrequired (unless using idp_client_secret_file)

Examples​

# config file key
idp_client_secret: idp_client_secret

# environment variable
IDP_CLIENT_SECRET=idp_client_secret

Identity Provider Client Secret File​

Identity Provider Client Secret File is the OAuth 2.0 Secret Identifier retrieved from your identity provider. See your identity provider's documentation, and Pomerium's identity provider docs for details.

The identity provider client secret file points to a file containing the secret. This is useful when deploying in environments that provide secret management like Docker Swarm.

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_client_secret_fileIDP_CLIENT_SECRET_FILEstringrequired (unless using identity_provider_client_secret)

Examples​

# config file key
idp_client_secret_file: '/run/secrets/POMERIUM_CLIENT_SECRET'

# environment variable
IDP_CLIENT_SECRET_FILE='/run/secrets/POMERIUM_CLIENT_SECRET'

Identity Provider Name​

Identity Provider Name is the short-hand name of a built-in OpenID Connect (OIDC) identity provider used for authentication.

See identity provider for details.

The supported values for this setting are:

  • apple
  • auth0
  • azure
  • cognito
  • github
  • gitlab
  • google
  • oidc
  • okta
  • onelogin
  • ping

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_providerIDP_PROVIDERstringrequired (if self-hosting)

Examples​

# config file key
idp_provider: auth0

# environment variable
IDP_PROVIDER=github

Identity Provider Request Params​

Identity Provider Request Params lists the parameters you want to include as part of a sign-in request using the OAuth 2.0 code flow.

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_request_paramsn/astring (map of key-value pairs)optional

Defaults​

Pomerium includes some default parameters for specific identity providers. Setting this configuration option will replace these default parameters. To remove the default parameters entirely, set this option to an empty map* (e.g. idp_request_params: {} in the config file).

ProviderDefault parameters
apple*
response_mode: form_post
azure
prompt: select_account
google
prompt: select_account consent
access_type: offline
note

*The default parameters for apple behave differently; any values set using this configuration option will be merged with the default parameters.

Examples​

# config file key
idp_request_params:
  client_id: client_id
  response_type: response_type
  redirect_uri: redirect_uri

For more information, see:

Identity Provider Scopes​

Identity Provider Scopes correspond to access privilege scopes as defined in Section 3.3 of OAuth 2.0 RFC6749.

The scopes associated with Access Tokens determine what resources will be available when they are used to access OAuth 2.0 protected endpoints.

danger

If you are using a built-in provider, you probably don't want to set customized scopes.

Some providers, like Amazon Cognito, do not support the offline_access scope.

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_scopesIDP_SCOPESstring (list)optional (for built-in identity providers)

Defaults​

Defaults
openid
profile
email
offline_access

Examples​

# config file key
idp_scopes: openid, profile, offline_access, email

# environment variable
IDP_SCOPES=openid, profile, offline_access, email

Identity Provider URL​

Identity Provider URL is the base path to an identity provider's OpenID connect discovery document. An example Azure URL would be https://login.microsoftonline.com/common/v2.0 for their discovery document.

"Base path" is defined as the section of the URL to the discovery document up to (but not including) /.well-known/openid-configuration.

How to configure​

Config file keysEnvironment variablesTypeUsage
idp_provider_urlIDP_PROVIDER_URLstringrequired (depending on identity provider)

Examples​

# config file key
idp_provider_url: 'https://awesome-company.auth0.com'

# environment variable
IDP_PROVIDER_URL='https://awesome-company.auth0.com'

Identity Provider Polling Min/Max Delay​

Identity provider Polling Minimum Delay and Polling Maximum Delay settings define the minimum and maximum delay times between requests to the identity provider data source.

A job starts with the minimum delay intervals. If the job fails to complete within the minimum delay period, it will be interrupted and the job will restart. If the job is interrupted due to timeout or an error, it will restart with increasing intervals up to the maximum delay period.

How to configure​

Set the Identity Provider Max/Min Delay settings in the Console:

Set IdP minimum and maximum polling delay settings in the console

note

The minimum_delay and maximum_delay settings are an Enterprise Console feature, and are not configurable in Pomerium Core.

Defaults​

While minimum and maximum polling time defaults are set for any Console installation, the required durations will vary depending on your identity provider and the size or your organization's directory.

If the job fails before completing, increase the minimum and maximum durations until the job completes.

Keep in mind that large directories may take several hours to complete.

Monitor directory sync​

To determine the appropriate durations required to sync your directory, check your Console logs and the Last Error and Request Duration sections of the Console GUI.

Last error​

You can check if an error interrupted a job by checking External Data > Last Error.

Check for external data sync errors

Request duration​

You can also check External Data > Metrics to view request durations.

Monitor request duration