Skip to main content

Who is this article for?

Incydr
Code42 for Enterprise
CrashPlan for Enterprise
CrashPlan for Small Business

Incydr, no.

CrashPlan for Enterprise, yes.

Code42 for Enterprise, yes.

CrashPlan for Small Business, no.

This article applies to on-premises authority servers.

Other available versions:

Cloud

HOME
GETTING STARTED
RELEASE NOTES
FAQS
SYSTEM STATUS
Code42 Support

Use the Code42 API to set SAML attributes

Overview

You can integrate any SAML 2.0-compliant identity provider with Code42. By default, you map an identity provider's username and email attributes to Code42.

Starting in version 8.2, for added security and flexibility, you can use Code42 APIs to set the SAML 2.0 context and class references in your identity provider's SSO requests, as well as the digest and signature algorithms to use. See the SAML attributes section below for the list of SAML authentication attributes whose mapping you can customize.

This article describes how to use the following Code42 API resources to customize mapping SAML authentication attributes: 

  • View the current SAML settings: identity-provider-saml-settings/IdentityProviderSamlSettings_View
  • Update the SAML settings: identity-provider-saml-settings/IdentityProviderSamlSettings_Update

Considerations

  • This functionality is available in version 8.2 and later.
  • Your role provides permission to access the data necessary to a given API resource. For example, if you do not have permission to change device settings in the Code42 console, then you don't have permission to change device settings with the API.
  • This process requires use of the Code42 API.
Test SAML settings changes
Changes you make to SAML settings using the procedures in this article are made directly to the identity provider settings in Code42. Ensure you verify that they work properly in a test organization first before using the SAML settings in production.

View current SAML settings

View the current SAML settings for an identity provider in Code42 using the identity-provider-saml-settings/IdentityProviderSamlSettings_View  API resource.

In the following example: 

  • Replace <AuthToken> with the authentication token you obtained in the Authentication section.
  • Replace <ServerURL>:<Port> with the URL and port of your authority server. For example, authority-server.example.com:4285 
  • Replace <IdentityProviderID> with the ID you obtained as described in Identity provider ID.
Copied!
curl -vvv -X GET 'https://<ServerURL>:<Port>/api/v6/identity-provider-saml-settings/view?uid=<IdentityProviderID>' \
-H "Authorization: v3_user_token <AuthToken>"

An excerpt of an example successful response:

{"metadata":{"date":"2019-08-14T15:08:21.892-05:00","headers":[]},"data":{"uid":"913123517744122250","displayName":"Azure","authnContextComparison":"EXACT","authnContextClassRef":["urn:oasis:names:tc:SAML:2.0:ac:classes:Password"],"requestAuthnDigestMethod":"http://www.w3.org/2001/04/xmlenc#sha256","requestAuthnSignatureMethod":"http://www.w3.org/2001/04/xmldsig-more#rsa-sha256","modificationDate":"2019-08-14T10:21:27.826-05:00"}}

For information on the returned values, see the SAML attributes section.

Default SAML settings

When you create a new identity provider in Code42, the default SAML request configuration settings are:

  • authnContextClassReference: Password
  • authnContextComparison: EXACT
  • requestAuthnDigestMethod: http://www.w3.org/2001/04/xmlenc#sha256
  • requestAuthnSignatureMethod: http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 

For information on these settings, see the SAML attributes section. 

Update the SAML settings

Update the SAML settings for an identity provider in Code42 using the identity-provider-saml-settings/IdentityProviderSamlSettings_Update  API resource.

In the following example: 

  • Replace <AuthToken> with the authentication token you obtained in the Authentication section.
  • Replace <ServerURL>:<Port> with the URL and port of your authority server. For example, authority-server.example.com:4285
  • Replace <IdentityProviderID> with the ID you obtained as described in the Identity provider ID section.
  • Provide values for these parameters as described in the SAML attributes section:
    • authnContextComparison
    • authnContextClassRef
    • requestAuthnDigestMethod
    • requestAuthnSignatureMethod
Copied!
curl -vvv -X POST https://<ServerURL>:<Port>/api/v6/identity-provider-saml-settings/update \
-H "Authorization: v3_user_token <AuthToken>" \
-H 'Content-Type: application/json' \
-d '{"settings": {"uid": "<IdentityProviderID>", 
"authnContextClassRef": ["urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword"], 
"authnContextComparison": "MAXIMUM", 
"requestAuthnDigestMethod": "http://www.w3.org/2001/04/xmlenc#sha512", 
"requestAuthnSignatureMethod": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"}}'

