Konvoy DocumentationAll Kubernetes clusters have two categories of users: service accounts and normal users. Kubernetes manages authentication for service accounts, but the cluster adminstrator, or a separate service, manages authentication for normal users.
Konvoy configures the cluster to use OpenID Connect (OIDC), a popular and extensible user authentication method, and installs Dex, a popular, open-source software that integrates your existing Identity Providers with Kubernetes.
To begin, set up an Identity Provider with Dex, then use OIDC as the Authentication method.
Identity Provider
An Identity Provider (IdP) is a service that lets you manage identity information for users, including groups. A Konvoy cluster uses Dex as its IdP. Dex, in turn, delegates to one or more external IdPs.
If you use already use one or more of the following IdPs, you can configure Dex to use them:
| 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 | |
| GitLab | yes | yes | yes | beta | |
| OpenID Connect | yes | yes | yes | beta | Includes Salesforce, Azure, etc. |
| yes | yes | yes | alpha | ||
| yes | no | no | beta | ||
| Microsoft | yes | yes | no | beta | |
| AuthProxy | no | no | no | alpha | Authentication proxies such as Apache2 mod_auth, etc. |
| Bitbucket Cloud | yes | yes | no | alpha | |
| OpenShift | no | yes | no | stable |
NOTE: These are the Identity Providers supported by Dex 2.22.0, the version used by Konvoy.
Identity Provider Procedures
Set up an identity provider with Dex
Authentication
OpenID Connect is an extension of the OAuth2 authentication protocol. As required by OAuth2, the client must be registered with the IdP; in this case, Dex. Do this by passing the name of the application and a callback/redirect uri. These handle the processing of the OpenID token after the user authenticates successfully. Upon registration Dex returns a “client_id” and a “secret”. Authentication requests use these, between the client and Dex, to identify the client.
Users access Konvoy in two ways:
- To interact with Kubernetes API, usually through
kubectl. - To interact with the Konvoy Ops Portal, which has GUI dashboards for Konvoy, Kommander, Prometheus, Kibana, etc.
In Konvoy, Dex comes pre-configured with a client for the above access use cases. The clients talk to Dex for authentication. Dex talks to the configured IdP (Identity Provider, for example LDAP, SAML etc.) to perform the actual task of authenticating the user. If the user authenticates successfully Dex pulls the user’s information from the IdP and forms an OpenID token. This token contains this information and returns it to the respective client’s callback url. The client or end user uses this token for communicating with the Konvoy Ops Portal or Kubernetes API respectively.
This figure illustrates these components and their interaction at a high level:
Authentication Procedures
Users & Groups
Users & Groups Procedures
Troubleshoot
Set up an identity provider with Dex
How to set up an identity provider with Dex…Read More
Generate a Client Access Token
How to generate a Client Access Token…Read More
Change the Group Prefix
Access and change the OIDC Group Prefix…Read More
Change the Access Token Lifetime
Changing the Access Token Lifetime.…Read More
Troubleshoot OIDC and Dex
How to troubleshoot OpenID Connect (OIDC) and Dex…Read More