---
title: "OpenID Connect strategy"
date: 2020-08-25T00:00:00+02:00
draft: false
weight: 9
---

:toc: macro
:toc-title: In this section:
:keywords: authentication openid
:icons: font
:sectlinks:

toc::[]

== Introduction

The `openid` authentication strategy lets you integrate Kiali to an external
identity provider that implements link:https://openid.net/connect/[OpenID
Connect], and allows users to login to Kiali using their existing accounts of a
third-party system.

If your
link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens[Kubernetes
cluster is also integrated with your OpenId provider], then Kiali's `openid`
strategy can offer role-based access control (RBAC) through the
link:https://kubernetes.io/docs/reference/access-authn-authz/rbac/[Kubernetes
authorization mechanisms]. See the link:{{< relref "../rbac" >}}[RBAC
documentation] for more details.

Currently, Kiali supports the _authorization code flow_ (preferred) and the
_implicit flow_ of the link:https://openid.net/connect/[OpenId Connect spec].

== Requirements

If you want to enable usage of the OpenId's _authorization code flow_, make
sure that the
link:https://github.com/kiali/kiali-operator/blob/7dafc469c95d4307ebd03c515a87c7f84eb64da7/deploy/kiali/kiali_cr.yaml#L746-L754[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.  

icon:bullhorn[size=1x]{nbsp} 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 link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens[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
link:https://github.com/jetstack/kube-oidc-proxy[`kube-oidc-proxy`] which is a
reverse proxy that handles the OpenID authentication and forwards the
authenticated requests to the Kubernetes API.

icon:bullhorn[size=1x]{nbsp} 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
link:https://github.com/jetstack/kube-oidc-proxy[`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:

[source,yaml]
----
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.

icon:bullhorn[size=1x]{nbsp} 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).

icon:bullhorn[size=1x]{nbsp} 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:

[source,yaml]
----
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
link:https://kubernetes.io/docs/reference/access-authn-authz/authentication/#configuring-the-api-server[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:

[source,yaml]
----
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:

[source,yaml]
----
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.

icon:bullhorn[size=1x]{nbsp} 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:

[source,yaml]
----
spec:
  auth:
    strategy: openid
    openid:
      client_id: "kiali-client"
      disable_rbac: true
      issuer_uri: "https://openid.issuer.com"
----

icon:bullhorn[size=1x]{nbsp} 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:

[source,yaml]
----
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:

[source,yaml]
----
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:

[source,yaml]
----
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:

[source,yaml]
----
spec:
  auth:
    openid:
      insecure_skip_verify_tls: true
----

icon:bullhorn[size=1x]{nbsp} You should use self-signed certificates only for
testing purposes.
