dex README

The project's README from github.com/dexidp/dex. As one markdown file: README.md.

dex - A federated OpenID Connect provider

GitHub Workflow Status OpenSSF Scorecard OpenSSF Best Practices Go Report Card LFX Health Score

logo

Dex is an identity service that uses OpenID Connect to drive authentication for other apps.

Dex acts as a portal to other identity providers through "connectors." This lets dex defer authentication to LDAP servers, SAML providers, or established identity providers like GitHub, Google, and Active Directory. Clients write their authentication logic once to talk to dex, then dex handles the protocols for a given backend.

ID Tokens

ID Tokens are an OAuth2 extension introduced by OpenID Connect and dex's primary feature. ID Tokens are JSON Web Tokens (JWTs) signed by dex and returned as part of the OAuth2 response that attests to the end user's identity. An example JWT might look like:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjlkNDQ3NDFmNzczYjkzOGNmNjVkZDMyNjY4NWI4NjE4MGMzMjRkOTkifQ.eyJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjU1NTYvZGV4Iiwic3ViIjoiQ2djeU16UXlOelE1RWdabmFYUm9kV0kiLCJhdWQiOiJleGFtcGxlLWFwcCIsImV4cCI6MTQ5Mjg4MjA0MiwiaWF0IjoxNDkyNzk1NjQyLCJhdF9oYXNoIjoiYmk5NmdPWFpTaHZsV1l0YWw5RXFpdyIsImVtYWlsIjoiZXJpYy5jaGlhbmdAY29yZW9zLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJncm91cHMiOlsiYWRtaW5zIiwiZGV2ZWxvcGVycyJdLCJuYW1lIjoiRXJpYyBDaGlhbmcifQ.OhROPq_0eP-zsQRjg87KZ4wGkjiQGnTi5QuG877AdJDb3R2ZCOk2Vkf5SdP8cPyb3VMqL32G4hLDayniiv8f1_ZXAde0sKrayfQ10XAXFgZl_P1yilkLdknxn6nbhDRVllpWcB12ki9vmAxklAr0B1C4kr5nI3-BZLrFcUR5sQbxwJj4oW1OuG6jJCNGHXGNTBTNEaM28eD-9nhfBeuBTzzO7BKwPsojjj4C9ogU4JQhGvm_l4yfVi0boSx8c0FX3JsiB0yLa1ZdJVWVl9m90XmbWRSD85pNDQHcWZP9hR6CMgbvGkZsgjG32qeRwUL_eNkNowSBNWLrGNPoON1gMg

ID Tokens contains standard claims assert which client app logged the user in, when the token expires, and the identity of the user.

{
  "iss": "http://127.0.0.1:5556/dex",
  "sub": "CgcyMzQyNzQ5EgZnaXRodWI",
  "aud": "example-app",
  "exp": 1492882042,
  "iat": 1492795642,
  "at_hash": "bi96gOXZShvlWYtal9Eqiw",
  "email": "[email protected]",
  "email_verified": true,
  "groups": [
    "admins",
    "developers"
  ],
  "name": "Jane Doe"
}

Because these tokens are signed by dex and contain standard-based claims other services can consume them as service-to-service credentials. Systems that can already consume OpenID Connect ID Tokens issued by dex include:

For details on how to request or validate an ID Token, see "Writing apps that use dex".

Kubernetes and Dex

Dex runs natively on top of any Kubernetes cluster using Custom Resource Definitions and can drive API server authentication through the OpenID Connect plugin. Clients, such as kubelogin and kubectl, can act on behalf of users who can login to the cluster through any identity provider dex supports.

Connectors

When a user logs in through dex, the user's identity is usually stored in another user-management system: a LDAP directory, a GitHub org, etc. Dex acts as a shim between a client app and the upstream identity provider. The client only needs to understand OpenID Connect to query dex, while dex implements an array of protocols for querying other user-management systems.

A "connector" is a strategy used by dex for authenticating a user against another identity provider. Dex implements connectors that target specific platforms such as GitHub, LinkedIn, and Microsoft as well as established protocols like LDAP and SAML.

Depending on the connectors limitations in protocols can prevent dex from issuing refresh tokens or returning group membership claims. For example, because SAML doesn't provide a non-interactive way to refresh assertions, if a user logs in through the SAML connector dex won't issue a refresh token to its client. Refresh token support is required for clients that require offline access, such as kubectl.

Dex implements the following connectors:

