Using single sign-on (SSO) in operations center

5 minute read

Since May 2020, by default, the single sign-on (SSO) process redirects the browser to the Jenkins Root URL configured in the targeted master.

This update was introduced in the following plugin versions:

Using single sign-on (SSO) improves the user experience by allowing a single login for access to multiple masters or from operations center to masters. All of the SSO flow is based on HTTP redirects, so there is no action required from the user. As an entry point to a master, the security is guaranteed by several verifications of incoming requests and data.

Figure 1. SSO flow between operations center and masters

To enable SSO in operations center:

To enable SSO in operations center you must have Administrator permissions.
  1. From the operations center dashboard, select Manage Jenkins.

  2. Under Security, select Configure Global Security.

  3. Under Client master security, select an SSO option for Security Setting Enforcement.

    • Single Sign-On (security realm and authorization strategy) recommended option

      Masters connected to the operations center inherit the security realm configuration as well as the authorization strategy. On the master security configuration page, these options are disabled and labeled Managed by operations center security policy. For example, if the operations center is configured with the Role-based matrix authorization strategy, this cannot be updated at the master level.

      Figure 2. Disabled configurations on master
    • Single Sign-On (security realm only)

      Masters connected to the operations center inherit the realm configuration only, meaning the master inherits data from the user database, but the authorization strategy can be configured at the master level. For example, even if the operations center is configured with the Role-based matrix authorization strategy, the master can be still be configured with the Logged-in users can do anything option.

See Security recommendations for more detailed information and advice on security configurations.

Configuring the Jenkins Root URL

The Jenkins Root URL must be configured if you are using single sign-on (SSO). An empty Jenkins Root URL will cause single sign-on to quit working unless you have applied the masterRootURLStrictCheckingDisabled flag. See Disabling the verification of the Jenkins Root URL for more information.

To set a Jenkins URL on the master:
  1. Log in to the specific master as an ADMINISTER.

  2. Navigate to Manage Jenkins > Configure System > Jenkins Location.

  3. Enter the Jenkins URL in the text box.

  4. Select Save.

Disabling the verification of the Jenkins Root URL

If your network configuration does not allow you to use this configuration for any reason, you can disable the verification of the master Jenkins URL by using a flag on the operations center that is propagated to masters within 1 minute.

For security reasons, the verification of the master Jenkins Root URL is activated by default.

Disabling the check of the master Jenkins URL exposes the product to an Open Redirect Vulnerability. This flag is made mainly for backward compatibility reasons, and should be used as a temporary way to fix the master Jenkins URL and enabled again as soon as possible.

Using the masterRootURLStrictCheckingDisabled flag on the Script Console

The masterRootURLStrictCheckingDisabled flag can be enabled temporarily on the Script Console of the operations center by navigating to Manage Jenkins > Script Console and entering the following script:

com.cloudbees.opscenter.server.sso.SSOConfiguration.masterRootURLStrictCheckingDisabled = true

The flag will be erased by a restart of the operations center, otherwise you can disable the flag with the following script:

com.cloudbees.opscenter.server.sso.SSOConfiguration.masterRootURLStrictCheckingDisabled = false
To check the current value of the flag, enter the following command:
println("Is strict checking of master's Jenkins URL disabled ? " + com.cloudbees.opscenter.server.sso.SSOConfiguration.masterRootURLStrictCheckingDisabled)
If you get a groovy.lang.MissingPropertyException: No such property exception on this command, it could be because the operations center has plugins with versions older than the one with the strict checking on master Jenkins URL.

Using the masterRootURLStrictCheckingDisabled flag on the command line

The masterRootURLStrictCheckingDisabled flag can also be set as a System property on the command line to run operations center using the following command:

java -Dcom.cloudbees.opscenter.server.sso.SSOConfiguration.masterRootURLStrictCheckingDisabled=true -jar core-oc.war
Adding this system property will require a restart of operations center and should be temporary.

Troubleshooting SSO

If you encounter trouble while using single sign-on (SSO) to log in or access one or several masters, check the following common solutions:

  • Error page on master reads: "This master Root URL is empty, but is required by operations center Single Sign-On."

    This message indicates that you need to set up a Jenkins Root URL in the master.

  • When accessing a master, I am redirected to a wrong or not reachable URL.

    During the single sign-on (SSO) process, the browser is redirected to the URL configured in the master. This can be fixed by Configuring the Jenkins Root URL.

  • I need to verify one or several masters attached to a single operations center have the Jenkins URL configured

    You can use a cluster operation to verify all masters connected to an operations center have the Jenkins URL configured.

    Enter the following script in a cluster operation:

    if(JenkinsLocationConfiguration.get().getUrl() == null ) exit 1

    If the global status of the operation is a success, then all masters have a Jenkins URL configured.

    If the global status of the operation is a failure, then at least one master has an empty Jenkins URL configured. Check at the end of the logs to see which master will need to be configured.

Single sign-on fallback behavior

The SSO fallback feature supports single sign-on plugins like the SAML plugin, Crowd Integration plugin, and Google Login plugin, ONLY if a compatible version of the plugins is installed on both the master as well as the operations center and the external identity provider (IDP) is configured correctly, meaning return URLs for each master are provided and the IDP can support more than one return URL. When creating masters using operations center SSO with an external SSO provider (SAML, Crowd, Google Login, etc.), you must manually configure that SSO with URLs of all the masters in the cluster for operations center SSO failover to work. Otherwise, the operations center authentication fallback feature will not work and the SSO provider will provide an error saying the masterURL is an invalid redirectUrl and will refuse to authenticate.

When using either of the single sign-on security modes, operations center supports a fallback mechanism to increase resiliency across the platform. If operations center goes offline, the Client Master connected to that operations center will detect the inability to connect to operations center, then fallback to use the same Security Realm as defined in operations center, but locally from the master. For example, if you use the Active Directory plugin from operations center and enable single sign-on, the same Active Directory configuration will be pushed to Client Masters in the case of an operations center outage. This fallback behavior allows Client Masters to continue to authenticate until operations center connectivity is restored.

Given this fallback behavior, you must ensure any custom plugins used for authentication (i.e. a custom security realm) in combination with operations center’s single sign-on behavior are installed on operations center and all connected Client Masters participating in single sign-on.