Set up OIDC Auth Applications¶
The oidc-auth-apps application is a system application that enables the use of a remote Windows Active Directory server or an LDAP server to authenticate users of the Kubernetes API.
In this document, the LDAP server presented is the one present in the StarlingX deploy, called Local LDAP server. This LDAP server runs in the controllers except for DC environments, where it runs only in the SystemController’s controllers.
The oidc-auth-apps
is packaged in the ISO and uploaded by default.
Configure OIDC Auth Applications¶
Prerequisites
You must have configured the Kubernetes
kube-apiserver
to use the oidc-auth-apps OIDC identity provider for validation of tokens in Kubernetes API requests, which use OIDC authentication. For more information on configuring the Kuberneteskube-apiserver
, see Configure Kubernetes for OIDC Token Validation while Bootstrapping the System or Configure Kubernetes for OIDC Token Validation after Bootstrapping the System.
Procedure
Create certificates using one of the following options.
Create certificates using cert-manager (recommended):
Certificates used by
oidc-auth-apps
can be managed by Cert-Manager. Doing so will automatically renew the certificates before they expire. Thesystem-local-ca
ClusterIssuer (see System Local CA Issuer) will be used to issue this certificate.Note
If a signing CA is not a well-known trusted CA, you must ensure the system trusts the CA by specifying it either during the bootstrap phase of system installation, by specifying
ssl_ca_cert: <certificate_file>
in the ansible bootstrap overrides localhost.yml file, or by using the system certificate-install -m ssl_ca <certificate_file> command.Also refer to Add a Trusted CA for installing a root CA, which includes instruction to lock/unlock controller nodes when using system certificate-install command.
Important
The namespace for
oidc-auth-apps
must bekube-system
.Create the OIDC client and identity provider server certificate and private key pair.
~(keystone_admin)]$ cat <<EOF > oidc-auth-apps-certificate.yaml --- apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: oidc-auth-apps-certificate namespace: kube-system spec: secretName: oidc-auth-apps-certificate duration: 2160h # 90 days renewBefore: 360h # 15 days issuerRef: name: system-local-ca kind: ClusterIssuer commonName: <OAM_floating_IP_address> subject: organizations: - ABC-Company organizationalUnits: - StarlingX-system-oidc-auth-apps ipAddresses: - <OAM_floating_IP_address> EOF
Note
The Certificate usage of Cert-manager Documentation (https://cert-manager.io/docs/usage/certificate/) states that one should “Take care when setting the
renewBefore
field to be very close to the duration as this can lead to a renewal loop, where the Certificate is always in the renewal period.”In the light of the statement above, you must not set
renewBefore
to a value very close to the “duration” value, such as a renewBefore of 29 days and a duration of 30 days. Instead, you could set values such as renewBefore=15 days and duration=30 days to avoid renewal loops.Apply the configuration.
~(keystone_admin)]$ kubectl apply -f oidc-auth-apps-certificate.yaml
Verify the configuration.
~(keystone_admin)]$ kubectl get certificate oidc-auth-apps-certificate –n kube-system
Configure the OIDC-client with both the OIDC Client and Identity Server Certificate and the OIDC Client and Identity Trusted CA certificate.
Create a secret with the certificate of the root CA that signed the OIDC client and identity provider’s server certificate. In this example, it will be the
ca.crt
of thesystem-local-ca
(ClusterIssuer).~(keystone_admin)]$ mkdir /home/sysadmin/ssl ~(keystone_admin)]$ kubectl get secret system-local-ca -n cert-manager -o=jsonpath='{.data.ca\.crt}' | base64 --decode > /home/sysadmin/ssl/dex-ca-cert.crt ~(keystone_admin)]$ kubectl create secret generic dex-ca-cert --from-file=/home/sysadmin/ssl/dex-ca-cert.crt -n kube-system ~(keystone_admin)]$ cat <<EOF > stx-oidc-client.yaml tlsName: oidc-auth-apps-certificate config: # The OIDC-client container mounts the dex-ca-cert secret at /home, therefore # issuer_root_ca: /home/<filename-only-of-generic-secret> issuer_root_ca: /home/dex-ca-cert.crt issuer_root_ca_secret: dex-ca-cert EOF ~(keystone_admin)]$ system helm-override-update oidc-auth-apps oidc-client kube-system --values stx-oidc-client.yaml
Create a secret with the certificate of the CA that signed the certificate of the Identity Providers (IdPs) that you will be using.
If you will use a WAD server, create the secret
wad-ca-cert
with the CA’s certificate that signed the Active Directory’s certificate using the command below.~(keystone_admin)]$ kubectl create secret generic wad-ca-cert --from-file=wad-ca-cert.crt -n kube-system
If you will use the Local LDAP server, create the secret
local-ldap-ca-cert
with the CA’s certificate that signed the Local LDAP’s certificate using the command below. This CA’s certificate, presented below as filelocal-ldap-ca-cert.crt
, can be extracted from the controller where the Local LDAP server is running (the SystemController in DC environments) using the command kubectl get secret system-local-ca -n cert-manager -o=jsonpath='{.data.ca\.crt}' | base64 --decode > local-ldap-ca-cert.crt.~(keystone_admin)]$ kubectl create secret generic local-ldap-ca-cert --from-file=local-ldap-ca-cert.crt -n kube-system
The secrets
wad-ca-cert
and/orlocal-ldap-ca-cert
will be used later in the application overrides.Configure the secret observer to track changes.
Change the cronSchedule according to your needs. The cronSchedule controls how often the application checks to see if the certificate mounted on the dex and oidc-client pods had changed.
Create a YAML configuration to modify the cronSchedule according to your needs.
The cronSchedule controls how often the application checks to see if the certificate mounted on the dex and oidc-client pods changed. The following example sets the schedule to every 15 minutes.
~(keystone_admin)]$ cat <<EOF > secret-observer-overrides.yaml cronSchedule: "*/15 * * * *" observedSecrets: - secretName: "dex-ca-cert" filename: "dex-ca-cert.crt" deploymentToRestart: "stx-oidc-client" - secretName: "oidc-auth-apps-certificate" filename: "tls.crt" deploymentToRestart: "stx-oidc-client" - secretName: "oidc-auth-apps-certificate" filename: "tls.crt" deploymentToRestart: "oidc-dex" EOF
Execute the following command to update the overrides:
~(keystone_admin)]$ system helm-override-update oidc-auth-apps secret-observer kube-system --values secret-observer-overrides.yaml
Use certificates generated and signed by an external CA.
Although it is recommended to use cert-manager to manage certificates, as described above in item “Create certificates using cert-manager (recommended)”, one can instead use certificates generated by an external CA.
For backwards compatibility reasons, the default helm chart overrides of dex, oidc-client and secret-observer in
oidc-auth-apps
application are set for this example of using externally generated certificates. The default override values of helm charts inoidc-auth-apps
application include the use of kubernetes secrets namedlocal-dex.tls
, anddex-client-secret
for declaring the dex server certificate and the CA which signed it, respectively. These secrets are created in this example.In addition, one can indicate the certificates for a WAD server and/or a Local LDAP server that have https enabled by using the secrets
wad-ca-cert
and/orlocal-ldap-ca-cert
as in this example.Prerequisites
You must have a CA signed certificate (
dex-cert.pem
file), and private key (dex-key.pem file
) for the dex OIDC Identity Provider of oidc-auth-apps.This certificate must have the StarlingX’s floating OAM IP Address in the SAN list. If you are planning on defining and using a DNS name for the StarlingX’s floating OAM IP Address, then this DNS name must also be in the SAN list. Refer to the documentation for the external CA that you are using, in order to create a signed certificate and key.
If you are using an intermediate CA to sign the dex certificate, include both the dex certificate (signed by the intermediate CA), and the intermediate CA’s certificate (signed by the Root CA) in that order, in
dex-cert.pem
.You must have the certificate of the CA (
dex-ca.pem
file) that signed the above certificate for the dex OIDC Identity Provider of oidc-auth-apps.If an intermediate CA was used to sign the dex certificate and both the dex certificate and the intermediate CA certificate was included in
dex-cert.pem
, then thedex-ca.pem
file should contain the root CA’s certificate.If the signing CA (
dex-ca.pem
) is not a well-known trusted CA, you must ensure the system trusts the CA by specifying it either during the bootstrap phase of system installation, by specifyingssl_ca_cert: dex-ca.pem
in the ansible bootstrap overrideslocalhost.yml
file, or by using the system certificate-install -m ssl_ca dex-ca.pem command.Also refer to Add a Trusted CA for installing a root CA, which includes instruction to lock/unlock controller nodes when using system certificate-install command.
Create the secret,
local-dex.tls
, with the certificate and key, to be used by the oidc-auth-apps, as well as the secret,dex-client-secret
, with the CA’s certificate that signed thelocal-dex.tls
certificate.For example, assuming the cert and key pem files for creating these secrets are in
/home/sysadmin/ssl/
, run the following commands to create the secrets:Note
oidc-auth-apps looks specifically for secrets of these names in the
kube-system
namespace.For the generic secret
dex-client-secret
, the filename must bedex-ca.pem
.~(keystone_admin)]$ kubectl create secret tls local-dex.tls --cert=ssl/dex-cert.pem --key=ssl/dex-key.pem -n kube-system ~(keystone_admin)]$ kubectl create secret generic dex-client-secret --from-file=/home/sysadmin/ssl/dex-ca.pem -n kube-system
If you will use a WAD server, create the secret
wad-ca-cert
with the CA’s certificate that signed the Active Directory’s certificate using the command below.~(keystone_admin)]$ kubectl create secret generic wad-ca-cert --from-file=wad-ca-cert.crt -n kube-system
If you will use the Local LDAP server, create the secret
local-ldap-ca-cert
with the CA’s certificate that signed the Local LDAP’s certificate using the command below. This CA’s certificate, presented below as filelocal-ldap-ca-cert.crt
, can be extracted from the controller where the Local LDAP server is running (the SystemController in DC environments) using the command kubectl get secret system-local-ca -n cert-manager -o=jsonpath='{.data.ca\.crt}' | base64 --decode > local-ldap-ca-cert.crt.~(keystone_admin)]$ kubectl create secret generic local-ldap-ca-cert --from-file=local-ldap-ca-cert.crt -n kube-system
Specify user overrides for oidc-auth-apps application, by using the following command:
~(keystone_admin)]$ system helm-override-update oidc-auth-apps dex kube-system --values /home/sysadmin/dex-overrides.yaml
The dex-overrides.yaml file contains the desired dex helm chart overrides (that is, the LDAP connector configuration for the Active Directory service, optional token expiry, and so on), and volume mounts for providing access to the
wad-ca-cert
secret and/or to thelocal-ldap-ca-cert
, described in this section.For the complete list of dex helm chart values supported, see Dex Helm Chart Values. For the complete list of parameters of the dex LDAP connector configuration, see Authentication Through LDAP.
The overall Dex documentation is available on dexidp.io. The configuration of dex server version v2.37.0 is described on github (https://github.com/dexidp/dex/blob/v2.37.0/config.yaml.dist) with example
config.dev.yaml
(https://github.com/dexidp/dex/blob/v2.37.0/config.dev.yaml).The examples below configure a token expiry of ten hours, the LDAP connectors to the remote servers using HTTPS (LDAPS) using the servers CA secrets, the required remote servers login information (that is, bindDN, and bindPW), and example userSearch, and groupSearch clauses.
(Optional) There is a default secret in the dex configuration for
staticClients
. You can change this using helm overrides. For example, to change the secret, first run the following command to see the default settings. In this example,10.10.10.2
is the StarlingX OAM floating IP address.~(keystone_admin)]$ system helm-override-show oidc-auth-apps dex kube-system config: staticClients: - id: stx-oidc-client-app name: STX OIDC Client app redirectURIs: ['https://10.10.10.2:30555/callback'] secret: St8rlingX
Change the secret from the output and copy the entire configuration section shown above in to your dex overrides file shown in the example below.
Warning
Do not forget to include the id, name, and redirectURIs parameters.
Note
There is an internal password (called
secret
in dex overrides andclient_secret
in oidc-client overrides) that is used between the oidc-client container and the dex container. It is recommended that you configure a unique, more secure password by specifying the value in the dex overrides file, as shown in the example below.For only a WAD server, the configuration is shown below.
config: staticClients: - id: stx-oidc-client-app name: STX OIDC Client app redirectURIs: ['https://<OAM floating IP address>:30555/callback'] secret: BetterSecret expiry: idTokens: "10h" connectors: - type: ldap name: WAD id: wad-1 config: host: pv-windows-acti.windows-activedir.example.com:636 rootCA: /etc/ssl/certs/adcert/wad-ca-cert.crt insecureNoSSL: false insecureSkipVerify: false bindDN: cn=Administrator,cn=Users,dc=windows-activedir,dc=example,dc=com bindPW: [<password>] usernamePrompt: Username userSearch: baseDN: ou=Users,ou=Titanium,dc=windows-activedir,dc=example,dc=com filter: "(objectClass=user)" username: sAMAccountName idAttr: sAMAccountName emailAttr: sAMAccountName nameAttr: displayName groupSearch: baseDN: ou=Groups,ou=Titanium,dc=windows-activedir,dc=example,dc=com filter: "(objectClass=group)" userMatchers: - userAttr: DN groupAttr: member nameAttr: cn volumeMounts: - mountPath: /etc/ssl/certs/adcert name: certdir - mountPath: /etc/dex/tls name: https-tls volumes: - name: certdir secret: secretName: wad-ca-cert - name: https-tls secret: defaultMode: 420 secretName: oidc-auth-apps-certificate
For only the Local LDAP server, the configuration is shown below. The value of
bindPW
can be retrieved through command keyring get ldap ldapadmin executed in the controller where the Local LDAP server is running. In DC environments, the MGMT floating IP address to be used is the one from the SystemController.config: staticClients: - id: stx-oidc-client-app name: STX OIDC Client app redirectURIs: ['https://<OAM floating IP address>:30555/callback'] secret: BetterSecret expiry: idTokens: "10h" connectors: - type: ldap name: LocalLDAP id: localldap-1 config: host: <MGMT floating IP address>:636 rootCA: /etc/ssl/certs/adcert/local-ldap-ca-cert.crt insecureNoSSL: false insecureSkipVerify: false bindDN: CN=ldapadmin,DC=cgcs,DC=local bindPW: [<password>] usernamePrompt: Username userSearch: baseDN: ou=People,dc=cgcs,dc=local filter: "(objectClass=posixAccount)" username: uid idAttr: DN emailAttr: uid nameAttr: gecos groupSearch: baseDN: ou=Group,dc=cgcs,dc=local filter: "(objectClass=posixGroup)" userMatchers: - userAttr: uid groupAttr: memberUid nameAttr: cn volumeMounts: - mountPath: /etc/ssl/certs/adcert name: certdir - mountPath: /etc/dex/tls name: https-tls volumes: - name: certdir secret: secretName: local-ldap-ca-cert - name: https-tls secret: defaultMode: 420 secretName: oidc-auth-apps-certificate
If both WAD and Local LDAP servers are used at same time, use the examples above with the connectors from WAD and Local LDAP in the same
connectors
list while thevolumes
to be used is the one written below.volumes: - name: certdir projected: sources: - secret: name: wad-ca-cert - secret: name: local-ldap-ca-cert - name: https-tls secret: defaultMode: 420 secretName: oidc-auth-apps-certificate
If more than one Windows Active Directory service is required for authenticating the different users of the StarlingX, multiple
ldap
type connectors can be configured; one for each Windows Active Directory service.If more than one
userSearch
plusgroupSearch
clauses are required for the same Windows Active Directory service, multipleldap
type connectors, with the same host information but differentuserSearch
plusgroupSearch
clauses, should be used.Whenever you use multiple
ldap
type connectors, ensure you use uniquename:
andid:
parameters for each connector.An override in the secrets in the dex helm chart must be accompanied by an override in the oidc-client helm chart.
The following override is sufficient for changing the secret in the
/home/sysadmin/oidc-client-overrides.yaml
file.config: client_secret: BetterSecret
Apply the oidc-client overrides using the following command:
~(keystone_admin)]$ system helm-override-update oidc-auth-apps oidc-client kube-system --values /home/sysadmin/oidc-client-overrides.yaml --reuse-values
Note
If you need to manually override the secrets, the
client_secret
in the oidc-client overrides must match thestaticClients
secret
in the dex overrides, otherwise the oidc-auth CLI client will not function.Use the system application-apply command to apply the configuration:
~(keystone_admin)]$ system application-apply oidc-auth-apps
Default helm overrides for oidc-auth-apps application¶
For backwards compatibility reasons, the default helm overrides for dex helm are:
Note
It is NOT recommended to use these; it is recommended to create
certificates using cert-manager
and explicitly refer to the resulting
certificate secrets in user-specified helm overrides, as described on the
procedure above.
image:
repository: ghcr.io/dexidp/dex
pullPolicy: IfNotPresent
tag: v2.37.0
imagePullSecrets:
- name: default-registry-key
env:
name: KUBERNETES_POD_NAMESPACE
value: kube-system
config:
issuer: https://<OAM_IP>:30556/dex
staticClients:
- id: stx-oidc-client-app
name: STX OIDC Client app
secret: St8rlingX
redirectURIs:
- https://<OAM_IP>:30555/callback
enablePasswordDB: false
web:
tlsCert: /etc/dex/tls/tls.crt
tlsKey: /etc/dex/tls/tls.key
storage:
type: kubernetes
config:
inCluster: true
oauth2:
skipApprovalScreen: true
logger:
level: debug
service:
type: NodePort
ports:
https:
nodePort: 30556
https:
enabled: true
grpc:
enabled: false
nodeSelector:
node-role.kubernetes.io/control-plane: ""
volumeMounts:
- mountPath: /etc/dex/tls/
name: https-tls
volumes:
- name: https-tls
secret:
defaultMode: 420
secretName: local-dex.tls
tolerations:
- key: "node-role.kubernetes.io/master"
operator: "Exists"
effect: "NoSchedule"
- key: "node-role.kubernetes.io/control-plane"
operator: "Exists"
effect: "NoSchedule"
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: app
operator: In
values:
- dex
topologyKey: kubernetes.io/hostname
The default helm overrides for oidc-client are:
config:
client_id: stx-oidc-client-app
client_secret: St8rlingX
issuer: https://<OAM_IP>:30556/dex
issuer_root_ca: /home/dex-ca.pem
issuer_root_ca_secret: dex-client-secret
listen: https://0.0.0.0:5555
redirect_uri: https://<OAM_IP>:30555/callback
tlsCert: /etc/dex/tls/https/server/tls.crt
tlsKey: /etc/dex/tls/https/server/tls.key
nodeSelector:
node-role.kubernetes.io/control-plane: ""
service:
type: NodePort
port: 5555
nodePort: 30555
replicas: <replicate count>
tolerations:
- key: "node-role.kubernetes.io/master"
operator: "Exists"
effect: "NoSchedule"
- key: "node-role.kubernetes.io/control-plane"
operator: "Exists"
effect: "NoSchedule"
affinity:
podAntiAffinity:
requiredDuringSchedulingIgnoredDuringExecution:
- labelSelector:
matchExpressions:
- key: app
operator: In
values:
- stx-oidc-client
topologyKey: kubernetes.io/hostname
helmv3Compatible: true
The default helm overrides for secret-observer are:
namespace: "kube-system"
observedSecrets:
- secretName: "dex-client-secret"
filename: "dex-ca.pem"
deploymentToRestart: "stx-oidc-client"
- secretName: "local-dex.tls"
filename: "tls.crt"
deploymentToRestart: "stx-oidc-client"
- secretName: "local-dex.tls"
filename: "tls.crt"
deploymentToRestart: "oidc-dex"
tolerations:
- key: "node-role.kubernetes.io/master"
operator: "Exists"
effect: "NoSchedule"
- key: "node-role.kubernetes.io/control-plane"
operator: "Exists"
effect: "NoSchedule"