Skip to main content
Code42 Support

Configuring Shibboleth For SSO In Your Code42 Environment (Version 4.1.4 And 4.1.5)

Applies to:
  • CrashPlan PROe

Overview

This tutorial explains how to configure your Code42 environment (version 4.1.4 and 4.1.5) to use single sign-on (SSO) with Shibboleth. In this article, Shibboleth is also referred to as an identity provider.

This article assumes you are already familiar with SSO and the SAML standard. For more information about how the Code42 platform implements SSO, see our Introduction To Single Sign-On.

If your Code42 environment is running version 4.1.6 or later, see our related Shibboleth article.

Compatible Code42 platform components

For versions 4.1.4 and 4.1.5 of the Code42 platform, some components support SSO.

Compatible With SSO
  • CrashPlan app for Windows, OS X, and Linux
  • Administration console
Incompatible With SSO
  • SharePlan app for Windows and OS X
  • SharePlan app for iOS and Android
  • SharePlan web app
  • CrashPlan apps for iOS, Android, and Windows Phone

Considerations

Code42 Master server
  • You must have an on-premises master server.
  • The master server's SSO entityID is generated based on the administration console Website protocol, host and port and Require SSL to access console fields. Do not modify these settings after configuring SSO.
  • Your master server must be able to access the Identity Provider metadata file.
  • The Code42 platform supports service provider-initiated SSO but does not support identity provider-initiated SSO. That means that:
    • Users cannot log in to your Code42 environment from an identity provider website or application.
    • You cannot automatically provision Code42 platform user accounts from the identity provider.
  • The following warning message (found in logs on your master server) is normal: “Not syncing SSO metadata at this moment due to rate limiting." Rate limiting prevents syncing with your identity provider more than once per minute.
Authentication And User Management
  • Users that sign in with SSO must exist in your Code42 environment, and their usernames must match SSO.
  • SSO provides user authentication but does not provide user management. The local Code42 platform directory service provides user management.
CrashPlan app
External authentication systems
Our Customer Champions can help with authentication issues caused by interaction with Code42 products. However, troubleshooting authentication issues outside your Code42 environment is beyond the scope of our Customer Champions.
For assistance with external authentication systems, contact your authentication vendor.

Before you begin

Verify Identity Provider Configuration
  • Make sure the SSL certificate of your SSO identity provider has been signed by a trusted Certificate Authority (CA).
  • Make sure you have administrative access to the identity provider or have contact with an identity provider administrator.
Verify Network Configuration
  • Configure your private network, Internet, and VPN settings to allow client devices to communicate with your identity provider on ports 80 and 443. Test client connectivity to the identity provider before you proceed.
  • If you want to use URL-based metadata exchange to configure your master server and identity provider to work together, make sure two-way communication is available between them on TCP ports 80 and 443. If two-way communication is not available or not allowed, you must download the identity provider's metadata file and make it accessible to your master server.
  • Confirm the required ports with your identity provider to determine if custom ports are being used.

Step 1: Prepare your Master server

  1. Install an SSL certificate that has been signed by a trusted Certificate Authority (CA).
  2. If your identity provider does not allow ports in SSO metadata, forward port 443 to port 4285 for inbound connections to the master server.
  3. Update your master server's default administration console address to use SSL:
    1. Go to Settings > Server.
    2. Change your master server's Website protocol, host and port to use https and port 4285.
      If port port 443 is mapped to 4285, exclude the port.
      • Example without port forwarding: https://master-server.example.com:4285
      • Example with port forwarding: https://master-server.example.com
    3. Click Save.
  4. Require SSL for administration console access to your master server:
    1. Go to Settings > Security.
    2. Select Require SSL to access console.
    3. Click Save.
    4. Restart the master server.
Port mapping
If you mapped port 443 to 4285, omit 4285 from the example URLs listed in this article.

Step 2: Add Shibboleth to your Master server

The Shibboleth metadata file must be accessible to your master server to complete this step. If your network configuration prevents URL-based metadata exchange, or if you need to manually edit the identity provider's metadata file, see Making The Shibboleth Metadata File Accessible below.

  1. Sign in to the administration console on your master server.
  2. Navigate to Settings > Security > Single Sign-On.
    Adding an identity provider in the administration console
  3. Select Enable.
  4. In Identity provider name, enter a display name for the identity provider with a preceding backslash and space.
    Example: \ Identity Provider Name
  5. In Identity Provider metadata URL, enter the URL for the identity provider metadata XML file.
  6. Click Save.
    • If the settings are successfully saved, you will see an alert box in the lower left of the console screen stating "Your changes have been saved." and the Service provider metadata (URL) is now generated and visible.
    • If you receive a "System error" warning instead, verify the URL of the identity provider metadata file.
  7. If necessary, set CLI system properties to change the default username attribute mappings.

