Skip to main content
Code42 Support

Configure Okta 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 Okta. In this article, Okta 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 Okta 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: Prepare Okta

Okta provides a predefined application entry for CrashPlan PROe that simplifies the configuration process. This method requires two-way communication between Okta and your master server. If two-way communication is not available between Okta and your master server, you can create a new Okta application based on the custom SAML template. For more information about configuring Okta, see the Okta documentation.

Okta option A: Add the Okta application for CrashPlan PROe

Use this method to configure Okta if there is two-way communication between your Code42 master server and the Okta identity provider. We recommend leaving the settings at the default values unless otherwise specified.

  1. Sign in to your Okta dashboard at your custom Okta URL.
  2. Add the CrashPlan PROe application.
  3. Follow the wizard steps to configure the CrashPlan PROe application for Okta.
  4. When you are prompted to configure general settings, configure the master server URL.
    1. In Server Url, enter https://master-server.example.com:4285.
      Replace master-server.example.com with the hostname or IP address of your Code42 master server.
    2. Leave the other settings at the default values, including LoginURL.
  5. When you are prompted to configure sign-on options, select SAML 2.0.
  6. Download the metadata file or save the URL to the file.
    This file must be made accessible to your master server.
    • If your master server has two-way communication with Okta, right click Identity Provider metadata to save the URL.
    • If your master server is behind a firewall, click Identity Provider metadata to download the file.

Okta option B: Create a Code42 application based on the Okta custom SAML template

Use this method if Okta cannot initiate communication with your Code42 master server due to firewall configuration or network topology. We recommend leaving the settings at the default values unless otherwise specified.

  1. Sign in to your Okta dashboard at your custom Okta URL.
  2. Add the Template SAML 2.0 App application.
  3. Follow the wizard steps to configure the CrashPlan PROe application for Okta.
  4. Configure general settings by filling in the following fields with the indicated values.
    In the following examples, replace master-server.example.com with the the fully qualified domain name (FQDN) or IP address of your Code42 master server.
    • Application label: Code42 platform
    • Post Back URL:
      https://master-server.example.com:4285/api/SsoAuthLoginResponse
    • Name ID Format: EmailAddress
    • Recipient: https://master-server.example.com:4285/api/SsoAuthLoginResponse
    • Audience restriction: https://master-server.example.com:4285
    • Request: Uncompressed
    • Destination: https://master-server.example.com:4285/api/SsoAuthLoginResponse
    • Default Relay State: https://master-server.example.com:4285
    • Attribute Statements: uid|${user.userName}
  5. Skip the user assignment step.
  6. After the template is configured, download the identity provider metadata file.
    1. Select the custom application, then click Sign On.
    2. Click View Setup Instructions.
    3. Copy the text in Provide the following IDP metadata to your SP provider and save it using a plain text editor.
      This file must be made accessible to your master server.

Step 3: Add Okta to your Master server

The Okta 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 Okta 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 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 Okta 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.

External resources