|
| 1 | +# Configuring HCL DX Compose and HCL Leap SSO with OIDC |
| 2 | + |
| 3 | +This page provides information on how to configure the Single Sign-On (SSO) layer between HCL DX Compose and HCL Leap. |
| 4 | + |
| 5 | +## Enabling SSO between HCL Leap and HCL DX Compose in Kubernetes |
| 6 | + |
| 7 | +This guide shows how to enable SSO between HCL DX and HCL Leap. You can use the modern and natively supported OpenID Connect (OIDC) protocol since both applications run on Open Liberty. The protocol connects directly to the preferred Identity Provider (IdP), such as Azure AD, Keycloak or Okta. By configuring DX and Leap to trust your central IdP, users get a seamless, single log-in experience. |
| 8 | + |
| 9 | +### Implementing OIDC SSO |
| 10 | + |
| 11 | +1. Install and configure your IdP. |
| 12 | + |
| 13 | + Create a client for each product. IdPs will serve as the single point of truth for credential inputs. |
| 14 | + |
| 15 | +2. Enable OIDC in HCL DX. |
| 16 | + |
| 17 | + Refer to [Configuring DX Compose to use an OIDC identity provider](./../../../cfg_webengine/configure_compose_to_use_oidc.md) to enable and configure OIDC for DX Compose. |
| 18 | + |
| 19 | +3. Enable OIDC in HCL Leap. |
| 20 | + |
| 21 | + Leap can be configured to leverage OIDC as the primary authentication mechanism, turning it into a Relying Party (RP) to the specific IdP. RP is an application that relies on a third-party (such as an IdP) for authentication. When OIDC is used, the user and group lookup feature of Leap is not available and must be disabled as part of the configuration. |
| 22 | + |
| 23 | + 1. Configure the OIDC IdP, which will serve as the OIDC provider. |
| 24 | + |
| 25 | + As part of the configuration process for your identify provider, you will have created or obtained a digital certificate for configuring HTTPS. This certificate will also need to be deployed to Leap so that the two servers can communicate with each other. |
| 26 | + |
| 27 | + !!!note |
| 28 | + The SSL certificate (`.crt`) and public key (`.key`) should be in PKCS12 format. |
| 29 | + |
| 30 | + 2. After copying the `.key` and `.crt` to the Kubernetes image, create a secret using the following command: |
| 31 | + |
| 32 | + ```bash |
| 33 | + kubectl -n <namespace> create secret tls <tls-secret> --key="/tmp/oidc.key" --cert="/tmp/oidc.crt" |
| 34 | + ``` |
| 35 | + |
| 36 | + This secret can be referenced in the `values.yaml` file using the following configuration: |
| 37 | + |
| 38 | + ```yaml |
| 39 | + configuration: |
| 40 | + leap: |
| 41 | + customCertificateSecrets: |
| 42 | + keycloakCert: <tls-secret> |
| 43 | + ``` |
| 44 | + |
| 45 | + 3. Add the OIDC definition as a server customization in the `values.yaml` file. |
| 46 | + |
| 47 | + The properties that you need to specify may differ based on your identity provider. For additional information, refer to [Open Liberty documentation on OIDC](https://openliberty.io/docs/latest/reference/config/openidConnectClient.html) |
| 48 | + |
| 49 | + Before moving on, verify that the `discoveryEndpointURL` property is valid by opening the URL in a browser prior to entering it in the `values.yaml` file and updating the `clientSecret` with the proper value obtained from your IdP. |
| 50 | + |
| 51 | + Example of an OIDC definition: |
| 52 | + |
| 53 | + ```yaml |
| 54 | + # Enter appropriate values for <your-oidc-id>, <your-client-id>, <your-client-secret>, <your-oidc-server>, <your-realm-name>. |
| 55 | + # You may have to refer to your identity provider's configuration. |
| 56 | + configuration: |
| 57 | + leap: |
| 58 | + configOverrideFiles: |
| 59 | + openIdConnect: | |
| 60 | + <server description="leapServer"> |
| 61 | + <openidConnectClient id="<your-oidc-id>" |
| 62 | + clientId="<your-client-id>" |
| 63 | + clientSecret="<your-client-secret>" |
| 64 | + signatureAlgorithm="RS256" |
| 65 | + authFilterRef="interceptedAuthFilter" |
| 66 | + mapIdentityToRegistryUser="false" |
| 67 | + httpsRequired="true" |
| 68 | + scope="openid" |
| 69 | + userIdentityToCreateSubject="preferred_username" |
| 70 | + discoveryEndpointUrl="https://<your-oidc-server>/realms/<your-realm-name>/.well-known/openid-configuration"> |
| 71 | + </openidConnectClient> |
| 72 | + <authFilter id="interceptedAuthFilter"> |
| 73 | + <requestUrl id="authRequestUrl" matchType="contains" urlPattern="/apps/secure|/apps/secured"/> |
| 74 | + </authFilter> |
| 75 | + <httpEndpoint id="defaultHttpEndpoint" |
| 76 | + host="*" |
| 77 | + httpPort="9080" |
| 78 | + httpsPort="9443"> |
| 79 | + <samesite none="*" /> |
| 80 | + </httpEndpoint> |
| 81 | + </server> |
| 82 | + ``` |
| 83 | + |
| 84 | + For more details on defining a server customization, refer to [Open Liberty server customizations](https://opensource.hcltechsw.com/leap-doc/latest/helm_open_liberty_custom.html){target="_blank"}. |
| 85 | + |
| 86 | + !!!important |
| 87 | + The openIdConnectClient redirects to `https://<your-domain>/oidcclient/redirect/<your-oidc-id>` after authentication. Make sure that your valid redirect URIs includes an entry that matches this, and that you're using a different id than what you're using for DX. You may also have to modify your Ingress/Gateway API configuration so that `/oidcclient/redirect/<your-oidc-id>` redirects to the Leap service. |
| 88 | + |
| 89 | + 4. Add the following config properties related to OIDC in the `values.yaml` file. |
| 90 | + |
| 91 | + The following properties must be set to complete the OIDC configuration: |
| 92 | + |
| 93 | + - `userLookups`: Set this to `false` to disable user lookups, which is not available when configured with OIDC. |
| 94 | + - `userGroups`: Set this to `false` to disable group lookups, which is not available when configured with OIDC. |
| 95 | + - `postLogoutRedirectURL`: Set this to the URL to which Leap will redirect the browser after a user logs out. This is necessary to complete the loop with the OIDC IdP. |
| 96 | + |
| 97 | + ```yaml |
| 98 | + configuration: |
| 99 | + leap: |
| 100 | + leapProperties: | |
| 101 | + ibm.nitro.NitroConfig.userLookup=false |
| 102 | + ibm.nitro.NitroConfig.userGroups=false |
| 103 | + ibm.nitro.LogoutServlet.postLogoutRedirectURL=https://myOIDCServer.com/realms/Leap/protocol/openid-connect/logout?client_id=hcl-leap-oidc-client&post_logout_redirect_uri=https://myLeapServer.com/apps/secure/org/ide/manager.html |
| 104 | + ``` |
| 105 | + |
| 106 | + For more details on setting Leap properties, refer to [Leap properties](https://opensource.hcltechsw.com/leap-doc/latest/helm_leap_properties.html). |
| 107 | + |
| 108 | + 5. Perform a Helm upgrade to apply your changes. |
| 109 | + |
| 110 | + 6. Restart the Leap pod. After restarting the Leap pod, accessing Leap should redirect you to authenticate using your OIDC IdP. |
| 111 | + |
| 112 | + For example, the following screenshot shows an authentication page accessed using Keycloak: |
| 113 | + |
| 114 | +  |
0 commit comments