Step 3: Prepare Shibboleth

There are two ways to exchange metadata between your master server and the Shibboleth identity provider. The URL-based method method requires two-way communication between Shibboleth and your master server. If two-way communication is not available, you can manually upload the master server's metadata file to the identity provider. For more information about adding a service provider to Shibboleth, see the Shibboleth documentation.

Shibboleth option A: URL-based metadata exchange

Configure the master server as a file-backed HTTP metadata provider.

  1. Make sure the Shibboleth identity provider can access the master server's metadata URL.
    The master server metadata file is located at:
    https://master-server.example.com:4285/api/SsoAuthSpMetadata
  2. Configure your Shibboleth identity provider to accept authentication requests from your master server.
    • Edit the file ${Shibboleth}/conf/relying-party.xml.
    • Add or modify the MetadataProvider element for your master server.
      <MetadataProvider xsi:type="FileBackedHTTPMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
                        id="Code42_Enteprise_Server"
                        metadataURL="https://master.server-example.com:4285/api/SsoAuthSpMetadata"
                        backingFile="/tmp/idp-metadata.xml" />
      
      Set the following values by modifying the text between the quotes:
      • id: Enter a name for your master server.
      • metadataURL: For URL-based metadata exchange, enter the master server's metadata URL.
      • backingFile: Enter a path and filename on the identity provider where the backup copy of the master server's metadata file is stored.

Shibboleth option B: File-based metadata exchange

Configure the master server as a filesystem metadata provider.

  1. Download the master server's metadata file and upload it to the identity provider.
    The master server metadata file is located at:
    https://master-server.example.com:4285/api/SsoAuthSpMetadata
  2. Configure your Shibboleth identity provider to accept authentication requests from your master server.
    • Edit the file ${Shibboleth}/conf/relying-party.xml.
    • Add or modify the MetadataProvider element for your master server.
      <MetadataProvider xsi:type="FilesystemMetadataProvider" xmlns="urn:mace:shibboleth:2.0:metadata"
                        id="Code42_Enterprise_Server"
                        metadataFile="/path/to/my/metadata.xml" />
      
      Set the following values by modifying the text between the quotes:
      • id: Enter a name for your master server.
      • metadataFile: Enter the path to the master server metadata file on the Shibboleth identity provider.

Step 4: Test SSO authentication

To avoid impacting your production environment, use a test organization to verify that SSO is working properly.

  1. If necessary, add a test user to the identity provider.
  2. Sign in to the administration console on your master server.
  3. Create a test organization.
  4. Create a user in the test organization that matches the identity provider test user.
  5. Configure the test organization to use SSO.
    1. Navigate to Organizations, then select the organization.
    2. From the Action menu, select Edit.
    3. Click Security.
      Enable SSO for an organization
    4. Deselect Inherit security settings from parent.
    5. Select Use <identity provider name> for authentication.
    6. Click Save.
  6. Sign in to the administration console as the test user to verify that SSO is working.
    1. Use a web browser to connect to the administration console.
      Administration console sign in screen
    2. On the sign in screen, click Sign on using Single Sign-On.
      The identity provider sign in page appears. This page varies by identity provider.
    3. Enter your test user's SSO credentials to sign in.

Step 5: Modify the CrashPlan app to enable SSO

The CrashPlan app is not configured to allow SSO by default. To use SSO in your Code42 environment, create an SSO-enabled CrashPlan app installer for new devices, and modify existing CrashPlan devices to enable SSO.

Modify the CrashPlan app installer and deploy it to new users

Modify the CrashPlan app installer to enable SSO authentication. Use this installer to set up the CrashPlan app for users that authenticate with SSO.

  1. Follow the instructions in Preparing The CrashPlan app For Deployment to set SSO custom properties.
  2. During the modification process, modify the following custom properties to enable SSO:
    1. Set registrationKey to the registration key for the appropriate organization.
    2. (Optional) To allow new users to start backing up the default file selection immediately without authenticating, set password to ${deferred}.
    3. Set ssoAuth.enabled to true.
    4. (Optional) To require SSO authentication and disable other authentication methods, set ssoAuth.required to true.
      When SSO authentication is required, users cannot sign in unless their organization is configured to use SSO.
    5. (Optional) To customize the SSO message that is displayed to users, modify the ssoAuth.provider value.
      The default message is "Login with single sign-on".
  3. After you set the SSO properties, follow the instructions to generate the CrashPlan app installers.
  4. Distribute the modified CrashPlan app installer to users that sign in using SSO.

Modify existing CrashPlan devices to enable SSO

