This content applies only to CloudBees CI on modern cloud platforms.
When using web-based security realms, such as Security Assertion Markup Language (SAML) or OpenID Connect (OIDC), each allowed redirect URI must be listed in the Identity Provider (IdP) to prevent open redirect vulnerabilities.
In a CloudBees CI installation, single sign-on (SSO) typically goes through the operations center. However, if the operations center is offline, the sign on occurs directly on each controller if the corresponding security realm plugin is installed. As a result, the redirect URIs for each controller must be registered with the IdP which can be cumbersome to manage, especially since a new entry must be added for each controller and IdPs often limit the number of allowed redirect URIs.
To address this issue, CloudBees provides the SSO Relay service, an optional component that can be installed as part of CloudBees CI on modern cloud platforms. SSO Relay is highly available, can be scaled independently of the operations center and controller, and streamlines redirect URI management by serving as a single redirect URI for all controllers. Instead of listing individual controller redirect URIs, only the SSO Relay redirect URI needs to be registered with the IdP.
Enable the SSO Relay service
You must first enable the SSO Relay service using the CloudBees CI Helm chart in the same namespace as the operations center. If you are using multiple clusters, install one instance of the SSO Relay service in each cluster.
To enable the SSO Relay service:
-
Update your CloudBees CI Helm chart
values.yamlfile to enable the SSO Relay service in the operations center namespace.SsoRelay: enabled: true -
Pass the required
values.yamlfile tohelm installorhelm upgrade. For more information, refer to Install CloudBees CI on modern cloud platforms on Kubernetes or Upgrade CloudBees CI on modern cloud platforms. -
Verify that the SSO Relay pods are running in the operations center namespace:
$ kubectl get po -l app.kubernetes.io/component=ssorelay NAME READY STATUS RESTARTS AGE cloudbees-sso-relay-7f6856cf9c-zsxwd 1/1 Running 0 89m
Configure your IdP for SSO Relay
Once you have enabled the SSO Relay service, you must configure your IdP to use SSO Relay for authentication. To configure your IdP for SSO Relay, you must add the appropriate redirect URIs to your IdP configuration, based on your security realm (SAML or OIDC) and whether you are using subdomains for your controllers.
Given the following Helm values when installing the CloudBees CI Helm chart:
OperationsCenter: HostName: cloudbees.example.com Protocol: https
Allow the following redirect URIs in your IdP, based on your security realm and subdomain configuration:
| Security Realm | Subdomain=false |
Subdomain=true |
|---|---|---|
SAML |
|
|
OIDC |
|
|
| CloudBees recommends keeping the operations center redirect URIs in your IdP configuration until you validate SSO Relay is working correctly, allowing temporary fallback to the operations center if needed. After validation, remove the operations center redirect URIs from your IdP configuration. |
Configure SSO Relay for authentication
Once you have configured your IdP for SSO Relay, you must configure the operations center and controllers to use SSO Relay for SAML or OIDC authentication. To configure SSO Relay for authentication, follow the instructions for your security realm:
Configure SSO Relay for SAML authentication
Follow these steps to enable SSO Relay integration with SAML-based authentication in your environment.
|
Before proceeding, ensure all operations center and controller deployments meet the following requirements:
|
You can configure SSO Relay for SAML authentication using either of the following methods:
Configure SSO Relay for OIDC authentication
Follow these steps to enable SSO Relay integration with OIDC-based authentication in your environment.
|
Before proceeding, ensure all operations center and controller deployments meet the following requirements:
|
You can configure SSO Relay for OIDC authentication using either of the following methods:
Configure SSO Relay for OIDC in the UI
To install CloudBees SSO Relay:
-
Select in the upper-right corner to navigate to the Manage Jenkins page.
-
Select Security, scroll down to Login with Openid Connect, and then in the Properties section, select CloudBees SSO Relay.
Figure 2. SSO Relay property for OIDC
Validate the SSO Relay service
Once you have configured SSO Relay authentication, validate that SSO Relay is working correctly by stopping the operations center and verifying that you can still sign in to each controller.
To further validate SSO Relay functionality, inspect the network tab in your browser’s developer tools to confirm that authentication requests are routed through the SSO Relay service.
Scale the SSO Relay service
You can scale the SSO Relay service independently of the operations center and controller deployments to meet your availability and performance requirements.
By default, the SSO Relay service deploys a single replica. To increase the number of replicas, update the values.yaml file used to install the CloudBees CI Helm chart:
SsoRelay: enabled: true controller: replicas: 2 podDisruptionBudget: minAvailable: null maxUnavailable: 1
This configuration sets two replicas and updates the pod disruption budget to allow one replica to be unavailable during voluntary disruptions, such as node maintenance or cluster upgrades.
To view all available configuration options for the CloudBees CI Helm chart, run the following command:
helm show values cloudbees/cloudbees-core
For more information about scaling and high availability options, refer to the Helm values documentation.