Using Single Sign On (SSO)

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.

As an entry point to a master, the security is guaranteed by several verifications of incoming requests and data.

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:

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

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.