If users in your Code42 environment use CrashPlan apps that are not SSO-enabled, modify each existing CrashPlan app to enable SSO.

Desktop management software
We recommend using desktop management software to automate this process.

Option A: Uninstall and install the SSO-enabled CrashPlan app

  1. Uninstall the CrashPlan app.
  2. Use the SSO-enabled CrashPlan app installer to install CrashPlan.

Option B: Modify an installed CrashPlan app to enable SSO

  1. Download our custom content template.
  2. Extract the template and locate the custom.properties file.
  3. Open the custom.properties file in a plain text editor.
  4. Set the address to the hostname and port of your master server.
  5. Verify that ssoAuth.enabled is set to true.
  6. (Optional) To require SSO authentication and disable other authentication methods, set ssoAuth.required to true.
    You do not need to make any further modifications to the file. If you have chosen to use a custom.properties file that has already been modified, note that settings not related to SSO may affect CrashPlan app configuration settings.
  7. On the CrashPlan device, create the following directory and place the custom.properties file inside:
    • Windows: C:\Program Files\CrashPlan\custom
    • OS X: /Library/Application Support/CrashPlan/custom
    • Linux: /usr/local/crashplan/custom
    • Solaris: /opt/sfw/crashplan/custom
  8. Restart the CrashPlan service.
  9. To sign in with single sign-on, deauthorize the CrashPlan device using one of these methods:

Step 6: Configure organizations to use SSO

Enable SSO for one or more organizations to start using SSO in your Code42 environment.

Option A: Enable SSO for a specific organization

  1. Sign in to the administration console on your master server.
  2. Navigate to Organizations, then select the organization.
  3. From the Action menu, select Edit.
  4. Click Security.
    Enable SSO for an organization
  5. Deselect Inherit security settings from parent.
  6. Select Use <identity provider name> for authentication.
  7. Click Save.

Option B: Enable SSO for all organizations

Modify the top-level organization settings to enable SSO for all organizations.

Disabling inheritance
If inheritance is disabled for an organization, that organization is not affected by changes to its parent organization.

  1. Sign in to the administration console on your master server.
  2. Navigate to Settings > Organization > Security.
  3. From the Action menu, select Edit.
  4. Click Security.
  5. Select Use <identity provider name> for authentication.
  6. Click Save.

Step 7: Add new users that sign in with SSO

New users can create their own accounts when they first sign in to a SSO-enabled CrashPlan app. Alternatively, you can use the administration console to create user accounts.

Option A: Deploy the SSO-enabled CrashPlan app

Distribute the SSO-enabled CrashPlan app installer to new users.

  • New users can register accounts in your Code42 environment by signing in with SSO credentials.
  • New users begin backing up the default file selection immediately without authenticating if all of the following conditions are met:
    • The organization is configured to auto-start backups.
    • The CrashPlan app is modified to contain the correct organization registration key.
    • The CrashPlan app is modified to defer the user's password.
      Users are not able to sign in to the CrashPlan app or restore unless they have a valid SSO account.

Option B: Add users in the Administration console

Use the administration console to manually add users to an organization that uses SSO.

  • Verify that the users in the organization exist in the SSO identity provider used by the organization.
  • Make sure that the Code42 environment usernames match the SSO usernames.

Making the Shibboleth metadata file accessible

If your identity provider or network configuration prevents URL-based metadata exchange, or if you need to manually edit the identity provider's metadata file, you must make the identity provider metadata file accessible to your master server. There are several ways to make the metadata file available:

  • Place the metadata file in the installs directory on your master server.
  • Make the metadata file available on your corporate web server.

Option A: Place the metadata file on the Master server

  1. Add the identity provider metadata file to the installs directory on your master server:
    • Linux: /opt/proserver/installs/
      Applies to enterprise servers installed as root on Ubuntu
    • Windows: C:\Program Files\CrashPlan PROe Server\installs\
    • OS X: /Applications/PROServer.app/Contents/Resources/Java/installs/
  2. Set file permissions so that the SAML metadata file is readable by the enterprise server service. In Linux, the numeric file mode 755 should suffice, although the ideal settings for your environment might differ.
  3. Use a web browser to verify that you can access the metadata file.
    For example: https://master-server.example.com:4285/installs/<metadata_filename>
    • Replace master-server.example.com with the fully qualified hostname or IP address of your master server.
    • Replace <metadata_filename> with the name of the metadata file.
    • If you mapped port 443 to 4285, do not include the port in the URL.

Option B: Place the metadata file on a corporate web server

  1. Add the identity provider metadata file to a web server that is accessible to your master server.
  2. Record the URL for the metadata file.
  3. Use a web browser to verify that you can access the metadata file.