Using single sign-on (SSO) in Operations Center

SecurityAudit and compliance

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

Configuring SSO in Operations Center

When using single sign-on (SSO) for an Operations Center, you may want specific masters to either not participate in SSO, or participate but manage authorization differently than Operations Center. These options are enabled both globally in the Global Security for Operations Center, and for each master that will manage authentication/authorization separately.

To configure SSO options in Operations Center:

To configure SSO options 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. When using CloudBees Role-Based Access Control plugin the roles are managed by Operations Center and the groups applied at the masters' root will be those that apply to the master item in Operations Center. 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
    • Do not enforce security setting on masters

      Masters connected to the Operations Center do not inherit any security settings or participate in single sign-on (SSO) provided by Operations Center.

    • 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.

  4. (Optional) Select the Allow client masters to opt-out checkbox if you want the ability allow specific masters to opt-out of the Operations Center authentication and/or authorization strategy.

    This option will only be displayed if you select either Single Sign-On (security realm and authorization strategy) recommended option or Single Sign-On (security realm only) for Security Setting Enforcement.
    If you do not update the Security Setting Enforcement Opt-out option for each individual master, the Opt-out option’s default setting is Use global enforcement. See Configuring options for individual masters for more information.
  5. Select Save.

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

Configuring options for individual masters

If you select either Single Sign-On (security realm and authorization strategy) recommended option or Single Sign-On (security realm only) for the Operations Center Security Setting Enforcement and select the Allow client masters to opt-out checkbox, you can allow specific masters to opt-out of the security enforcement. This option is useful if you want masters to have authentication and authorization or just authentication managed by default, but also have masters that you want to manage the security independent of Operations Center or if you are using Configuration as Code (CasC) for Controllers and want to manage the role-based access control (RBAC) groups and roles as code for given masters.

To enable individual masters to opt-out of Operations Center security enforcement:

  1. From the Operations Center dashboard, select the gear(Manage) icon to the left of the master item.

  2. In the left pane, select Configure.

  3. Scroll down to the Security Setting Enforcement section.

  4. Select one of the following options:

    • Enforce Authentication only: Selecting this option means the master will take part in Operations Center single sign-on (SSO) only, but will manage Authorization strategy separately.

    • Opt Out of all security enforcement: Selecting this option means the master will not take part in Operations Center enabled single sign-on (SSO) or have its Authorization strategy managed by Operations Center. Additionally, if the global security configuration security policy was enforcing any other settings - these will also not be enforced.

      Updating an existing master to use this option could leave your master unsecured.
    • Use global security enforcement: Selecting this option means the master will not be opted out and enforcement will happen as per the Operations Center global security configuration.

  5. Select Save.

The options displayed in the Security Setting Enforcement section on a master depend on how SSO is configured on Operations Center. The following options are displayed when the following Operations Center SSO settings are selected:

  • Do not enforce security setting on masters

    • No options appear

  • Single Sign-On (security realm and authorization strategy) and Allow client masters to opt-out checkbox is checked

    • Enforce Authentication only

    • Opt Out of all security enforcement

    • Use global security enforcement

  • Single Sign-On (security realm only) and Allow client masters to opt-out checkbox is checked and/or

    • Use global security enforcement

    • Opt Out of all security enforcement

See Configuring SSO in Operations Center for more information.

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.