# Identity Provider Settings

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

- [Identity Provider Client ID](#identity-provider-client-id)
- [Identity Provider Client Secret](#identity-provider-client-secret)
- [Identity Provider Client Secret File](#identity-provider-client-secret-file)
- [Identity Provider Name](#identity-provider-name)
- [Identity Provider Request Params](#identity-provider-request-params)
- [Identity Provider Scopes](#identity-provider-scopes)
- [Identity Provider URL](#identity-provider-url)
- [Identity Provider Polling Min/Max Delay](#identity-provider-polling-minmax-delay)

Pomerium uses the [**Hosted Authenticate Service**](https://www.pomerium.com/docs/capabilities/authentication.md) by default.

If you want to run Pomerium with a self-hosted authenticate service, include an [**identity provider**](https://www.pomerium.com/docs/integrations/user-identity/identity-providers.md) and [**authenticate service URL**](https://www.pomerium.com/docs/reference/service-urls.md#authenticate-service-url) in your configuration.

See [**Self-Hosted Authenticate Service**](https://www.pomerium.com/docs/capabilities/authentication.md) for more information.

## Supported identity providers

Pomerium supports all major single-sign on (SSO) identity providers. See the [identity providers](https://www.pomerium.com/docs/integrations/user-identity/identity-providers.md) 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

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_client_id` | `IDP_CLIENT_ID` | `string` | **required** (if self-hosting) |

#### Examples

```yaml
idp_client_id: idp_client_id
```

```bash
IDP_CLIENT_ID=idp_client_id
```

**Enterprise:**

**Kubernetes:**

See [`identityProvider.secret`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider)

## 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

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_client_secret` | `IDP_CLIENT_SECRET` | `string` | **required** (unless using [idp\_client\_secret\_file](#identity-provider-client-secret-file)) |

#### Examples

```yaml
idp_client_secret: idp_client_secret
```

```bash
IDP_CLIENT_SECRET=idp_client_secret
```

**Enterprise:**

**Kubernetes:**

See [`identityProvider.secret`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider) for more information

## 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](https://docs.docker.com/engine/swarm/secrets/).

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_client_secret_file` | `IDP_CLIENT_SECRET_FILE` | `string` | **required** (unless using [identity\_provider\_client\_secret](#identity-provider-client-secret)) |

#### Examples

```yaml
idp_client_secret_file: '/run/secrets/POMERIUM_CLIENT_SECRET'
```

```bash
IDP_CLIENT_SECRET_FILE='/run/secrets/POMERIUM_CLIENT_SECRET'
```

**Enterprise:**

`idp_client_secret_file` is a bootstrap configuration setting and is not configurable in the Console.

**Kubernetes:**

See [`identityProvider.secret`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider) for more information.

## 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`
- `hosted` (see [Hosted Authenticate Service])
- `oidc`
- `okta`
- `onelogin`
- `ping`

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_provider` | `IDP_PROVIDER` | `string` | **required** (if not using the [Hosted Authenticate Service]) |

#### Examples

```yaml
idp_provider: auth0
```

```bash
IDP_PROVIDER=github
```

**Enterprise:**

**Kubernetes:**

See [`identityProvider.provider`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider) for more information

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

Do not set the `client_id`, `response_type`, `redirect_uri`, `scope`, `state`, or `nonce` parameters here. Pomerium sets these itself as part of the OAuth 2.0 code flow, and overriding them will break sign-in. Use this setting only for additional parameters your identity provider supports (for example, `prompt` or `access_type`).

### How to configure

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_request_params` | `IDP_REQUEST_PARAMS` | `string` (map of key-value pairs) | **optional** |

#### Examples

```yaml
idp_request_params:
  foo: bar
  baz: qux
```

```bash
IDP_REQUEST_PARAMS='{"foo":"bar", "baz":"qux"}'
```

**Enterprise:**

**Kubernetes:**

See Kubernetes [`identityProvider.requestParams` and `identityProvider.requestParamsSecret`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider) for more information

### 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).

| **Provider** | **Default parameters** |
| :-- | :-- |
| `apple`\* | <pre>response\_mode: form\_post</pre> |
| `azure` | <pre>prompt: select\_account</pre> |
| `google` | <pre>prompt: select\_account consent<br />access\_type: offline</pre> |

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

For more information, see:

- [OIDC Request Parameters](https://openid.net/specs/openid-connect-basic-1_0.html#RequestParameters)
- [IANA OAuth Parameters](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml)
- [Microsoft Azure Request params](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow#request-an-authorization-code)
- [Google Authentication URI parameters](https://developers.google.com/identity/protocols/oauth2/openid-connect)

## Identity Provider Scopes

**Identity Provider Scopes** correspond to access privilege scopes as defined in [Section 3.3](https://www.rfc-editor.org/rfc/rfc6749#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.

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

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_scopes` | `IDP_SCOPES` | `string` (list) | **optional** (for built-in identity providers) |

#### Examples

```yaml
idp_scopes: openid, profile, offline_access, email
```

```bash
IDP_SCOPES=openid, profile, offline_access, email
```

**Enterprise:**

**Kubernetes:**

See Kubernetes [`identityProvider.scopes`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider) for more information

### Defaults

| **Defaults**     |
| :--------------- |
| `openid`         |
| `profile`        |
| `email`          |
| `offline_access` |

## Identity Provider URL

**Identity Provider URL** is the base path to an identity provider's [OpenID connect discovery document](https://openid.net/specs/openid-connect-discovery-1_0.html). An example Azure URL would be `https://login.microsoftonline.com/common/v2.0` for [their discovery document](https://login.microsoftonline.com/common/v2.0/.well-known/openid-configuration).

"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

**Core:**

| **Config file keys** | **Environment variables** | **Type** | **Usage** |
| :-- | :-- | :-- | :-- |
| `idp_provider_url` | `IDP_PROVIDER_URL` | `string` | **required** (depending on identity provider) |

#### Examples

```yaml
idp_provider_url: 'https://awesome-company.auth0.com'
```

```bash
IDP_PROVIDER_URL='https://awesome-company.auth0.com'
```

**Enterprise:**

**Kubernetes:**

See Kubernetes [`identityProvider.url`](https://www.pomerium.com/docs/deploy/k8s/reference.md#identityprovider) for more information

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

The `minimum_delay` and `maximum_delay` settings are an [**Enterprise Console**](https://www.pomerium.com/enterprise-sales/) feature, and are not configurable in Pomerium Core.

### 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]

### 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]

[hosted authenticate service]: https://www.pomerium.com/docs/capabilities/authentication.md#hosted-authenticate-service