Skip to main content
Code42 Support

Configure InCommon for SSO in your Code42 environment

Applies to:
  • CrashPlan PROe

Overview

This tutorial explains how to configure your Code42 environment to use single sign-on (SSO) with the InCommon identity federation. In this article, InCommon 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.

Compatible Code42 platform components

For version 4.1.6 and later, the Code42 platform components bundled with the enterprise server support SSO.

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

Considerations

Code42 master server
  • You must have an on-premises master server running version 4.1.6 or later.
  • 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. This 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.
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. One of the following directory services provides user management:
    • Local Code42 platform directory
    • LDAP
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

Configure SSO certificate settings

  1. If your SSO identity provider uses encryption keys longer than 128 bits, configure your master server to accept longer encryption keys.
  2. If your security policy requires a CA-signed certificate for SSO, replace the SSO certificate on your master server.

Configure administration console security

  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 InCommon to your master server

Add InCommon to your master server, then add one or more InCommon identity providers.

Add the InCommon identity federation

Skip this step if InCommon is already added to your master server.

  1. Sign in to the administration console on your master server.
  2. Navigate to Settings > Security > Single Sign-On.
  3. Click Add Identity Provider or Federation.
  4. In Identity Provider metadata URL, enter the URL for the identity federation metadata XML file:
    http://wayf.incommonfederation.org/InCommon/InCommon-metadata.xml
  5. Click Continue.
    Additional identity provider settings appear.
    Add identity federation
  6. In Display name, enter a display name for the identity federation.
  7. In Path to identity provider display name, enter a metadata extension to extract provider display names from the identity federation metadata XML file.
    For example: //mdui:DisplayName
    • When the path is configured, display names for identity providers are pulled from the federation metadata XML file and presented to users as a choice when they sign in using SSO.
    • When the path is not configured, the full paths for the identity providers are displayed.
  8. (Optional) Customize mappings between Code42 platform user attributes and identity provider SSO assertion attributes.
    1. Deselect Use default mapping.
    2. Select Use nameId.
    3. Configure mapping settings for each Code42 platform user attribute:
      • Email: Enter the SSO attribute that contains user email addresses.
      • First name: Enter the SSO attribute that contains user first names.
      • Last name: Enter the SSO attribute that contains user last names.
  9. Click Save.

Add an InCommon identity provider

  1. Sign in to the administration console on your master server.
  2. Navigate to Settings > Security > Single Sign-On.
  3. Under the identity federation, click Add identity provider.
  4. From Choose identity provider, select an identity provider.
  5. Click Continue.
    Additional identity provider settings appear.
    Add identity provider from an identity federation
  6. From Choose identity provider, select an identity provider.
  7. (Optional) In Display name, enter a display name for the identity provider. Leave Display name bank to use the default name from the identity federation metadata file.
    When two or more identity providers are offered in a Code42 environment, the identity provider name is presented to users as a choice when they sign in using SSO.
  8. (Optional) Customize mappings between Code42 platform user attributes and identity provider SSO assertion attributes.
    1. Deselect Use default mapping.
    2. Configure mapping settings for each Code42 platform user attribute:
      • Username: Select Use Attribute tag to map a custom SSO attribute to the Code42 platform username.
        For many InCommon identity providers, the attribute tag is eduPersonPrincipalName.
      • Email: Enter the SSO attribute that contains user email addresses.
      • First name: Enter the SSO attribute that contains user first names.
      • Last name: Enter the SSO attribute that contains user last names.
  9. Click Save.

Step 3: Prepare InCommon

Submit the Code42 master server metadata file to the identity federation.
The master server metadata file is located at:
https://master-server.example.com:4285/api/SsoAuthSpMetadata

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.
      Organization SSO configuration
    4. Deselect Inherit security settings from parent.
    5. From Select an authentication method, choose SSO.
      The configured SSO identity providers appear.
    6. Select the identity providers that you want to offer for the organization.
    7. From Select a directory service, select Local for testing purposes.
      Additional steps must be performed to use SSO with LDAP.
    8. Click Save.
  6. Sign in to the administration console as the test user to verify that SSO is working.
    1. Connect to the administration console.
      Administration console sign in screen with single sign-on
    2. On the sign in screen, click Sign on using Single Sign-On.
    3. If more than one identity provider is offered in your Code42 environment, select an identity provider from the menu, then click CONTINUE.
      The identity provider sign in page appears.
    4. Enter your test user's SSO credentials to sign in.

Step 5: Modify the CrashPlan app to enable SSO

CrashPlan PROe only. SharePlan does not require modifications 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. If two or more identity providers are offered in your Code42 environment, tell the users in each organization which identity provider they should choose when they sign in.

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

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.
    Organization SSO configuration
  5. Deselect Inherit security settings from parent.
  6. From Select an authentication method, choose SSO.
    The configured SSO identity providers appear.
  7. Select the identity providers that you want to offer for the organization.
  8. From Select a directory service, select Local.
    Additional steps must be performed to use SSO with LDAP.
  9. Click Save.

Option B: Enable SSO for all organizations

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

  1. Sign in to the administration console on your master server.
  2. Navigate to Settings > Organization.
  3. Click Security.
  4. From Select an authentication method, choose SSO.
    The configured SSO identity providers appear.
  5. Select the identity providers that you want to offer to your organizations.
  6. From Select a directory service, select Local.
    Additional steps must be performed to use SSO with LDAP.
  7. 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.
SharePlan registration
The SharePlan app cannot be used to register SSO-enabled user accounts. If your Code42 environment uses SharePlan, deploy the CrashPlan app to create user accounts before deploying the SharePlan app.

Option B: Add users in the administration console

Use the administration console to 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.

What to expect

Signing in with SSO

When an organization is configured to use one or more identity providers, users in that organization must select the SSO option when signing in to Code42 applications or the administration console.

Multiple identity providers

If more than one SSO identity provider is offered by your Code42 environment, users are presented with a list of identity providers to choose from. The list includes all identity providers offered throughout your Code42 environment because the users' organizations are not known until they sign in.

Reduced authentication prompts

When a user signs in with SSO, the user does not need to reenter credentials for subsequent authentication attempts until the SAML authentication token expires. A SAML token applies to an application rather than a device, which means that a user might need to enter credentials again when signing into a different app. For example:

  • Signing in to the SharePlan app does not also authenticate the CrashPlan app because they are different apps.
  • Signing in to the administration console also authenticates the SharePlan web app because they are accessed via a web browser.

Losing access to an identity provider

A user might lose access to an identity provider for the following reasons:

  • A user is moved to an organization that does not offer his or her identity provider
  • An identity provider is removed from an organization or federation

In either case, all user devices associated with that identity provider are automatically deauthorized by your master server. Users cannot sign in until they are added to the authentication service configured for the organization.

External resources