.. cwn1581381515361 .. _configure-oidc-auth-applications: ----------------------------- Set up OIDC Auth Applications ----------------------------- The ``oidc-auth-apps`` is a system-level application that serves as an OIDC Identity Provider for authenticating users accessing the Kubernetes API. It functions as a proxy OIDC provider powered by dexidp.io and can be configured to forward authentication requests to various types of upstream Identity Providers. In the current |prod| environment, it supports proxying to LDAP-based Identity Providers, including |prod|'s Local |LDAP| server and/or remote Windows Active Directory servers. In this section, the procedure below shows examples for configuring ``oidc-auth-apps`` to proxy requests to a remote Windows Active Directory server and/or to |prod|'s Local |LDAP| server. The ``oidc-auth-apps`` is packaged in the ISO and uploaded by default. Configure OIDC Auth Applications -------------------------------- .. rubric:: |prereq| .. _configure-oidc-auth-applications-ul-gpz-x51-llb: - 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 :ref:`Configure Kubernetes for OIDC Token Validation while Bootstrapping the System ` or :ref:`Configure Kubernetes for OIDC Token Validation after Bootstrapping the System `. .. rubric:: |proc| #. Create certificates for OIDC Servers. Certificates used by ``oidc-auth-apps`` can be managed by Cert-Manager. Doing so will automatically renew the certificates before they expire. The ``system-local-ca`` ClusterIssuer (see :ref:`system-local-ca-issuer-9196c5794834`) 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: `` in the ansible bootstrap overrides ``localhost.yml`` file, or by using the :command:`system ca-certificate-install` command. Also refer to :ref:`Add a Trusted CA ` for installing a root |CA|, which includes instruction to `lock/unlock` controller nodes when using :command:`system ca-certificate-install` command. .. important:: The namespace for ``oidc-auth-apps`` must be ``kube-system``. #. Create the |OIDC| client and identity provider server certificate and private key pair. .. code-block:: none ~(keystone_admin)]$ cat < 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: subject: organizations: - ABC-Company organizationalUnits: - StarlingX-system-oidc-auth-apps ipAddresses: - EOF .. include:: /shared/_includes/recommended-renewbefore-value-for-certificates-c929cf42b03b.rest #. Apply the configuration. .. code-block:: none ~(keystone_admin)]$ kubectl apply -f oidc-auth-apps-certificate.yaml #. Verify the configuration. .. code-block:: none ~(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. Configure 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 the ``oidc-auth-apps-certificate`` (ClusterIssuer). .. code-block:: none ~(keystone_admin)]$ cat < 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/ issuer_root_ca: /home/ca.crt issuer_root_ca_secret: oidc-auth-apps-certificate 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. .. code-block:: none ~(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, use the Root |CA| data from ``oidc-auth-apps-certificate``, since it is the same Root |CA| that signs the Local |LDAP| certificate (``system-local-ca``). The secrets ``wad-ca-cert`` and/or ``oidc-auth-apps-certificate`` 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. .. code-block:: none ~(keystone_admin)]$ cat < secret-observer-overrides.yaml cronSchedule: "*/15 * * * *" observedSecrets: - secretName: "oidc-auth-apps-certificate" filename: "ca.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: .. code-block:: none ~(keystone_admin)]$ system helm-override-update oidc-auth-apps secret-observer kube-system --values secret-observer-overrides.yaml #. Specify user overrides for **oidc-auth-apps** application, by using the following command: .. code-block:: none ~(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 the ``local-ldap-ca-cert``, described in this section. See examples of the ``dex-overrides.yaml`` file for a |WAD| backend/connector and a Local |LDAP| backend/connector below. 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.42.0 is described on github (https://github.com/dexidp/dex/blob/v2.42.0/config.yaml.dist) with example ``config.dev.yaml`` (https://github.com/dexidp/dex/blob/v2.42.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 :command:`userSearch`, and :command:`groupSearch` clauses. For only a |WAD| server, the configuration is shown below. .. code-block:: none config: staticClients: - id: stx-oidc-client-app name: STX OIDC Client app redirectURIs: ['https://: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: [] 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` command 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. .. code-block:: none cat < dex-overrides.yaml config: staticClients: - id: stx-oidc-client-app name: STX OIDC Client app secret: St8rlingX redirectURIs: - https://:30555/callback expiry: idTokens: "10h" connectors: - type: ldap name: LocalLDAP id: localldap-1 config: host: :636 rootCA: /etc/ssl/certs/adcert/ca.crt insecureNoSSL: false insecureSkipVerify: false bindDN: CN=ldapadmin,DC=cgcs,DC=local bindPW: [] 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: oidc-auth-apps-certificate - 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 the ``volumes`` to be used is the one written below. .. code-block:: none 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 |prod|, 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. (Optional) There is a default internal secret in the above dex configuration for the ``stx-oidc-client-app`` StaticClient. This internal secret is used between the ``oidc-client`` container and the dex container. It is recommended that you configure a unique, more secure password. 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 |prod-long| |OAM| floating IP address. .. code-block:: none ~(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. #. An override of the secret in the staticClients section of the dex helm chart in previous step 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. .. code-block:: none config: client_secret: BetterSecret Apply the oidc-client overrides using the following command: .. code-block:: none ~(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 the ``staticClients`` ``secret`` in the dex overrides, otherwise the oidc-auth |CLI| client will not function. #. Use the :command:`system application-apply` command to apply the configuration: .. code-block:: none ~(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. .. code-block:: none image: repository: ghcr.io/dexidp/dex pullPolicy: IfNotPresent tag: v2.40.0 imagePullSecrets: - name: default-registry-key env: name: KUBERNETES_POD_NAMESPACE value: kube-system config: issuer: https://:30556/dex staticClients: - id: stx-oidc-client-app name: STX OIDC Client app secret: St8rlingX redirectURIs: - https://: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" podLabels: app: dex affinity: podAntiAffinity: requiredDuringSchedulingIgnoredDuringExecution: - labelSelector: matchExpressions: - key: app operator: In values: - dex topologyKey: kubernetes.io/hostname The default helm overrides for oidc-client are: .. code-block:: none config: client_id: stx-oidc-client-app client_secret: St8rlingX issuer: https://: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://: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: 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: .. code-block:: none 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"