@@ -45,11 +45,8 @@ The configuration for the local connector is always the same; it looks like this
This connector config lets users authenticate with other OIDC providers. In addition to `id` and `type`, the `oidc` connector takes the following additional fields:
* issuerURL: a `string`. The base URL for the OIDC provider. Should be a URL with an `https` scheme.
* clientID: a `string`. The OIDC client ID.
* clientSecret: a `string`. The OIDC client secret.
* trustedEmailProvider: a `boolean`. If true dex will trust the email address claims from this provider and not require that users verify their emails.
In order to use the `oidc` connector you must register dex as an OIDC client; this mechanism is different from provider to provider. For Google, follow the instructions at their [developer site](https://developers.google.com/identity/protocols/OpenIDConnect?hl=en). Regardless of your provider, registering your client will also provide you with the client ID and secret.
...
...
@@ -80,7 +77,6 @@ Here's what a `oidc` connector looks like configured for authenticating with Goo
This connector config lets users authenticate through [GitHub](https://github.com/). In addition to `id` and `type`, the `github` connector takes the following additional fields:
* clientID: a `string`. The GitHub OAuth application client ID.
* clientSecret: a `string`. The GitHub OAuth application client secret.
To begin, register an OAuth application with GitHub through your, or your organization's [account settings](ttps://github.com/settings/applications/new). To register dex as a client of your GitHub application, enter dex's redirect URL under 'Authorization callback URL':
...
...
@@ -109,7 +105,6 @@ The `github` connector requests read only access to user's email through the [`u
This connector config lets users authenticate through [Bitbucket](https://bitbucket.org/). In addition to `id` and `type`, the `bitbucket` connector takes the following additional fields:
* clientID: a `string`. The Bitbucket OAuth consumer client ID.
* clientSecret: a `string`. The Bitbucket OAuth consumer client secret.
To begin, register an OAuth consumer with Bitbucket through your, or your teams's management page. Follow the documentation at their [developer site](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html).
...
...
@@ -136,83 +131,85 @@ Here's an example of a `bitbucket` connector; the clientID and clientSecret shou
### `ldap` connector
The `ldap` connector allows email/password based authentication hosted by dex, backed by a LDAP directory.
Authentication is performed by binding to the configured LDAP server using the user supplied credentials. Successfull bind equals authenticated user.
The `ldap` connector allows email/password based authentication hosted by dex, backed by a LDAP directory. The connector can operate in two primary modes:
Optionally the connector can be configured to search before authentication. The entryDN found will be used to bind to the LDAP server.
1. Binding against a specific directory using the end user's credentials.
2. Searching a directory for a entry using a service account then attempting to bind with the user's credentials.
This feature must be enabled to get supplementary information from the directory (ID, Name, Email). This feature can also be used to limit access to the service.
User entries are expected to have an email attribute (configurable through "emailAttribute"), and optionally a display name attribute (configurable through "nameAttribute").
Example use case: Allow your users to log in with e-mail address as username instead of the identification string in your DNs (typically username).
___NOTE:___ Users must register with dex at first login. For this to work you have to run dex-worker with --enable-registration.
___NOTE:___ Dex currently requires user registration with the dex system, even if that user already has an account with the upstream LDAP system. Installations that use this connector are recommended to provide the "--enable-automatic-registration" flag.
In addition to `id` and `type`, the `ldap` connector takes the following additional fields:
* serverHost: a `string`. The hostname for the LDAP Server.
* serverPort: a `unsigned 16-bit integer`. The port for the LDAP Server.
* timeout: `duration in milliseconds`. The timeout for connecting to and reading from LDAP Server in Milliseconds. Default: `60000` (60 Seconds)
* host: a `string`. The host and port of the LDAP server in form "host:port".
* useTLS: a `boolean`. Whether the LDAP Connector should issue a StartTLS after successfully connecting to the LDAP Server.
* useSSL: a `boolean`. Whether the LDAP Connector should expect the connection to be encrypted, typically used with ldaps port (636/tcp).
* certFile: a `string`. Optional Certificate to present to LDAP server.
* keyFile: a `string`. Key associated with Certificate specified in `certFile`.
* certFile: a `string`. Optional path to x509 client certificate to present to LDAP server.
* keyFile: a `string`. Key associated with x509 client cert specified in `certFile`.
* caFile: a `string`. Filename for PEM-file containing the set of root certificate authorities that the LDAP client use when verifying the server certificates. Default: use the host's root CA set.
* skipCertVerification: a `boolean`. Skip server certificate chain verification.
* maxIdleConn: a `integer`. Maximum number of idle LDAP Connections to keep in connection pool. Default: `5`
* baseDN: a `string`. Base DN from which Bind DN is built and searches are based.
* nameAttribute: a `string`. Attribute to map to Name. Default: `cn`
* emailAttribute: a `string`. Attribute to map to Email. Default: `mail`
* nameAttribute: a `string`. Entity attribute to map to display name of users. Default: `cn`
* emailAttribute: a `string`. Required. Attribute to map to Email. Default: `mail`
* searchBeforeAuth: a `boolean`. Perform search for entryDN to be used for bind.
* searchFilter: a `string`. Filter to apply to search. Variable substititions: `%u` User supplied username/e-mail address. `%b` BaseDN. Searches that return multiple entries are considered ambiguous and will return an error.
* searchScope: a `string`. Scope of the search. `base|one|sub`. Default: `one`
* searchBindDN: a `string`. DN to bind as for search operations.
* searchBindPw: a `string`. Password for bind for search operations.
* bindTemplate: a `string`. Template to build bindDN from user supplied credentials. Variable subtitutions: `%u` User supplied username/e-mail address. `%b` BaseDN. Default: `uid=%u,%b`.
* searchFilter: a `string`. Filter to apply to search. Variable substititions: `%u` User supplied username/e-mail address. `%b` BaseDN.
### Example: Authenticating against a specific directory
* searchScope: a `string`. Scope of the search. `base|one|sub`. Default: `one`
To authenticate against a specific LDAP directory level, use the "bindTemplate" field. This string describes how to map a username to a LDAP entity.
* searchBindDN: a `string`. DN to bind as for search operations.
* searchBindPw: a `string`. Password for bind for search operations.
"bindTemplate" is a format string. `%d` is replaced by the value of "baseDN" and `%u` is replaced by the username attempting to login. In this case if a user "janedoe" attempts to authenticate, the bindTemplate will be expanded to:
* bindTemplate: a `string`. Template to build bindDN from user supplied credentials. Variable subtitutions: `%u` User supplied username/e-mail address. `%b` BaseDN. Default: `uid=%u,%b` ___NOTE:___ This is not used when searchBeforeAuth is enabled.
The connector then attempts to bind as this entry using the password provided by the end user.
* trustedEmailProvider: a `boolean`. If true dex will trust the email address claims from this provider and not require that users verify their emails.
### Example: Searching the directory
Here's an example of a `ldap` connector;
The following configuration will search a directory using an LDAP filter. With FreeIPA
"searchFilter" is a format string expanded in a similar manner as "bindTemplate". If the user "janedoe" attempts to authenticate, the connector will run the following query using the service account credentials.
```
(&(objectClass=person)(uid=janedoe))
```
If the search finds an entry, it will attempt to use the provided password to bind as that entry.
__NOTE__: Searches that return multiple entries will return an error.
## Setting the Configuration
To set a connectors configuration in dex, put it in some temporary file, then use the dexctl command to upload it to dex: