Configure OIDC Auth Applications¶

The oidc-auth-apps application is a system application that needs to be configured to use a remote Windows Active Directory server to authenticate users of the Kubernetes API. The oidc-auth-apps is packaged in the ISO and uploaded by default.

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 Kubernetes kube-apiserver, see Configure Kubernetes for OIDC Token Validation while Bootstrapping the System or Configure Kubernetes for OIDC Token Validation after Bootstrapping the System.
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 the dex-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 specifying ‘ssl_ca_cert: dex-ca.pem’ in the ansible bootstrap overrides localhost.yml file, or by using the system certificate-install -m ssl_ca dex-ca.pem command.

Procedure

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 the local-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 be ‘dex-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
```
Create the secret wadcert with the CA’s certificate that signed the Active Directory’s certificate using the following command:
```
~(keystone_admin)]$ kubectl create secret generic wadcert --from-file=ssl/AD_CA.cer -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 wadcert secret, 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 example below configures a token expiry of ten hours, a single LDAP connector to an Active Directory service using HTTPS (LDAPS) using the wadcert secret configured in this section, the required Active Directory service 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.

Note

Do NOT forget to include the id, name, and redirectURIs parameters.

Note

There is an internal client_secret that is used between the oidc-client container and the dex container. It is recommended that you configure a unique, more secure client_secret by specifying the value in the dex overrides file, as shown in the example below.
```
config:
  staticClients:
  - id: stx-oidc-client-app
    name: STX OIDC Client app
    redirectURIs: ['<OAM floating IP address>/callback']
    secret: BetterSecret
  client_secret: BetterSecret
  expiry:
    idTokens: "10h"
  connectors:
  - type: ldap
    name: OpenLDAP
    id: ldap
    config:
      host: pv-windows-acti.cumulus.wrs.com:636
      rootCA: /etc/ssl/certs/adcert/AD_CA.cer
      insecureNoSSL: false
      insecureSkipVerify: false
      bindDN: cn=Administrator,cn=Users,dc=cumulus,dc=wrs,dc=com
      bindPW: [<password>]
      usernamePrompt: Username
      userSearch:
        baseDN: ou=Users,ou=Titanium,dc=cumulus,dc=wrs,dc=com
        filter: "(objectClass=user)"
        username: sAMAccountName
        idAttr: sAMAccountName
        emailAttr: sAMAccountName
        nameAttr: displayName
      groupSearch:
        baseDN: ou=Groups,ou=Titanium,dc=cumulus,dc=wrs,dc=com
        filter: "(objectClass=group)"
        userAttr: DN
        groupAttr: member
        nameAttr: cn
extraVolumes:
- name: certdir
  secret:
    secretName: wadcert
extraVolumeMounts:
- name: certdir
  mountPath: /etc/ssl/certs/adcert
```
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 plus groupSearch clauses are required for the same Windows Active Directory service, multiple ‘ldap’ type connectors, with the same host information but different userSearch plus groupSearch clauses, should be used.

Whenever you use multiple ‘ldap’ type connectors, ensure you use unique ‘name:’ and ‘id:’ 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
```
Note

If you need to manually override the secrets, the client_secret in the oidc-client overrides must match the staticClients secret and client_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
```

Configure OIDC Auth Applications

Configure OIDC Auth Applications¶

StarlingX R5.0