Name supports refresh tokens supports groups claim supports preferred_username claim status notes
LDAP yes yes yes stable
GitHub yes yes yes stable
SAML 2.0 no yes no stable WARNING: Unmaintained and likely vulnerable to auth bypasses (#1884)
GitLab yes yes yes beta
OpenID Connect yes yes yes beta Includes Salesforce, Azure, etc.
OAuth 2.0 no yes yes alpha
Google yes yes yes alpha
LinkedIn yes no no beta
Microsoft yes yes no beta
AuthProxy no yes no alpha Authentication proxies such as Apache2 mod_auth, etc.
Bitbucket Cloud yes yes no alpha
OpenShift yes yes no alpha
Atlassian Crowd yes yes yes * beta preferred_username claim must be configured through config
Gitea yes no yes beta
OpenStack Keystone yes yes no alpha

Stable, beta, and alpha are defined as:

All changes or deprecations of connector features will be announced in the release notes.

Documentation

See the official documentation for getting started, configuration, and usage guides.

Reporting a vulnerability

Please see our security policy for details about reporting vulnerabilities.

Getting help

Contributing

Please see CONTRIBUTING.md for development setup, guidelines, and how to submit pull requests.

License

The project is licensed under the Apache License, Version 2.0.

dex (dexidp/dex)

Searching Database…

11.2K ·GitHub
这是什么?Dex 是一个身份服务,通过 OpenID Connect 为其他应用提供登录认证。借助可插拔的“连接器”(connector),它可以把登录委托给 LDAP、SAML 或 GitHub、Google 这类提供商,这样客户端只需写一次认证逻辑。
那 dex 是一个完整的身份产品,还是我已有提供商前面的一层?它是一个联合认证的 OIDC 提供商:用户身份通常存放在上游的 LDAP 目录、GitHub 组织或 SAML 环境中,dex 充当你的应用与该提供商之间的中间层,签发客户端实际使用的已签名令牌(token)。
我怎样才能把 dex 跑起来?它是一个 Go 服务器:用 make 构建,或者运行官方发布的 Docker 镜像。README 指向官方文档,里面有入门、配置和使用指南。
它可以对接哪些身份提供商?15 个连接器:LDAP、GitHub、GitLab、Gitea、SAML 2.0、通用 OpenID Connect(覆盖 Salesforce、Azure 等类似提供商)、OAuth 2.0、Google、LinkedIn、Microsoft、AuthProxy、Bitbucket Cloud、OpenShift、Atlassian Crowd 和 OpenStack Keystone。
这些连接器都同样可靠吗?不是。每个连接器都分为 stable、beta 或 alpha 三个等级,功能也各不相同——比如 SAML 2.0 虽然是 stable 状态,却带有警告说明它无人维护,可能存在认证绕过漏洞。
dex 能跑在哪里——必须用 Kubernetes 吗?Kubernetes 是主打场景但并非必需:dex 通过 CRD 可以原生运行在任何集群上,并能通过 OIDC 插件接管 API 服务器的认证。kubectl 和 kubelogin 这类客户端随后就能代表通过任意已接入提供商登录的用户执行操作。
登录成功后,应用实际能拿到什么?一个 ID Token——这是 dex 的核心功能。它是由 dex 签名的 JSON Web Token(JWT),带有标准声明(claims):是哪个客户端应用为用户完成登录、令牌何时过期、以及用户是谁。其他服务也可以把这些令牌当作服务间调用的凭证来用;Kubernetes 和 AWS STS 已经在这么做了。
每次登录都会让我的应用拿到刷新令牌(refresh token)吗?不会——上游协议的限制会传递下来。SAML 没有非交互式的方式来刷新断言(assertion),所以对于 SAML 登录,dex 不会签发刷新令牌;而 LDAP、GitHub、GitLab 和大多数其他连接器都可以。像 kubectl 这种需要离线访问(offline access)的场景,就得用支持刷新的连接器。
那我为什么要在 LDAP 或 GitHub 前面加一层 dex?因为客户端只需针对 dex 编写一次认证逻辑,而由 dex 来实现各个后端的协议——要更换或新增提供商,只需修改 dex 的配置,而不用重写每一个应用。
它能对接 Azure AD 或 Salesforce 吗?可以,通过通用 OpenID Connect 连接器(beta),README 中说它覆盖 Salesforce 和 Azure 这类提供商;另有一个通用 OAuth 2.0 连接器,处于 alpha 阶段。
What are similar projects?casdoor, kratos, hydra, zitadel, authentik, keycloak, cas, casbin
Creator
dexidp
Size
28.7 MB
Stars
11.2K
Age
11y
Commits · 90 Days