Identity provider SAML settings API structure and syntax

Summary

  • Request URL 
    https://<ServerURL>:<port>/api/v6/identity-provider-saml-settings/ 
  • Identity provider SAML settings resource names: 
    • view: To view existing SAML settings
    • update: To update SAML settings
  • Authentication method: Include a token in the request header (see the Authentication section below)
  • Identity provider ID: Include the ID of the identity provider (see the Identity provider ID section below)
  • Complete API documentation
    The identity-provider-saml-settings resource is in the v6 API. To find API documentation for this resource, select v6 or higher from the upper-right corner of the Code42 API documentation page. For more information about the Code42 API documentation viewer, see Code42 API documentation viewers. For more information about Code42 API syntax, see Code42 API syntax and usage.

Authentication

This API resource requires an authentication token in the header of all requests. To obtain an authentication token, use your Code42 administrator credentials to submit a GET request to https://<server>:<port>/c42api/v3/auth/jwt?useBody=true 

For example:

Copied!
curl -X GET -u "username" -H "Accept: application/json" "https://authority-server.example.com:4285/c42api/v3/auth/jwt?useBody=true"

If your organization uses two-factor authentication for local users, you must also include a totp-auth header value containing the Time-based One-Time Password (TOTP) supplied by the Google Authenticator mobile app. The example below includes a TOTP value of 424242.

Copied!
curl -X GET -u "username" -H "totp-auth: 424242" "Accept: application/json" "https://authority-server.example.com:4285/c42api/v3/auth/jwt?useBody=true"

A successful request returns an authentication token. For example:

{
    "v3_user_token": "eyJjdHkiO_bxYJOOn28y...5HGtGHgJzHVCE8zfy1qRBf_rhchA"
}
Token considerations
  • Use this authentication token in your requests.
  • Authentication tokens expire after 30 minutes.
  • The authentication example above only applies to users who authenticate locally with Code42. Single sign-on (SSO) users must also complete SAML authentication with their SSO provider. If you need assistance with this process, contact your SSO provider.

Identity provider ID

The identity provider SAML settings API requires that you provide the unique ID of the identity provider. Run the SsoIdentityProvider API to obtain the IDs of all the available identity providers.

In the following example:

  • Replace <username> with the Code42 username. 
  • Replace <ServerURL>:<Port> with the URL and port of your authority server. For example, authority-server.example.com:4285
Copied!
curl -X GET -u "<username>" "https://<ServerURL>:<Port>/api/SsoIdentityProvider?active=true" \
-H "Accept: application/json"

A successful response returns the identity provider IDs (ssoIdentityProviderUid) and other information.

