netbird/dex
0
0
Fork 0
mirror of https://github.com/netbirdio/dex.git synced 2026-05-22 18:43:53 -07:00
Code Issues Packages Projects Releases Wiki Activity

[WIP] Removing .md files as a part of the Dex IdP Documentation migration. (#1810)

Browse Source 
* Removing .md files as a part of the Dex IdP Documentation migration.

https://github.com/dexidp/dex/issues/1761
https://github.com/dexidp/website/issues/2
Signed-off-by: Nate Waddington <nwaddington@cncf.io>

* Updating README.md links after .md files removal.

Signed-off-by: Nate Waddington <nwaddington@cncf.io>

* Updating URL as per PR feedback. dexidp.org -> dexidp.io

Signed-off-by: Nate Waddington <nwaddington@cncf.io>

* removing errant ")"

Signed-off-by: Nate Waddington <nwaddington@cncf.io>
This commit is contained in:
Nate W
2020-10-06 18:02:40 +02:00
committed by GitHub
parent d1f599dd32
commit 3f41b26fb9
42 changed files with 22 additions and 3424 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Documentation/README.md
+1
View File
@@ -0,0 +1 @@
These documents have moved to the [dexidp/website repo](https://github.com/dexidp/website).
Documentation/api.md
-146
View File
@@ -1,146 +0,0 @@
# The Dex API
Dex provides a [gRPC](http://www.grpc.io/) service for programmatic modification of dex's state.
The API is intended to expose hooks for management applications and is not expected to be used by most installations.
This document is an overview of how to interact with the API.
## Configuration
Admins that wish to expose the gRPC service must add the following entry to the dex config file. This option is off by default.
```yaml
grpc:
# Cannot be the same address as an HTTP(S) service.
addr: 127.0.0.1:5557
# Server certs. If TLS credentials aren't provided dex will run in plaintext (HTTP) mode.
tlsCert: /etc/dex/grpc.crt
tlsKey: /etc/dex/grpc.key
# Client auth CA.
tlsClientCA: /etc/dex/client.crt
# enable reflection
reflection: true
```
## Clients
gRPC is a suite of tools for generating client and server bindings from a common declarative language.
The canonical schema for Dex's API can be found in the source tree at [`api/v2/api.proto`](../api/v2/api.proto).
Go bindings are generated and maintained in the same directory for both public and internal use.
### Go
A Go project can import the API module directly, without having to import the entire project:
```bash
go get github.com/dexidp/dex/api/v2
```
The client then can be used as follows:
```go
package main
import (
"context"
"fmt"
"log"
"github.com/dexidp/dex/api/v2"
"google.golang.org/grpc"
"google.golang.org/grpc/credentials"
)
func newDexClient(hostAndPort, caPath string) (api.DexClient, error) {
creds, err := credentials.NewClientTLSFromFile(caPath, "")
if err != nil {
return nil, fmt.Errorf("load dex cert: %v", err)
}
conn, err := grpc.Dial(hostAndPort, grpc.WithTransportCredentials(creds))
if err != nil {
return nil, fmt.Errorf("dial: %v", err)
}
return api.NewDexClient(conn), nil
}
func main() {
client, err := newDexClient("127.0.0.1:5557", "/etc/dex/grpc.crt")
if err != nil {
log.Fatalf("failed creating dex client: %v ", err)
}
req := &api.CreateClientReq{
Client: &api.Client{
Id: "example-app",
Name: "Example App",
Secret: "ZXhhbXBsZS1hcHAtc2VjcmV0",
RedirectUris: []string{"http://127.0.0.1:5555/callback"},
},
}
if _, err := client.CreateClient(context.TODO(), req); err != nil {
log.Fatalf("failed creating oauth2 client: %v", err)
}
}
```
A clear working example of the Dex gRPC client for Go can be found [here](../examples/grpc-client/README.md).
### Other languages
To generate a client for your own project install [`protoc`](https://github.com/google/protobuf/releases),
install a protobuf generator for your project's language, and download the `api.proto` file.
Here is an example:
```bash
# Download api.proto for a given version.
$ DEX_VERSION=v2.24.0
$ wget https://raw.githubusercontent.com/dexidp/dex/${DEX_VERSION}/api/v2/api.proto
# Generate the client bindings.
$ protoc [YOUR LANG PARAMS] api.proto
```
Client programs can then be written using the generated code.
## Authentication and access control
The Dex API does not provide any authentication or authorization beyond TLS client auth.
Projects that wish to add access controls on top of the existing API should build apps which perform such checks.
For example to provide a "Change password" screen, a client app could use Dex's OpenID Connect flow to authenticate an end user,
then call Dex's API to update that user's password.
## dexctl?
Dex does not ship with a command line tool for interacting with the API.
Command line tools are useful but hard to version, easy to design poorly,
and expose another interface which can never be changed in the name of compatibility.
While the Dex team would be open to re-implementing `dexctl` for v2 a majority of the work is writing a design document,
not the actual programming effort.
## Why not REST or gRPC Gateway?
Between v1 and v2, Dex switched from REST to gRPC. This largely stemmed from problems generating documentation,
client bindings, and server frameworks that adequately expressed REST semantics.
While [Google APIs](https://github.com/google/apis-client-generator), [Open API/Swagger](https://openapis.org/),
and [gRPC Gateway](https://github.com/grpc-ecosystem/grpc-gateway) were evaluated,
they often became clunky when trying to use specific HTTP error codes or complex request bodies.
As a result, v2's API is entirely gRPC.
Many arguments _against_ gRPC cite short term convenience rather than production use cases.
Though this is a recognized shortcoming, Dex already implements many features for developer convenience.
For instance, users who wish to manually edit clients during testing can use the `staticClients` config field instead of the API.
Documentation/authproxy.md
-1
View File
@@ -1 +0,0 @@
This document has moved to [connectors/authproxy.md](connectors/authproxy.md).
Documentation/connectors/atlassian-crowd.md
-44
View File
@@ -1,44 +0,0 @@
Authentication through Atlassian Crowd
## Overview
Atlassian Crowd is a centralized identity management solution providing single sign-on and user identity.
Current connector uses request to [Crowd REST API](https://developer.atlassian.com/server/crowd/json-requests-and-responses/) endpoints:
* `/user` - to get user-info
* `/session` - to authenticate the user
Offline Access scope support provided with a new request to user authentication and user info endpoints.
## Configuration
To start using the Atlassian Crowd connector, firstly you need to register an application in your Crowd like specified in the [docs](https://confluence.atlassian.com/crowd/adding-an-application-18579591.html).
The following is an example of a configuration for dex `examples/config-dev.yaml`:
```yaml
connectors:
- type: atlassian-crowd
# Required field for connector id.
id: crowd
# Required field for connector name.
name: Crowd
config:
# Required field to connect to Crowd.
baseURL: https://crowd.example.com/crowd
# Credentials can be string literals or pulled from the environment.
clientID: $ATLASSIAN_CROWD_APPLICATION_ID
clientSecret: $ATLASSIAN_CROWD_CLIENT_SECRET
# Optional groups whitelist, communicated through the "groups" scope.
# If `groups` is omitted, all of the user's Crowd groups are returned when the groups scope is present.
# If `groups` is provided, this acts as a whitelist - only the user's Crowd groups that are in the configured `groups` below will go into the groups claim.
# Conversely, if the user is not in any of the configured `groups`, the user will not be authenticated.
groups:
- my-group
# Prompt for username field.
usernamePrompt: Login
# Optionally set preferred_username claim.
# If `preferredUsernameField` is omitted or contains an invalid option, the `preferred_username` claim will be empty.
# If `preferredUsernameField` is set, the `preferred_username` claim will be set to the chosen Crowd user attribute value.
# Possible choices are: "key", "name", "email"
preferredUsernameField: name
```
Documentation/connectors/authproxy.md
-138
View File
@@ -1,138 +0,0 @@
# Authenticating proxy
NOTE: This connector is experimental and may change in the future.
## Overview
The `authproxy` connector returns identities based on authentication which your
front-end web server performs. Dex consumes the `X-Remote-User` header set by
the proxy, which is then used as the user's email address.
__The proxy MUST remove any `X-Remote-*` headers set by the client, for any URL
path, before the request is forwarded to dex.__
The connector does not support refresh tokens or groups.
## Configuration
The `authproxy` connector is used by proxies to implement login strategies not
supported by dex. For example, a proxy could handle a different OAuth2 strategy
such as Slack. The connector takes no configuration other than a `name` and `id`:
```yaml
connectors:
# Slack login implemented by an authenticating proxy, not by dex.
- type: authproxy
id: slack
name: Slack
```
The proxy only needs to authenticate the user when they attempt to visit the
callback URL path:
```
( dex issuer URL )/callback/( connector id )?( url query )
```
For example, if dex is running at `https://auth.example.com/dex` and the connector
ID is `slack`, the callback URL would look like:
```
https://auth.example.com/dex/callback/slack?state=xdg3z6quhrhwaueo5iysvliqf
```
The proxy should login the user then return them to the exact URL (inlucing the
query), setting `X-Remote-User` to the user's email before proxying the request
to dex.
## Configuration example - Apache 2
The following is an example config file that can be used by the external
connector to authenticate a user.
```yaml
connectors:
- type: authproxy
id: myBasicAuth
name: HTTP Basic Auth
```
The authproxy connector assumes that you configured your front-end web server
such that it performs authentication for the `/dex/callback/myBasicAuth`
location and provides the result in the X-Remote-User HTTP header. The following
configuration will work for Apache 2.4.10+:
```
<Location /dex/>
ProxyPass "http://localhost:5556/dex/"
ProxyPassReverse "http://localhost:5556/dex/"
# Strip the X-Remote-User header from all requests except for the ones
# where we override it.
RequestHeader unset X-Remote-User
</Location>
<Location /dex/callback/myBasicAuth>
AuthType Basic
AuthName "db.debian.org webPassword"
AuthBasicProvider file
AuthUserFile "/etc/apache2/debian-web-pw.htpasswd"
Require valid-user
# Defense in depth: clear the Authorization header so that
# Debian Web Passwords never even reach dex.
RequestHeader unset Authorization
# Requires Apache 2.4.10+
RequestHeader set X-Remote-User expr=%{REMOTE_USER}@debian.org
ProxyPass "http://localhost:5556/dex/callback/myBasicAuth"
ProxyPassReverse "http://localhost:5556/dex/callback/myBasicAuth"
</Location>
```
## Full Apache2 setup
After installing your Linux distribution’s Apache2 package, place the following
virtual host configuration in e.g. `/etc/apache2/sites-available/sso.conf`:
```
<VirtualHost sso.example.net>
ServerName sso.example.net
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html
ErrorLog ${APACHE_LOG_DIR}/error.log
CustomLog ${APACHE_LOG_DIR}/access.log combined
<Location /dex/>
ProxyPass "http://localhost:5556/dex/"
ProxyPassReverse "http://localhost:5556/dex/"
# Strip the X-Remote-User header from all requests except for the ones
# where we override it.
RequestHeader unset X-Remote-User
</Location>
<Location /dex/callback/myBasicAuth>
AuthType Basic
AuthName "db.debian.org webPassword"
AuthBasicProvider file
AuthUserFile "/etc/apache2/debian-web-pw.htpasswd"
Require valid-user
# Defense in depth: clear the Authorization header so that
# Debian Web Passwords never even reach dex.
RequestHeader unset Authorization
# Requires Apache 2.4.10+
RequestHeader set X-Remote-User expr=%{REMOTE_USER}@debian.org
ProxyPass "http://localhost:5556/dex/callback/myBasicAuth"
ProxyPassReverse "http://localhost:5556/dex/callback/myBasicAuth"
</Location>
</VirtualHost>
```
Then, enable it using `a2ensite sso.conf`, followed by a restart of Apache2.
Documentation/connectors/bitbucketcloud.md
-38
View File
@@ -1,38 +0,0 @@
# Authentication through Bitbucket Cloud
## Overview
One of the login options for dex uses the Bitbucket OAuth2 flow to identify the end user through their Bitbucket account.
When a client redeems a refresh token through dex, dex will re-query Bitbucket to update user information in the ID Token. To do this, __dex stores a readonly Bitbucket access token in its backing datastore.__ Users that reject dex's access through Bitbucket will also revoke all dex clients which authenticated them through Bitbucket.
## Configuration
Register a new OAuth consumer with [Bitbucket](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) ensuring the callback URL is `(dex issuer)/callback`. For example if dex is listening at the non-root path `https://auth.example.com/dex` the callback would be `https://auth.example.com/dex/callback`.
The application requires the user to grant only the `Read Account` permission.
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: bitbucket-cloud
# Required field for connector id.
id: bitbucket-cloud
# Required field for connector name.
name: Bitbucket Cloud
config:
# Credentials can be string literals or pulled from the environment.
clientID: $BITBUCKET_CLIENT_ID
clientSecret: $BITBUCKET_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
# Optional teams whitelist, communicated through the "groups" scope.
# If `teams` is omitted, all of the user's Bitbucket teams are returned when the groups scope is present.
# If `teams` is provided, this acts as a whitelist - only the user's Bitbucket teams that are in the configured `teams` below will go into the groups claim. Conversely, if the user is not in any of the configured `teams`, the user will not be authenticated.
teams:
- my-team
# Optional parameter to include team groups.
# If enabled, the groups claim of dex id_token will looks like this:
# ["my_team", "my_team/administrators", "my_team/members"]
includeTeamGroups: true
```
Documentation/connectors/gitea.md
-29
View File
@@ -1,29 +0,0 @@
# Authentication through Gitea
## Overview
One of the login options for dex uses the Gitea OAuth2 flow to identify the end user through their Gitea account.
When a client redeems a refresh token through dex, dex will re-query Gitea to update user information in the ID Token. To do this, __dex stores a readonly Gitea access token in its backing datastore.__ Users that reject dex's access through Gitea will also revoke all dex clients which authenticated them through Gitea.
## Configuration
Register a new OAuth consumer with [Gitea](https://docs.gitea.io/en-us/oauth2-provider/) ensuring the callback URL is `(dex issuer)/callback`. For example if dex is listening at the non-root path `https://auth.example.com/dex` the callback would be `https://auth.example.com/dex/callback`.
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: gitea
# Required field for connector id.
id: gitea
# Required field for connector name.
name: Gitea
config:
# Credentials can be string literals or pulled from the environment.
clientID: $GITEA_CLIENT_ID
clientSecret: $GITEA_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
# optional, default = https://gitea.com
baseURL: https://gitea.com
```
Documentation/connectors/github.md
-150
View File
@@ -1,150 +0,0 @@
# Authentication through GitHub
## Overview
One of the login options for dex uses the GitHub OAuth2 flow to identify the end user through their GitHub account.
When a client redeems a refresh token through dex, dex will re-query GitHub to update user information in the ID Token. To do this, __dex stores a readonly GitHub access token in its backing datastore.__ Users that reject dex's access through GitHub will also revoke all dex clients which authenticated them through GitHub.
## Caveats
* A user must explicitly [request][github-request-org-access] an [organization][github-orgs] give dex [resource access][github-approve-org-access]. Dex will not have the correct permissions to determine if the user is in that organization otherwise, and the user will not be able to log in. This request mechanism is a feature of the GitHub API.
## Configuration
Register a new application with [GitHub][github-oauth2] ensuring the callback URL is `(dex issuer)/callback`. For example if dex is listening at the non-root path `https://auth.example.com/dex` the callback would be `https://auth.example.com/dex/callback`.
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: github
# Required field for connector id.
id: github
# Required field for connector name.
name: GitHub
config:
# Credentials can be string literals or pulled from the environment.
clientID: $GITHUB_CLIENT_ID
clientSecret: $GITHUB_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
# Optional organizations and teams, communicated through the "groups" scope.
#
# NOTE: This is an EXPERIMENTAL config option and will likely change.
#
# Legacy 'org' field. 'org' and 'orgs' cannot be used simultaneously. A user
# MUST be a member of the following org to authenticate with dex.
# org: my-organization
#
# Dex queries the following organizations for group information if the
# "groups" scope is provided. Group claims are formatted as "(org):(team)".
# For example if a user is part of the "engineering" team of the "coreos"
# org, the group claim would include "coreos:engineering".
#
# If orgs are specified in the config then user MUST be a member of at least one of the specified orgs to
# authenticate with dex.
#
# If neither 'org' nor 'orgs' are specified in the config and 'loadAllGroups' setting set to true then user
# authenticate with ALL user's Github groups. Typical use case for this setup:
# provide read-only access to everyone and give full permissions if user has 'my-organization:admins-team' group claim.
orgs:
- name: my-organization
# Include all teams as claims.
- name: my-organization-with-teams
# A white list of teams. Only include group claims for these teams.
teams:
- red-team
- blue-team
# Flag which indicates that all user groups and teams should be loaded.
loadAllGroups: false
# Optional choice between 'name' (default), 'slug', or 'both'.
#
# As an example, group claims for member of 'Site Reliability Engineers' in
# Acme organization would yield:
# - ['acme:Site Reliability Engineers'] for 'name'
# - ['acme:site-reliability-engineers'] for 'slug'
# - ['acme:Site Reliability Engineers', 'acme:site-reliability-engineers'] for 'both'
teamNameField: slug
# flag which will switch from using the internal GitHub id to the users handle (@mention) as the user id.
# It is possible for a user to change their own user name but it is very rare for them to do so
useLoginAsID: false
```
## GitHub Enterprise
Users can use their GitHub Enterprise account to login to dex. The following configuration can be used to enable a GitHub Enterprise connector on dex:
```yaml
connectors:
- type: github
# Required field for connector id.
id: github
# Required field for connector name.
name: GitHub
config:
# Required fields. Dex must be pre-registered with GitHub Enterprise
# to get the following values.
# Credentials can be string literals or pulled from the environment.
clientID: $GITHUB_CLIENT_ID
clientSecret: $GITHUB_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
# Optional organizations and teams, communicated through the "groups" scope.
#
# NOTE: This is an EXPERIMENTAL config option and will likely change.
#
# Legacy 'org' field. 'org' and 'orgs' cannot be used simultaneously. A user
# MUST be a member of the following org to authenticate with dex.
# org: my-organization
#
# Dex queries the following organizations for group information if the
# "groups" scope is provided. Group claims are formatted as "(org):(team)".
# For example if a user is part of the "engineering" team of the "coreos"
# org, the group claim would include "coreos:engineering".
#
# A user MUST be a member of at least one of the following orgs to
# authenticate with dex.
orgs:
- name: my-organization
# Include all teams as claims.
- name: my-organization-with-teams
# A white list of teams. Only include group claims for these teams.
teams:
- red-team
- blue-team
# Required ONLY for GitHub Enterprise.
# This is the Hostname of the GitHub Enterprise account listed on the
# management console. Ensure this domain is routable on your network.
hostName: git.example.com
# ONLY for GitHub Enterprise. Optional field.
# Used to support self-signed or untrusted CA root certificates.
rootCA: /etc/dex/ca.crt
```
### Generate TLS assets
Running Dex with HTTPS enabled requires a valid SSL certificate, and the API server needs to trust the certificate of the signing CA using the `--oidc-ca-file` flag.
For our example use case, the TLS assets can be created using the following command:
```
$ ./examples/k8s/gencert.sh
```
This will generate several files under the `ssl` directory, the important ones being `cert.pem` ,`key.pem` and `ca.pem`. The generated SSL certificate is for 'dex.example.com', although you could change this by editing `gencert.sh` if required.
### Run example client app with Github config
```
./bin/example-app --issuer-root-ca examples/k8s/ssl/ca.pem
```
1. Open browser to http://127.0.0.1:5555
2. Click Login
3. Select Log in with GitHub and grant access to dex to view your profile
[github-oauth2]: https://github.com/settings/applications/new
[github-orgs]: https://developer.github.com/v3/orgs/
[github-request-org-access]: https://help.github.com/articles/requesting-organization-approval-for-oauth-apps/
[github-approve-org-access]: https://help.github.com/articles/approving-oauth-apps-for-your-organization/
Documentation/connectors/gitlab.md
-39
View File
@@ -1,39 +0,0 @@
# Authentication through Gitlab
## Overview
GitLab is a web-based Git repository manager with wiki and issue tracking features, using an open source license, developed by GitLab Inc. One of the login options for dex uses the GitLab OAuth2 flow to identify the end user through their GitLab account. You can use this option with [gitlab.com](gitlab.com), GitLab community or enterprise edition.
When a client redeems a refresh token through dex, dex will re-query GitLab to update user information in the ID Token. To do this, __dex stores a readonly GitLab access token in its backing datastore.__ Users that reject dex's access through GitLab will also revoke all dex clients which authenticated them through GitLab.
## Configuration
Register a new application via `User Settings -> Applications` ensuring the callback URL is `(dex issuer)/callback`. For example if dex is listening at the non-root path `https://auth.example.com/dex` the callback would be `https://auth.example.com/dex/callback`.
The application requires the user to grant the `read_user` and `openid` scopes. The latter is required only if group membership is a desired claim.
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: gitlab
# Required field for connector id.
id: gitlab
# Required field for connector name.
name: GitLab
config:
# optional, default = https://gitlab.com
baseURL: https://gitlab.com
# Credentials can be string literals or pulled from the environment.
clientID: $GITLAB_APPLICATION_ID
clientSecret: $GITLAB_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
# Optional groups whitelist, communicated through the "groups" scope.
# If `groups` is omitted, all of the user's GitLab groups are returned when the groups scope is present.
# If `groups` is provided, this acts as a whitelist - only the user's GitLab groups that are in the configured `groups` below will go into the groups claim. Conversely, if the user is not in any of the configured `groups`, the user will not be authenticated.
groups:
- my-group
# flag which will switch from using the internal GitLab id to the users handle (@mention) as the user id.
# It is possible for a user to change their own user name but it is very rare for them to do so
useLoginAsID: false
```
Documentation/connectors/google.md
-60
View File
@@ -1,60 +0,0 @@
# Authentication through Google
## Overview
Dex is able to use Google's OpenID Connect provider as an authentication source.
The connector uses the same authentication flow as the OpenID Connect provider but adds Google specific features such as Hosted domain support and reading groups using a service account.
## Configuration
```yaml
connectors:
- type: google
id: google
name: Google
config:
# Connector config values starting with a "$" will read from the environment.
clientID: $GOOGLE_CLIENT_ID
clientSecret: $GOOGLE_CLIENT_SECRET
# Dex's issuer URL + "/callback"
redirectURI: http://127.0.0.1:5556/callback
# Google supports whitelisting allowed domains when using G Suite
# (Google Apps). The following field can be set to a list of domains
# that can log in:
#
# hostedDomains:
# - example.com
# The Google connector supports whitelisting allowed groups when using G Suite
# (Google Apps). The following field can be set to a list of groups
# that can log in:
#
# groups:
# - admins@example.com
# Google does not support the OpenID Connect groups claim and only supports
# fetching a user's group membership with a service account.
# This service account requires an authentication JSON file and the email
# of a G Suite admin to impersonate:
#
#serviceAccountFilePath: googleAuth.json
#adminEmail: super-user@example.com
```
## Fetching groups from Google
To allow Dex to fetch group information from Google, you will need to configure a service account for Dex to use.
This account needs Domain-Wide Delegation and permission to access the `https://www.googleapis.com/auth/admin.directory.group.readonly` API scope.
To get group fetching set up:
1. Follow the [instructions](https://developers.google.com/admin-sdk/directory/v1/guides/delegation) to set up a service account with Domain-Wide Delegation
- During service account creation, a JSON key file will be created that contains authentication information for the service account. This needs storing in a location accessible by Dex and you will set the `serviceAccountFilePath` to point at it.
- When delegating the API scopes to the service account, delegate the `https://www.googleapis.com/auth/admin.directory.group.readonly` scope and only this scope. If you delegate more scopes to the service account, it will not be able to access the API.
2. Enable the [Admin SDK](https://console.developers.google.com/apis/library/admin.googleapis.com/)
3. Add the `serviceAccountFilePath` and `adminEmail` configuration options to your Dex config.
- `serviceAccountFilePath` should point to the location of the service account JSON key file
- `adminEmail` should be the email of a G Suite super user. The service account you created earlier will impersonate this user when making calls to the admin API. A valid user should be able to retrieve a list of groups when [testing the API](https://developers.google.com/admin-sdk/directory/v1/reference/groups/list#try-it).
Documentation/connectors/kubelogin-activedirectory.md
-133
View File
@@ -1,133 +0,0 @@
# Integration kubelogin and Active Directory
## Overview
kubelogin is helper tool for kubernetes and oidc integration.
It makes easy to login Open ID Provider.
This document describes how dex work with kubelogin and Active Directory.
examples/config-ad-kubelogin.yaml is sample configuration to integrate Active Directory and kubelogin.
## Precondition
1. Active Directory
You should have Active Directory or LDAP has Active Directory compatible schema such as samba ad.
You may have user objects and group objects in AD. Please ensure TLS is enabled.
2. Install kubelogin
Download kubelogin from https://github.com/int128/kubelogin/releases.
Install it to your terminal.
## Getting started
### Generate certificate and private key
Create OpenSSL conf req.conf as follow:
```
[req]
req_extensions = v3_req
distinguished_name = req_distinguished_name
[req_distinguished_name]
[ v3_req ]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = dex.example.com
```
Please replace dex.example.com to your favorite hostname.
Generate certificate and private key by following command.
```console
$ openssl req -new -x509 -sha256 -days 3650 -newkey rsa:4096 -extensions v3_req -out openid-ca.pem -keyout openid-key.pem -config req.cnf -subj "/CN=kube-ca" -nodes
$ ls openid*
openid-ca.pem openid-key.pem
```
### Modify dex config
Modify following host, bindDN and bindPW in examples/config-ad-kubelogin.yaml.
```yaml
connectors:
- type: ldap
name: OpenLDAP
id: ldap
config:
host: ldap.example.com:636
# No TLS for this setup.
insecureNoSSL: false
insecureSkipVerify: true
# This would normally be a read-only user.
bindDN: cn=Administrator,cn=users,dc=example,dc=com
bindPW: admin0!
```
### Run dex
```
$ bin/dex serve examples/config-ad-kubelogin.yaml
```
### Configure kubernetes with oidc
Copy openid-ca.pem to /etc/ssl/certs/openid-ca.pem on master node.
Use the following flags to point your API server(s) at dex. `dex.example.com` should be replaced by whatever DNS name or IP address dex is running under.
```
--oidc-issuer-url=https://dex.example.com:32000/dex
--oidc-client-id=kubernetes
--oidc-ca-file=/etc/ssl/certs/openid-ca.pem
--oidc-username-claim=email
--oidc-groups-claim=groups
```
Then restart API server(s).
See https://kubernetes.io/docs/reference/access-authn-authz/authentication/ for more detail.
### Set up kubeconfig
Add a new user to the kubeconfig for dex authentication:
```console
$ kubectl config set-credentials oidc \
--exec-api-version=client.authentication.k8s.io/v1beta1 \
--exec-command=kubectl \
--exec-arg=oidc-login \
--exec-arg=get-token \
--exec-arg=--oidc-issuer-url=https://dex.example.com:32000/dex \
--exec-arg=--oidc-client-id=kubernetes \
--exec-arg=--oidc-client-secret=ZXhhbXBsZS1hcHAtc2VjcmV0 \
--exec-arg=--extra-scope=profile \
--exec-arg=--extra-scope=email \
--exec-arg=--extra-scope=groups \
--exec-arg=--certificate-authority-data=$(base64 -w 0 openid-ca.pem)
```
Please confirm `--oidc-issuer-url`, `--oidc-client-id`, `--oidc-client-secret` and `--certificate-authority-data` are same as values in config-ad-kubelogin.yaml.
Run the following command:
```console
$ kubectl --user=oidc cluster-info
```
It launches the browser and navigates it to http://localhost:8000.
Please log in with your AD account (eg. test@example.com) and password.
After login and grant, you can access the cluster.
You can switch the current context to dex authentication.
```console
$ kubectl config set-context --current --user=oidc
```
Documentation/connectors/ldap.md
-346
View File
@@ -1,346 +0,0 @@
# Authentication through LDAP
## Overview
The LDAP connector allows email/password based authentication, backed by a LDAP directory.
The connector executes two primary queries:
1. Finding the user based on the end user's credentials.
2. Searching for groups using the user entry.
## Getting started
The dex repo contains a basic LDAP setup using [OpenLDAP][openldap].
First start the LDAP server using docker-compose. This will run the OpenLDAP daemon in a Docker container, and seed it with an initial set of users.
```
cd examples/ldap
docker-compose up
```
This container is expected to print several warning messages which are normal. Once the server is up, run dex in another terminal.
```
./bin/dex serve examples/ldap/config-ldap.yaml
```
Then run the OAuth client in another terminal.
```
./bin/example-app
```
Go to [http://localhost:5555](http://localhost:5555), login and enter the username and password of the LDAP user: `janedoe@example.com`/`foo`. Add the "groups" scope as part of the initial redirect to add group information from the LDAP server.
## Security considerations
Dex attempts to bind with the backing LDAP server using the end user's _plain text password_. Though some LDAP implementations allow passing hashed passwords, dex doesn't support hashing and instead _strongly recommends that all administrators just use TLS_. This can often be achieved by using port 636 instead of 389, and administrators that choose 389 are actively leaking passwords.
Dex currently allows insecure connections because the project is still verifying that dex works with the wide variety of LDAP implementations. However, dex may remove this transport option, and _users who configure LDAP login using 389 are not covered by any compatibility guarantees with future releases._
## Configuration
User entries are expected to have an email attribute (configurable through `emailAttr`), and a display name attribute (configurable through `nameAttr`). `*Attr` attributes could be set to "DN" in situations where it is needed but not available elsewhere, and if "DN" attribute does not exist in the record.
For the purposes of configuring this connector, "DN" is case-sensitive and should always be capitalised.
The following is an example config file that can be used by the LDAP connector to authenticate a user.
```yaml
connectors:
- type: ldap
# Required field for connector id.
id: ldap
# Required field for connector name.
name: LDAP
config:
# Host and optional port of the LDAP server in the form "host:port".
# If the port is not supplied, it will be guessed based on "insecureNoSSL",
# and "startTLS" flags. 389 for insecure or StartTLS connections, 636
# otherwise.
host: ldap.example.com:636
# Following field is required if the LDAP host is not using TLS (port 389).
# Because this option inherently leaks passwords to anyone on the same network
# as dex, THIS OPTION MAY BE REMOVED WITHOUT WARNING IN A FUTURE RELEASE.
#
# insecureNoSSL: true
# If a custom certificate isn't provide, this option can be used to turn on
# TLS certificate checks. As noted, it is insecure and shouldn't be used outside
# of explorative phases.
#
# insecureSkipVerify: true
# When connecting to the server, connect using the ldap:// protocol then issue
# a StartTLS command. If unspecified, connections will use the ldaps:// protocol
#
# startTLS: true
# Path to a trusted root certificate file. Default: use the host's root CA.
rootCA: /etc/dex/ldap.ca
# A raw certificate file can also be provided inline.
# rootCAData: ( base64 encoded PEM file )
# The DN and password for an application service account. The connector uses
# these credentials to search for users and groups. Not required if the LDAP
# server provides access for anonymous auth.
# Please note that if the bind password contains a `$`, it has to be saved in an
# environment variable which should be given as the value to `bindPW`.
bindDN: uid=serviceaccount,cn=users,dc=example,dc=com
bindPW: password
# The attribute to display in the provided password prompt. If unset, will
# display "Username"
usernamePrompt: SSO Username
# User search maps a username and password entered by a user to a LDAP entry.
userSearch:
# BaseDN to start the search from. It will translate to the query
# "(&(objectClass=person)(uid=<username>))".
baseDN: cn=users,dc=example,dc=com
# Optional filter to apply when searching the directory.
filter: "(objectClass=person)"
# username attribute used for comparing user entries. This will be translated
# and combined with the other filter as "(<attr>=<username>)".
username: uid
# The following three fields are direct mappings of attributes on the user entry.
# String representation of the user.
idAttr: uid
# Required. Attribute to map to Email.
emailAttr: mail
# Maps to display name of users. No default value.
nameAttr: name
# Group search queries for groups given a user entry.
groupSearch:
# BaseDN to start the search from. It will translate to the query
# "(&(objectClass=group)(member=<user uid>))".
baseDN: cn=groups,dc=freeipa,dc=example,dc=com
# Optional filter to apply when searching the directory.
filter: "(objectClass=group)"
# Following list contains field pairs that are used to match a user to a group. It adds an additional
# requirement to the filter that an attribute in the group must match the user's
# attribute value.
userMatchers:
- userAttr: uid
groupAttr: member
# Represents group name.
nameAttr: name
```
The LDAP connector first initializes a connection to the LDAP directory using the `bindDN` and `bindPW`. It then tries to search for the given `username` and bind as that user to verify their password.
Searches that return multiple entries are considered ambiguous and will return an error.
## Example: Mapping a schema to a search config
Writing a search configuration often involves mapping an existing LDAP schema to the various options dex provides. To query an existing LDAP schema install the OpenLDAP tool `ldapsearch`. For `rpm` based distros run:
```
sudo dnf install openldap-clients
```
For `apt-get`:
```
sudo apt-get install ldap-utils
```
For smaller user directories it may be practical to dump the entire contents and search by hand.
```
ldapsearch -x -h ldap.example.org -b 'dc=example,dc=org' | less
```
First, find a user entry. User entries declare users who can login to LDAP connector using username and password.
```
dn: uid=jdoe,cn=users,cn=compat,dc=example,dc=org
cn: Jane Doe
objectClass: posixAccount
objectClass: ipaOverrideTarget
objectClass: top
gidNumber: 200015
gecos: Jane Doe
uidNumber: 200015
loginShell: /bin/bash
homeDirectory: /home/jdoe
mail: jane.doe@example.com
uid: janedoe
```
Compose a user search which returns this user.
```yaml
userSearch:
# The directory directly above the user entry.
baseDN: cn=users,cn=compat,dc=example,dc=org
filter: "(objectClass=posixAccount)"
# Expect user to enter "janedoe" when logging in.
username: uid
# Use the full DN as an ID.
idAttr: DN
# When an email address is not available, use another value unique to the user, like uid.
emailAttr: mail
nameAttr: gecos
```
Second, find a group entry.
```
dn: cn=developers,cn=groups,cn=compat,dc=example,dc=org
memberUid: janedoe
memberUid: johndoe
gidNumber: 200115
objectClass: posixGroup
objectClass: ipaOverrideTarget
objectClass: top
cn: developers
```
Group searches must match a user attribute to a group attribute. In this example, the search returns users whose uid is found in the group's list of memberUid attributes.
```yaml
groupSearch:
# The directory directly above the group entry.
baseDN: cn=groups,cn=compat,dc=example,dc=org
filter: "(objectClass=posixGroup)"
# The group search needs to match the "uid" attribute on
# the user with the "memberUid" attribute on the group.
userMatchers:
- userAttr: uid
groupAttr: memberUid
# Unique name of the group.
nameAttr: cn
```
To extract group specific information the `DN` can be used in the `userAttr` field.
```
# Top level object example.coma in LDIF file.
dn: dc=example,dc=com
objectClass: top
objectClass: dcObject
objectClass: organization
dc: example
```
The following is an example of a group query would match any entry with member=<user DN>:
```yaml
groupSearch:
# BaseDN to start the search from. It will translate to the query
# "(&(objectClass=group)(member=<user DN>))".
baseDN: cn=groups,cn=compat,dc=example,dc=com
# Optional filter to apply when searching the directory.
filter: "(objectClass=group)"
userMatchers:
- userAttr: DN # Use "DN" here not "uid"
groupAttr: member
nameAttr: name
```
There are cases when different types (objectClass) of groups use different attributes to keep a list of members. Below is an example of group query for such case:
```yaml
groupSearch:
baseDN: cn=groups,cn=compat,dc=example,dc=com
# Optional filter to search for different group types
filter: "(|(objectClass=posixGroup)(objectClass=group))"
# Use multiple user matchers so Dex will know which attribute names should be used to search for group members
userMatchers:
- userAttr: uid
groupAttr: memberUid
- userAttr: DN
groupAttr: member
nameAttr: name
```
## Example: Searching a FreeIPA server with groups
The following configuration will allow the LDAP connector to search a FreeIPA directory using an LDAP filter.
```yaml
connectors:
- type: ldap
id: ldap
name: LDAP
config:
# host and port of the LDAP server in form "host:port".
host: freeipa.example.com:636
# freeIPA server's CA
rootCA: ca.crt
userSearch:
# Would translate to the query "(&(objectClass=posixAccount)(uid=<username>))".
baseDN: cn=users,dc=freeipa,dc=example,dc=com
filter: "(objectClass=posixAccount)"
username: uid
idAttr: uid
# Required. Attribute to map to Email.
emailAttr: mail
# Entity attribute to map to display name of users.
groupSearch:
# Would translate to the query "(&(objectClass=group)(member=<user uid>))".
baseDN: cn=groups,dc=freeipa,dc=example,dc=com
filter: "(objectClass=group)"
userMatchers:
- userAttr: uid
groupAttr: member
nameAttr: name
```
If the search finds an entry, it will attempt to use the provided password to bind as that user entry.
[openldap]: https://www.openldap.org/
## Example: Searching a Active Directory server with groups
The following configuration will allow the LDAP connector to search a Active Directory using an LDAP filter.
```yaml
connectors:
- type: ldap
name: ActiveDirectory
id: ad
config:
host: ad.example.com:636
insecureNoSSL: false
insecureSkipVerify: true
bindDN: cn=Administrator,cn=users,dc=example,dc=com
bindPW: admin0!
usernamePrompt: Email Address
userSearch:
baseDN: cn=Users,dc=example,dc=com
filter: "(objectClass=person)"
username: userPrincipalName
idAttr: DN
emailAttr: userPrincipalName
nameAttr: cn
groupSearch:
baseDN: cn=Users,dc=example,dc=com
filter: "(objectClass=group)"
userMatchers:
- userAttr: DN
groupAttr: member
nameAttr: cn
```
Documentation/connectors/linkedin.md
-27
View File
@@ -1,27 +0,0 @@
# Authentication through LinkedIn
## Overview
One of the login options for dex uses the LinkedIn OAuth2 flow to identify the end user through their LinkedIn account.
When a client redeems a refresh token through dex, dex will re-query LinkedIn to update user information in the ID Token. To do this, __dex stores a readonly LinkedIn access token in its backing datastore.__ Users that reject dex's access through LinkedIn will also revoke all dex clients which authenticated them through LinkedIn.
## Configuration
Register a new application via `My Apps -> Create Application` ensuring the callback URL is `(dex issuer)/callback`. For example if dex is listening at the non-root path `https://auth.example.com/dex` the callback would be `https://auth.example.com/dex/callback`.
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: linkedin
# Required field for connector id.
id: linkedin
# Required field for connector name.
name: LinkedIn
config:
# Credentials can be string literals or pulled from the environment.
clientID: $LINKEDIN_APPLICATION_ID
clientSecret: $LINKEDIN_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
```
Documentation/connectors/microsoft.md
-118
View File
@@ -1,118 +0,0 @@
# Authentication through Microsoft
## Overview
One of the login options for dex uses the Microsoft OAuth2 flow to identify the
end user through their Microsoft account.
When a client redeems a refresh token through dex, dex will re-query Microsoft
to update user information in the ID Token. To do this, __dex stores a readonly
Microsoft access and refresh tokens in its backing datastore.__ Users that
reject dex's access through Microsoft will also revoke all dex clients which
authenticated them through Microsoft.
### Caveats
`groups` claim in dex is only supported when `tenant` is specified in Microsoft
connector config. In order for dex to be able to list groups on behalf of
logged in user, an explicit organization administrator consent is required. To
obtain the consent do the following:
- when registering dex application on https://apps.dev.microsoft.com add
an explicit `Directory.Read.All` permission to the list of __Delegated
Permissions__
- open the following link in your browser and log in under organization
administrator account:
`https://login.microsoftonline.com/<tenant>/adminconsent?client_id=<dex client id>`
## Configuration
Register a new application on https://apps.dev.microsoft.com via `Add an app`
ensuring the callback URL is `(dex issuer)/callback`. For example if dex
is listening at the non-root path `https://auth.example.com/dex` the callback
would be `https://auth.example.com/dex/callback`.
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: microsoft
# Required field for connector id.
id: microsoft
# Required field for connector name.
name: Microsoft
config:
# Credentials can be string literals or pulled from the environment.
clientID: $MICROSOFT_APPLICATION_ID
clientSecret: $MICROSOFT_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
```
`tenant` configuration parameter controls what kinds of accounts may be
authenticated in dex. By default, all types of Microsoft accounts (consumers
and organizations) can authenticate in dex via Microsoft. To change this, set
the `tenant` parameter to one of the following:
- `common`- both personal and business/school accounts can authenticate in dex
via Microsoft (default)
- `consumers` - only personal accounts can authenticate in dex
- `organizations` - only business/school accounts can authenticate in dex
- `<tenant uuid>` or `<tenant name>` - only accounts belonging to specific
tenant identified by either `<tenant uuid>` or `<tenant name>` can
authenticate in dex
For example, the following snippet configures dex to only allow business/school
accounts:
```yaml
connectors:
- type: microsoft
# Required field for connector id.
id: microsoft
# Required field for connector name.
name: Microsoft
config:
# Credentials can be string literals or pulled from the environment.
clientID: $MICROSOFT_APPLICATION_ID
clientSecret: $MICROSOFT_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
tenant: organizations
```
### Groups
When the `groups` claim is present in a request to dex __and__ `tenant` is
configured, dex will query Microsoft API to obtain a list of groups the user is
a member of. `onlySecurityGroups` configuration option restricts the list to
include only security groups. By default all groups (security, Office 365,
mailing lists) are included.
By default, dex resolve groups ids to groups names, to keep groups ids, you can
specify the configuration option `groupNameFormat: id`.
It is possible to require a user to be a member of a particular group in order
to be successfully authenticated in dex. For example, with the following
configuration file only the users who are members of at least one of the listed
groups will be able to successfully authenticate in dex:
```yaml
connectors:
- type: microsoft
# Required field for connector id.
id: microsoft
# Required field for connector name.
name: Microsoft
config:
# Credentials can be string literals or pulled from the environment.
clientID: $MICROSOFT_APPLICATION_ID
clientSecret: $MICROSOFT_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/callback
tenant: myorg.onmicrosoft.com
groups:
- developers
- devops
```
Also, `useGroupsAsWhitelist` configuration option, can restrict the groups
claims to include only the user's groups that are in the configured `groups`.
Documentation/connectors/oidc.md
-109
View File
@@ -1,109 +0,0 @@
# Authentication through an OpenID Connect provider
## Overview
Dex is able to use another OpenID Connect provider as an authentication source. When logging in, dex will redirect to the upstream provider and perform the necessary OAuth2 flows to determine the end users email, username, etc. More details on the OpenID Connect protocol can be found in [_An overview of OpenID Connect_](../openid-connect.md).
Prominent examples of OpenID Connect providers include Google Accounts, Salesforce, and Azure AD v2 ([not v1][azure-ad-v1]).
## Caveats
When using refresh tokens, changes to the upstream claims aren't propagated to the id_token returned by dex. If a user's email changes, the "email" claim returned by dex won't change unless the user logs in again. Progress for this is tracked in [issue #863][issue-863].
## Configuration
```yaml
connectors:
- type: oidc
id: google
name: Google
config:
# Canonical URL of the provider, also used for configuration discovery.
# This value MUST match the value returned in the provider config discovery.
#
# See: https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig
issuer: https://accounts.google.com
# Connector config values starting with a "$" will read from the environment.
clientID: $GOOGLE_CLIENT_ID
clientSecret: $GOOGLE_CLIENT_SECRET
# Dex's issuer URL + "/callback"
redirectURI: http://127.0.0.1:5556/callback
# Some providers require passing client_secret via POST parameters instead
# of basic auth, despite the OAuth2 RFC discouraging it. Many of these
# cases are caught internally, but some may need to uncomment the
# following field.
#
# basicAuthUnsupported: true
# Google supports whitelisting allowed domains when using G Suite
# (Google Apps). The following field can be set to a list of domains
# that can log in:
#
# hostedDomains:
# - example.com
# List of additional scopes to request in token response
# Default is profile and email
# Full list at https://github.com/dexidp/dex/blob/master/Documentation/custom-scopes-claims-clients.md
# scopes:
# - profile
# - email
# - groups
# Some providers return claims without "email_verified", when they had no usage of emails verification in enrollment process
# or if they are acting as a proxy for another IDP etc AWS Cognito with an upstream SAML IDP
# This can be overridden with the below option
# insecureSkipEmailVerified: true
# Groups claims (like the rest of oidc claims through dex) only refresh when the id token is refreshed
# meaning the regular refresh flow doesn't update the groups claim. As such by default the oidc connector
# doesn't allow groups claims. If you are okay with having potentially stale group claims you can use
# this option to enable groups claims through the oidc connector on a per-connector basis.
# This can be overridden with the below option
# insecureEnableGroups: true
# When enabled, the OpenID Connector will query the UserInfo endpoint for additional claims. UserInfo claims
# take priority over claims returned by the IDToken. This option should be used when the IDToken doesn't contain
# all the claims requested.
# https://openid.net/specs/openid-connect-core-1_0.html#UserInfo
# getUserInfo: true
# The set claim is used as user id.
# Claims list at https://openid.net/specs/openid-connect-core-1_0.html#Claims
# Default: sub
# userIDKey: nickname
# The set claim is used as user name.
# Default: name
# userNameKey: nickname
# For offline_access, the prompt parameter is set by default to "prompt=consent".
# However this is not supported by all OIDC providers, some of them support different
# value for prompt, like "prompt=login" or "prompt=none"
# promptType: consent
# Some providers return non-standard claims (eg. mail).
# Use claimMapping to map those claims to standard claims:
# https://openid.net/specs/openid-connect-core-1_0.html#Claims
# claimMapping can only map a non-standard claim to a standard one if it's not returned in the id_token.
claimMapping:
# The set claim is used as preferred username.
# Default: preferred_username
# preferred_username: other_user_name
# The set claim is used as email.
# Default: email
# email: mail
# The set claim is used as groups.
# Default: groups
# groups: "cognito:groups"
```
[oidc-doc]: openid-connect.md
[issue-863]: https://github.com/dexidp/dex/issues/863
[azure-ad-v1]: https://github.com/coreos/go-oidc/issues/133
Documentation/connectors/openshift.md
-79
View File
@@ -1,79 +0,0 @@
# Authentication using OpenShift
## Overview
Dex can make use of users and groups defined within OpenShift by querying the platform provided OAuth server.
## Configuration
### Creating an OAuth Client
Two forms of OAuth Clients can be utilized:
* [Using a Service Account as an OAuth Client](https://docs.openshift.com/container-platform/latest/authentication/using-service-accounts-as-oauth-client.html) (Recommended)
* [Registering An Additional OAuth Client](https://docs.openshift.com/container-platform/latest/authentication/configuring-internal-oauth.html#oauth-register-additional-client_configuring-internal-oauth)
#### Using a Service Account as an OAuth Client
OpenShift Service Accounts can be used as a constrained form of OAuth client. Making use of a Service Account to represent an OAuth Client is the recommended option as it does not require elevated privileged within the OpenShift cluster. Create a new Service Account or make use of an existing Service Account.
Patch the Service Account to add an annotation for location of the Redirect URI
```
oc patch serviceaccount <name> --type='json' -p='[{"op": "add", "path": "/metadata/annotations/serviceaccounts.openshift.io/oauth-redirecturi.dex", "value":"https:///<dex_url>/callback"}]'
```
The Client ID for a Service Account representing an OAuth Client takes the form `system:serviceaccount:<namespace>:<service_account_name>`
The Client Secret for a Service Account representing an OAuth Client is the long lived OAuth Token that is configued for the Service Account. Execute the following command to retrieve the OAuth Token.
```
oc serviceaccounts get-token <name>
```
#### Registering An Additional OAuth Client
Instead of using a constrained form of Service Account to represent an OAuth Client, an additional OAuthClient resource can be created.
Create a new OAuthClient resource similar to the following:
```yaml
kind: OAuthClient
apiVersion: oauth.openshift.io/v1
metadata:
name: dex
# The value that should be utilized as the `client_secret`
secret: "<clientSecret>"
# List of valid addresses for the callback. Ensure one of the values that are provided is `(dex issuer)/callback`
redirectURIs:
- "https:///<dex_url>/callback"
grantMethod: prompt
```
### Dex Configuration
The following is an example of a configuration for `examples/config-dev.yaml`:
```yaml
connectors:
- type: openshift
# Required field for connector id.
id: openshift
# Required field for connector name.
name: OpenShift
config:
# OpenShift API
issuer: https://api.mycluster.example.com:6443
# Credentials can be string literals or pulled from the environment.
clientID: $OPENSHIFT_OAUTH_CLIENT_ID
clientSecret: $OPENSHIFT_OAUTH_CLIENT_SECRET
redirectURI: http://127.0.0.1:5556/dex/
# Optional: Specify whether to communicate to OpenShift without validating SSL ceertificates
insecureCA: false
# Optional: The location of file containing SSL certificates to commmunicate to OpenShift
rootCA: /etc/ssl/openshift.pem
# Optional list of required groups a user mmust be a member of
groups:
- users
```
Documentation/connectors/saml.md
-115
View File
@@ -1,115 +0,0 @@
# Authentication through SAML 2.0
## Overview
The SAML provider allows authentication through the SAML 2.0 HTTP POST binding. The connector maps attribute values in the SAML assertion to user info, such as username, email, and groups.
The connector uses the value of the `NameID` element as the user's unique identifier which dex assumes is both unique and never changes. Use the `nameIDPolicyFormat` to ensure this is set to a value which satisfies these requirements.
Unlike some clients which will process unprompted AuthnResponses, dex must send the initial AuthnRequest and validates the response's InResponseTo value.
## Caveats
__The connector doesn't support refresh tokens__ since the SAML 2.0 protocol doesn't provide a way to requery a provider without interaction. If the "offline_access" scope is requested, it will be ignored.
The connector doesn't support signed AuthnRequests or encrypted attributes.
## Group Filtering
The SAML Connector supports providing a whitelist of SAML Groups to filter access based on, and when the `groupsattr` is set with a scope including groups, Dex will check for membership based on configured groups in the `allowedGroups` config setting for the SAML connector.
If `filterGroups` is set to true, any groups _not_ part of `allowedGroups` will be excluded.
## Configuration
```yaml
connectors:
- type: saml
# Required field for connector id.
id: saml
# Required field for connector name.
name: SAML
config:
# SSO URL used for POST value.
ssoURL: https://saml.example.com/sso
# CA to use when validating the signature of the SAML response.
ca: /path/to/ca.pem
# Dex's callback URL.
#
# If the response assertion status value contains a Destination element, it
# must match this value exactly.
#
# This is also used as the expected audience for AudienceRestriction elements
# if entityIssuer isn't specified.
redirectURI: https://dex.example.com/callback
# Name of attributes in the returned assertions to map to ID token claims.
usernameAttr: name
emailAttr: email
groupsAttr: groups # optional
# List of groups to filter access based on membership
# allowedGroups
# - Admins
# CA's can also be provided inline as a base64'd blob.
#
# caData: ( RAW base64'd PEM encoded CA )
# To skip signature validation, uncomment the following field. This should
# only be used during testing and may be removed in the future.
#
# insecureSkipSignatureValidation: true
# Optional: Manually specify dex's Issuer value.
#
# When provided dex will include this as the Issuer value during AuthnRequest.
# It will also override the redirectURI as the required audience when evaluating
# AudienceRestriction elements in the response.
entityIssuer: https://dex.example.com/callback
# Optional: Issuer value expected in the SAML response.
ssoIssuer: https://saml.example.com/sso
# Optional: Delimiter for splitting groups returned as a single string.
#
# By default, multiple groups are assumed to be represented as multiple
# attributes with the same name.
#
# If "groupsDelim" is provided groups are assumed to be represented as a
# single attribute and the delimiter is used to split the attribute's value
# into multiple groups.
groupsDelim: ", "
# Optional: Requested format of the NameID.
#
# The NameID value is is mapped to the user ID of the user. This can be an
# abbreviated form of the full URI with just the last component. For example,
# if this value is set to "emailAddress" the format will resolve to:
#
# urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress
#
# If no value is specified, this value defaults to:
#
# urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
#
nameIDPolicyFormat: persistent
```
A minimal working configuration might look like:
```yaml
connectors:
- type: saml
id: okta
name: Okta
config:
ssoURL: https://dev-111102.oktapreview.com/app/foo/exk91cb99lKkKSYoy0h7/sso/saml
ca: /etc/dex/saml-ca.pem
redirectURI: http://127.0.0.1:5556/dex/callback
usernameAttr: name
emailAttr: email
groupsAttr: groups
```
Documentation/custom-scopes-claims-clients.md
-100
View File
@@ -1,100 +0,0 @@
# Custom scopes, claims and client features
This document describes the set of OAuth2 and OpenID Connect features implemented by dex.
## Scopes
The following is the exhaustive list of scopes supported by dex:
| Name | Description |
| ---- | ------------|
| `openid` | Required scope for all login requests. |
| `email` | ID token claims should include the end user's email and if that email was verified by an upstream provider. |
| `profile` | ID token claims should include the username of the end user. |
| `groups` | ID token claims should include a list of groups the end user is a member of. |
| `federated:id` | ID token claims should include information from the ID provider. The token will contain the connector ID and the user ID assigned at the provider. |
| `offline_access` | Token response should include a refresh token. Doesn't work in combinations with some connectors, notability the [SAML connector][saml-connector] ignores this scope. |
| `audience:server:client_id:( client-id )` | Dynamic scope indicating that the ID token should be issued on behalf of another client. See the _"Cross-client trust and authorized party"_ section below. |
## Custom claims
Beyond the [required OpenID Connect claims][core-claims], and a handful of [standard claims][standard-claims], dex implements the following non-standard claims.
| Name | Description |
| ---- | ------------|
| `groups` | A list of strings representing the groups a user is a member of. |
| `federated_claims` | The connector ID and the user ID assigned to the user at the provider. |
| `email` | The email of the user. |
| `email_verified` | If the upstream provider has verified the email. |
| `name` | User's display name. |
The `federated_claims` claim has the following format:
```json
"federated_claims": {
"connector_id": "github",
"user_id": "110272483197731336751"
}
```
## Cross-client trust and authorized party
Dex has the ability to issue ID tokens to clients on behalf of other clients. In OpenID Connect terms, this means the ID token's `aud` (audience) claim being a different client ID than the client that performed the login.
For example, this feature could be used to allow a web app to generate an ID token on behalf of a command line tool:
```yaml
staticClients:
- id: web-app
redirectURIs:
- 'https://web-app.example.com/callback'
name: 'Web app'
secret: web-app-secret
- id: cli-app
redirectURIs:
- 'https://cli-app.example.com/callback'
name: 'Command line tool'
secret: cli-app-secret
# The command line tool lets the web app issue ID tokens on its behalf.
trustedPeers:
- web-app
```
Note that the command line tool must explicitly trust the web app using the `trustedPeers` field. The web app can then use the following scope to request an ID token that's issued for the command line tool.
```
audience:server:client_id:cli-app
```
The ID token claims will then include the following audience and authorized party:
```
{
"aud": "cli-app",
"azp": "web-app",
"email": "foo@bar.com",
// other claims...
}
```
## Public clients
Public clients are inspired by Google's [_"Installed Applications"_][installed-apps] and are meant to impose restrictions on applications that don't intend to keep their client secret private. Clients can be declared as public using the `public` config option.
```yaml
staticClients:
- id: cli-app
public: true
name: 'CLI app'
secret: cli-app-secret
```
Instead of traditional redirect URIs, public clients are limited to either redirects that begin with "http://localhost" or a special "out-of-browser" URL "urn:ietf:wg:oauth:2.0:oob". The latter triggers dex to display the OAuth2 code in the browser, prompting the end user to manually copy it to their app. It's the client's responsibility to either create a screen or a prompt to receive the code, then perform a code exchange for a token response.
When using the "out-of-browser" flow, an ID Token nonce is strongly recommended.
[saml-connector]: saml-connector.md
[core-claims]: https://openid.net/specs/openid-connect-core-1_0.html#IDToken
[standard-claims]: https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims
[installed-apps]: https://developers.google.com/api-client-library/python/auth/installed-app
Documentation/dev-become-a-maintainer.md
-17
View File
@@ -1,17 +0,0 @@
# Join the fun -- become a maintainer!
If a person or their company uses dex, has demonstrated an understanding of this
project (either by submitting PRs to dex or related projects such as Helm
charts), and the ability to work productively with the community, that person
can have write access to this repo. We want to be liberal with this privilege
and enable companies using dex to have a voice in its development.
The first 10 PRs by new maintainers must be approved by a maintainer from a
different company.
Access to https://quay.io/dexidp will be restricted to @srenatus, @rithujohn191
and @ericchiang to prevent new maintainers from being able to unilaterally push
images.
If you would like access, please email @ericchiang at ericchiang@google.com
stating your case or open a public issue. Come join the fun 😃
Documentation/dev-dependencies.md
-29
View File
@@ -1,29 +0,0 @@
# Managing dependencies
## Go modules
Dex uses [Go modules][go-modules] to manage its dependencies. Go 1.11 or higher is recommended. While Go 1.12 is expected to finalize the Go modules feature, with Go 1.11 you should [activate the Go modules feature][go-modules-activate] before interacting with Go modules.
Here is one way to activate the Go modules feature with Go 1.11.
```
export GO111MODULE=on # manually active module mode
```
You should become familiar with [module-aware `go get`][module-aware-go-get] as it can be used to add version-pinned dependencies out of band of the typical `go mod tidy -v` workflow.
## Adding dependencies
To add a new dependency to dex or update an existing one:
1. Make changes to dex's source code importing the new dependency.
2. You have at least three options as to how to update `go.mod` to reflect the new dependency:
* Run `go mod tidy -v`. This is a good option if you do not wish to immediately pin to a specific Semantic Version or commit.
* Run, for example, `go get <package-name>@<commit-hash>`. This is a good option when you want to immediately pin to a specific Semantic Version or commit.
* Manually update `go.mod`. If one of the two options above doesn't suit you, do this -- but very carefully.
3. Create a git commit to reflect your code changes.
[go-modules]: https://github.com/golang/go/wiki/Modules
[go-modules-activate]: https://github.com/golang/go/wiki/Modules#how-to-install-and-activate-module-support
[module-aware-go-get]: https://tip.golang.org/cmd/go/#hdr-Module_aware_go_get

Some files were not shown because too many files have changed in this diff Show More