Using single sign-on (SSO) improves the user experience by allowing a single login for access to multiple controllers or from operations center to controllers. 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 controller, the security is guaranteed by several verifications of incoming requests and data.
Configuring SSO in operations center
When using single sign-on (SSO) for an operations center, you may want specific controllers 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 controller 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. |
-
From the operations center dashboard, select Manage Jenkins.
-
Under Security, select Configure Global Security.
-
Under Client controller security, select an SSO option for Security Setting Enforcement.
-
Single Sign-On (security realm and authorization strategy) recommended option
Controllers 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 controllers' root will be those that apply to the controller item in operations center. On the controller 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 controller level.
Figure 2. Disabled configurations on controller -
Do not enforce security setting on controllers
Controllers 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)
Controllers connected to the operations center inherit the realm configuration only, meaning the controller inherits data from the user database, but the authorization strategy can be configured at the controller level. For example, even if the operations center is configured with the Role-based matrix authorization strategy, the controller can be still be configured with the Logged-in users can do anything option.
-
-
(Optional) Select the Allow client controllers to opt-out checkbox if you want the ability allow specific controllers 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 controller, the Opt-out option’s default setting is Use global enforcement. See Configuring options for individual controllers for more information. -
Select Save.
Refer to Security recommendations for more detailed information and advice on security configurations.
Configuring options for individual controllers
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 controllers to opt-out checkbox, you can allow specific controllers to opt-out of the security enforcement. This option is useful if you want controllers to have authentication and authorization or just authentication managed by default, but also have controllers that you want to manage the security independent of operations center or if you are using Configuration as Code and want to manage the Role-Based Access Control (RBAC) groups and roles as code for given controllers.
To enable individual controllers to opt-out of operations center security enforcement:
-
From the operations center dashboard, select the gear(Manage) icon to the left of the controller item.
-
In the left pane, select Configure.
-
Scroll down to the Security Setting Enforcement section.
-
Select one of the following options:
-
Enforce Authentication only: Selecting this option means the controller 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 controller 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 was enforcing any other settings - these will also not be enforced.
Updating an existing controller to use this option could leave your controller unsecured. -
Use global security enforcement: Selecting this option means the controller will not be opted out and enforcement will happen as per the operations center global security configuration.
-
-
Select Save.
|
The options displayed in the Security Setting Enforcement section on a controller depend on how SSO is configured on operations center. The following options are displayed when the following operations center SSO settings are selected:
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.
-
Log in to the specific controller as an ADMINISTER.
-
Navigate to Manage Jenkins > Configure System > Jenkins Location.
-
Enter the Jenkins URL in the text box.
-
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 controller Jenkins URL by using a flag on the operations center that is propagated to controllers within 1 minute.
For security reasons, the verification of the controller Jenkins Root URL is activated by default.
| Disabling the check of the controller 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 controller 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
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 controllers, check the following common solutions:
-
Error page on controller 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 controller.
-
When accessing a controller, 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 controller. This can be fixed by Configuring the Jenkins Root URL.
-
I need to verify one or several controllers attached to a single operations center have the Jenkins URL configured
You can use a cluster operation to verify all controllers connected to an operations center have the Jenkins URL configured.
Enter the following script in a cluster operation:
if(JenkinsLocationConfiguration.get().getUrl() == null ) exit 1If the global status of the operation is a success, then all controllers have a Jenkins URL configured.
If the global status of the operation is a failure, then at least one controller has an empty Jenkins URL configured. Check at the end of the logs to see which controller 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 controller as well as the operations center and the external identity provider (IDP) is configured correctly, meaning return URLs for each controller are provided and the IDP can support more than one return URL. When creating controllers 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 controllers 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 controller 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 controller. 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 controllers in the case of an operations center outage. This fallback behavior allows client controllers 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 controllers participating in single sign-on. |