{"metadata":{"timestamp":"2020-09-02T12:20:57.913-05:00","params":{"active":"true"}},"data":[{"ssoIdentityProviderUid":"969941277100434242","displayName":"MyOrgSSO" ...

SAML attributes

Use the following optional parameters to update the SAML settings used by the Code42 identity provider:

The following code example uses these parameters:

Copied!
curl -vvv -X POST https://authority-server.example.com:4285/api/v6/identity-provider-saml-settings/update \
-H "Authorization: v3_user_token <AuthToken>" \
-H 'Content-Type: application/json' \
-d '{"settings": {"uid": "<AuthProviderID>", 
"authnContextClassRef": ["urn:oasis:names:tc:SAML:2.0:ac:classes:InternetProtocolPassword"], 
"authnContextComparison": "MAXIMUM", 
"requestAuthnDigestMethod": "http://www.w3.org/2001/04/xmlenc#sha512", 
"requestAuthnSignatureMethod": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha512"}}'

Parameters are entered in the format "<parameter>:<value>". All four SAML parameters listed below can optionally be omitted when calling this API. By omitting a parameter and value entirely, Code42 uses the default parameters and values when sending the AuthnRequest to the identity provider. In some cases, the parameter can be specified with a null or empty value. More information is detailed in each section below.

authnContextClassRef

This parameter sets the context class reference to authenticate users. This parameter is optional and can be omitted from the command call. If the parameter is included and its value is specified to be empty (as an array or a string in an array), the authnContextClassRef XML element is omitted entirely from the SAML AuthnRequest.

You can use any of the SAML 2.0 authentication context classes to authenticate users. The Authentication Context Class Reference values listed in the table below are the most commonly used in the SAML 2.0 specification. (Because some identity providers have created their own authentication classes which aren't listed in the SAML 2.0 specification, such as for multi-factor authentication, you can still specify any valid authentication class reference as long as it has a correctly formatted URN.)

The value supplied to the parameter should have one of the following prefixes:

  • urn:oasis:names:tc:SAML:2.0:ac:classes (SAML 2.0) or
  • urn:oasis:names:tc:SAML:1.2:ac:classes (SAML 1.2)

For more information about SAML 2.0 authentication context classes, see the SAML 2.0 specification.  

Valid values Description
InternetProtocol Provide an IP address.
InternetProtocolPassword Provide an IP address in addition to a username/password combination.
Kerberos Use a password to acquire a Kerberos ticket.
MobileOneFactorUnregistered Authenticate mobile devices without requiring explicit end-user interaction.
MobileTwoFactorUnregistered Authenticate mobile devices with two-factor based authentication.
MobileOneFactorContract Authenticate mobile devices through contract customer registration and single factor authentication.
MobileTwoFactorContract Authenticate mobile devices through contract customer registration and two-factor authentication.
Password (Default) Provide a password over an unprotected HTTP session.
PasswordProtectedTransport Provide a password over a protected HTTPS session.
PreviousSession Authenticate using a previously-used authentication context.
X509 Use a digital signature where the key was validated as part of an X.509 PKI.
PGP Use a digital signature where the key was validated as part of a PGP PKI.
SPKI Use a digital signature where the key was validated via an SPKI.
XMLDSig Use a digital signature according to the XML Digital Signature specification.
Smartcard Authenticate using a smartcard.
SmartcardPKI Authenticate using a smartcard with enclosed private key and a PIN.
SoftwarePKI Authenticate with an X.509 certificate stored in software.
Telephony Authenticate using a telephone number.
NomadTelephony Authenticate using a roaming telephone number such as a phone card.
PersonalTelephony Authenticate using a telephone number and a user suffix.
AuthenticatedTelephony Authenticate using a telephone number, a user suffix, and a password.
SecureRemotePassword Provide a Secure Remote Password.
TLSClient Provide a client certificate secured with the SSL/TLS protocol.
TimeSyncToken Provide a time synchronization token.
Unspecified Authenticate by using unspecified means. The server does not expect a particular authentication method. Instead the server will attempt to authenticate the user via its configured authn options. 

authnContextComparison

This parameter specifies the comparison method used to evaluate the requested context class (AuthnContextClassRef). This parameter is optional and can be omitted from the command call. When the parameter is specified, it must be populated with any of the Valid values listed in the table below.

For more information about the AuthnContextComparison method, see the SAML 2.0 specification.

Valid values Description
EXACT (Default) Must be the exact match of at least one of the authentication contexts specified.
MINIMUM Must be at least as strong (as deemed by the responder) as one of the authentication contexts specified.
MAXIMUM Must be as strong as possible (as deemed by the responder) without exceeding the strength of at least one of the authentication contexts specified.
BETTER Must be stronger (as deemed by the responder) than any one of the authentication contexts specified.
Not Specified Uses the default value EXACT.

requestAuthnDigestMethod

This digest algorithm performs a checksum of the contents of the SAML request to ensure it was not edited in transit. This parameter is optional and can be omitted from the command call. When the parameter is specified, it must be populated with any of the Valid values listed in the table below.

For more information about digest algorithms, see the W3 XML Security Algorithm Cross-Reference.

Valid values Description
http://www.w3.org/2000/09/xmldsig#sha1 SHA-1 digest algorithm
http://www.w3.org/2001/04/xmlenc#sha256 (Default) SHA-256 digest algorithm
http://www.w3.org/2001/04/xmldsig-more#sha384 SHA-384 digest algorithm
http://www.w3.org/2001/04/xmlenc#sha512 SHA-512 digest algorithm

requestAuthnSignatureMethod

This parameter is a cryptographic signature algorithm for the checksum of the contents of the SAML request. The signature algorithm should match the digest algorithm with a variety of pre-pended private key generation indicators. This parameter is optional and can be omitted from the command call. When the parameter is specified, it must be populated with any of the Valid values listed in the table below.

For more information about signature algorithms, see the W3 XML Security Algorithm Cross-Reference.

Valid values Description
http://www.w3.org/2000/09/xmldsig#rsa-sha1 RSA-SHA1 signature algorithm
http://www.w3.org/2001/04/xmldsig-more#rsa-sha256 (Default) RSA-SHA256 signature algorithm
http://www.w3.org/2001/04/xmldsig-more#rsa-sha384 RSA-SHA384 signature algorithm
http://www.w3.org/2001/04/xmldsig-more#rsa-sha512 RSA-SHA512 signature algorithm

Related topics 

  • Was this article helpful?