OpenID Connect strategy
Introduction
The openid
authentication strategy lets you integrate Kiali to an external
identity provider that implements OpenID
Connect, and allows users to login to Kiali using their existing accounts of a
third-party system.
If your
Kubernetes
cluster is also integrated with your OpenId provider, then Kiali’s openid
strategy can offer role-based access control (RBAC) through the
Kubernetes
authorization mechanisms. See the RBAC
documentation for more details.
Currently, Kiali supports the authorization code flow (preferred) and the implicit flow of the OpenId Connect spec.
Requirements
If you want to enable usage of the OpenId’s authorization code flow, make sure that the Kiali’s signing key is 16, 24 or 32 byte long. If you setup a signing key of a different size, Kiali will only be capable of using the implicit flow. If you install Kiali via the operator and don’t set a custom signing key, the operator should create a 16 byte long signing key.
We recommend using the authorization code flow.
If you don’t need RBAC support, the only requirement is to have a working OpenId Server where Kiali can be configured as a client application.
If you do need RBAC support, you need either:
-
A Kubernetes cluster configured with OpenID connect integration, which results in the API server accepting tokens issued by your identity provider; or
-
A replacement or reverse proxy for the Kubernetes cluster API capable of handling the OIDC authentication.
The first option is preferred if you can manipulate your cluster API server startup flags, which will result in your cluster to also be integrated with the external OpenID provider.
The second option is provided for cases where you are using a managed
Kubernetes and your cloud provider does not support configuring OpenID
integration. Kiali assumes an implementation of a Kubernetes API server. For
example, a community user has reported to successfully configure Kiali’s OpenID
strategy by using
kube-oidc-proxy
which is a
reverse proxy that handles the OpenID authentication and forwards the
authenticated requests to the Kubernetes API.
Several Azure users have reported that OpenId
authentication is not working correctly even after enabling Azure AD
integration in AKS clusters. As of now, if you need RBAC, you will need to
fallback to using
kube-oidc-proxy
or a
similar alternative. If you don’t need RBAC, just configure Kiali accordingly.
As nobody in the Kiali team has access to Azure, contributions for improved
Azure support will be appreciated.
Set-up with RBAC support
Assuming you already have a working Kubernetes cluster with OpenId integration
(or a working alternative like kube-oidc-proxy
), you should already had
configured an application or a client in your OpenId server (some cloud
providers configure this app/client automatically for you). You must re-use
this existing application/client by adding the root path of your Kiali
instance as an allowed/authorized callback URL. If the OpenID server provided
you a client secret for the application/client, or if you had manually set a
client secret, issue the following command to create a Kubernetes secret
holding the OpenId client secret:
kubectl create secret generic kiali --from-literal="oidc-secret=$CLIENT_SECRET" -n $NAMESPACE
where $NAMESPACE
is the namespace where you installed Kiali and
$CLIENT_SECRET
is the secret you configured or provided by your OpenId
Server. If Kiali is already running, you may need to restart the Kiali pod so
that the secret is mounted in Kiali.
This secret is only needed if you want Kiali to use the authorization code flow (i.e. if your Kiali’s signing key is neither 16, 24 or 32 byte long).
It’s worth emphasizing that to configure OpenID integration you must re-use the OpenID application/client that you created for your Kubernetes cluster. If you create a new application/client for Kiali in your OpenId server, Kiali will fail to properly authenticate users.
Then, to enable the OpenID Connect strategy, the minimal configuration you need to set in the Kiali CR is like the following:
spec:
auth:
strategy: openid
openid:
client_id: "kiali-client"
issuer_uri: "https://openid.issuer.com"
This assumes that your Kubernetes cluster is configured with OpenID Connect
integration. In this case, the client-id
and issuer_uri
attributes must
match the --oidc-client-id
and --oidc-issuer-url
flags
used
to start the cluster API server. If these values don’t match, users will fail
to login to Kiali.
If you are using a replacement or a reverse proxy for the Kubernetes API server, the minimal configuration is like the following:
spec:
auth:
strategy: openid
openid:
api_proxy: "https://proxy.domain.com:port"
api_proxy_ca_data: "..."
client_id: "kiali-client"
issuer_uri: "https://openid.issuer.com"
The value of client-id
and issuer_uri
must match the values of the
configuration of your reverse proxy or cluster API replacement. The api_proxy
attribute is the URI of the reverse proxy or cluster API replacement (only
HTTPS is allowed). The api_proxy_ca_data
is the public certificate authority
file encoded in a base64 string, to trust the secure connection.
Set-up with no RBAC support
Register Kiali as a client application in your OpenId Server. Use the root path of your Kiali instance as the callback URL. If the OpenId Server provides you a client secret, or if you manually set a client secret, issue the following command to create a Kubernetes secret holding the OpenId client secret:
kubectl create secret generic kiali --from-literal="oidc-secret=$CLIENT_SECRET" -n $NAMESPACE
where $NAMESPACE
is the namespace where you installed Kiali and
$CLIENT_SECRET
is the secret you configured or provided by your OpenId
Server. If Kiali is already running, you may need to restart the Kiali pod so
that the secret is mounted in Kiali.
This secret is only needed if you want Kiali to use the authorization code flow (i.e. if your Kiali’s signing key is neither 16, 24 or 32 byte long).
Then, to enable the OpenID Connect strategy, the minimal configuration you need to set in the Kiali CR is like the following:
spec:
auth:
strategy: openid
openid:
client_id: "kiali-client"
disable_rbac: true
issuer_uri: "https://openid.issuer.com"
As RBAC is disabled, all users logging into Kiali will share the same cluster-wide privileges.
Additional configurations
Configuring the displayed user name
The Kiali front-end will, by default, retrieve the string of the sub
claim of
the OpenID token and display it as the user name. You can customize which field
to display as the user name by setting the username_claim
attribute of the
Kiali CR. For example:
spec:
auth:
openid:
username_claim: "email"
If you enabled RBAC, you will want the username_claim
attribute to match the
--oidc-username-claim
flag used to start the Kubernetes API server, or the
equivalent option if you are using a replacement or reverse proxy of the API
server. Else, any user-friendly claim will be OK as it is purely informational.
Configuring requested scopes
By default, Kiali will request access to the openid
, profile
and email
standard scopes. If you need a different set of scopes, you can set the
scopes
attribute in the Kiali CR. For example:
spec:
auth:
openid:
scopes:
- "openid"
- "email"
- "groups"
The openid
scope is forced. If you don’t add it to the list of scopes to
request, Kiali will still request it from the identity provider.
Configuring authentication timeout
When the user is redirected to the external authentication system, by default
Kiali will wait at most 5 minutes for the user to authenticate. After that time
has elapsed, Kiali will reject authentication. You can adjust this timeout by
setting the authentication_timeout
with the number of seconds that Kiali
should wait at most. For example:
spec:
auth:
openid:
authentication_timeout: 60 # Wait only one minute.
Using an OpenID provider with a self-signed certificate
If your OpenID provider is using a self-signed certificate, you can disable
certificate validation by setting the insecure_skip_verify_tls
to true
in
the Kiali CR:
spec:
auth:
openid:
insecure_skip_verify_tls: true
You should use self-signed certificates only for testing purposes.
Using a HTTP/HTTPS Proxy
In some network configurations, there is the need to use proxies to connect to
the outside world. OpenID requires outside world connections to get metadata and
do key validation, so you can configure it by setting the http_proxy
and
https_proxy
keys in the Kiali CR. They use the same format as the HTTP_PROXY
and HTTPS_PROXY
environment variables.
spec:
auth:
openid:
http_proxy: http://USERNAME:PASSWORD@10.0.1.1:8080/
https_proxy: https://USERNAME:PASSWORD@10.0.0.1:8080/
Using with Keycloak
When using OpenId with Keycloak, you will need to enable the Standard Flow Enabled
option on the Client (in the Administration Console):

The Standard Flow described on the options is the same as the authorization code flow from the rest of the documentation.
If you get an error like Client is not allowed to initiate browser login with
given response_type. Implicit flow is disabled for the client.
, it means that
your signing key for Kiali is not a standard size (16, 24 or 32 bytes long).
Enabling the Implicit Flow Enabled
option of the client will make the problem
go away, but be aware that the implicit flow is less secure, and not
recommended.