Knowledge Center

Knowledge Center > Admin > Administrator Settings > Configure Single Sign-On for Zuora

Configure Single Sign-On for Zuora

This article describes how to configure your organization's security management components to enable single sign-on to Zuora. It also includes error messages and troubleshooting tips to help you and your users avoid common roadblocks.

About Zuora Single Sign-On

This feature is in Controlled ReleaseSubmit a request at Zuora Global Support to get this feature enabled for your tenant.

A single sign-on (SSO) infrastructure enables enterprise users to sign in once and have access to all authorized applications and resources. Zuora supports the single sign-on infrastructure using federated authentication via Security Assertion Markup Language (SAML) 2.0. SAML provides a secure, XML-based solution for exchanging user security information between an identity provider and service providers. The federated authentication process in Zuora involves the following entities:

  • Identity Provider: The authority system that provides the user information. Zuora system trusts the identity provider's user information and uses the data to provide access to the application.
  • Service Provider: Zuora application
  • User: Zuora application user

See Glossary for frequently used terms in SSO.

Requirements

Zuora SSO feature is fully tested and certified with the following identity providers:

  • Microsoft Windows Active Directory Federation Services (AD FS) 2.0 with HTTPS
  • Okta

In addition to the above identity providers, other identity providers that use the SAML 2.0 will work with Zuora SSO.

In your identity provider, you must configure the following settings to work with Zuora SSO:

  • Single sign-on URL: The endpoint(s) where the Zuora application receives the SAML assertion. 
    • If you are enabling SSO in the Zuora Production environment, use: https://www.zuora.com/apps/saml/SSO/...s/defaultAlias​
    • If you are enabling SSO in the Zuora API Sandbox environment, enter: https://apisandbox.zuora.com/apps/saml/SSO/alias/defaultAlias
  • Audience URI: The Entity ID of this Zuora application.
    • If you are enabling SSO in the Zuora Production environment, use: www.zuora.com or https://www.zuora.com
    • If you are enabling SSO in the Zuora API Sandbox environment, use: apisandbox.zuora.com or https://apisandbox.zuora.com
  • Name ID format: Use the Email Address format.
  • Default username: Use Email.

This version of the Zuora SSO feature requires the following:

  • The Artifact and HTTP-POST binding methods are used to validate SAML tokens. The Redirect binding method is not supported.
  • Federated IDs must be unique across all identity providers federated with Zuora
  • One identity provider can be associated with only one tenant, and one tenant can be associated with only one identity provider.
  • Zuora only supports the requests initiated by identity providers. SSO-enabled users need to log in from the identity provider's login page to access the Zuora application. Service provider-initiated login is not supported.

The following requirements apply to Zuora SSO users:

  • A Zuora user must have one unique federated ID assigned in order to use SSO. 
  • A user can log in to Zuora either in the SSO mode or in the local login mode. A user cannot be configured to use both modes. 
  • SSO is not supported for API users. You can single sign on to Zuora only through UI.

SAML Federation Metadata

SAML federation metadata describes an identity provider or a service provider. The metadata needs to be exchanged between two parties to establish a SAML federation. To enable Zuora SSO, a tenant and Zuora exchange metadata during the tenant SSO provisioning process. SAML metadata typically includes:

  • Entity identifier
  • Public keys used to check SAML message signatures
  • End point URLs
  • Supported bindings and profiles

Required Certificates

The following certificates are required for configuration and operation of Zuora SSO:

Identity provider’s SAML certificate

This certificate is used to sign validation requests sent from Zuora to an identity provider. It must be a 2048 bit certificate. We strongly recommend that this certificate is long-lived and self-signed.

Zuora service provider's SAML certificate

The private key of this certificate is used to validate the identity provider response signatures. It is a long-lived, self-signed, 2048 bit certificate.

Identity provider HTTPS certificate

This certificate is used to make HTTPS connections. It must be signed by a respected CA that is included in Java trusted CA list. Self-signed certificates are not supported in Zuora.

IMPORTANT: If your identity provider certificate expires or changes, you must re-generate the metadata file with the new or updated certificate and submit the new metadata file to Zuora. Wait for a notification from Zuora before allowing your users to login to Zuora via SSO.

SSO Provisioning Process

The provisioning process to enable single sign-on for your Zuora tenant is as follows:

  1. As a selected beta customer, you submit a support ticket to Zuora.
  2. You provide your Zuora contact the following:

    This is the URL to which your users are re-directed upon logging out of the Zuora application. The logout URL must conform to the format: scheme://domain:port/path?query_string#fragment_id.

    If you use AD FS as your identity provider, the logout URL is typically the AD FS login page at https://adfs_domain_name/adfs/ls/Idp...tedSignon.aspx.

Add Zuora Service Provider to Identity Provider

If you are using AD FS as your identity provider, see Adding Zuora Service Provider to AD FS for the steps to add Zuora as a trusted relying party.

If you are using Okta as your identity provider, see Adding Zuora Service Provider to Okta for the steps to add Zuora as a SAML SSO application.

Obtain Identity Provider Federation Metadata

The identify provider federation metadata must be fully compliant to the Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 specification

See Obtaining SAML Federation Metadata from AD FS about how to locate and retrieve identify provider metadata from AD FS.

See Obtaining SAML Federation Metadata from Okta about how to locate and retrieve identify provider metadata from Okta.

Configure Zuora Users for Single Sign-On

<h3">Enable SSO for a Zuora User

Before you enable SSO for a user, that user must have a user account in Zuora. If this is a new user, first, create this user in Zuora as described in Managing Users.

To enable SSO for a Zuora user:

  • Log into the Zuora application as a tenant admin, and browse to Settings > Administration Settings > Manage Users.
  • In the user list, click the user for whom you want enable SSO.
  • In the user's Basic Information section, select the SSO SAML Enabled field. EnableSSO.png
  • In the Federated ID field, enter the unique SSO federated ID of this user. Federated IDs must be in an email format, i.e., username@domain.com.
  • Click Save.

Activation Email

New Zuora users for whom SSO is enabled do not receive the activation email from Zuora. The user is automatically activated upon the first successful login to Zuora.

If, at some point, SSO needs to be disabled for this user, the tenant admin needs to use the Resend Activation Email feature to convert this user to a local Zuora user.

Zuora Session Time Out

When a user session times out in Zuora, the user is redirected to the Zuora login page. If SSO-enabled, the user needs to browse to the Zuora link on their identity provider login page in order to re-establish a Zuora session.

Disable SSO for Zuora User

To disable a user from signing on to Zuora via SSO:

  1. Log into Zuora application as a tenant admin, and browse to Settings > Administration Settings > Manage Users.
  2. In the user list, click the user for whom you want to disable SSO.
  3. In the user's Basic Information section, clear the SSO SAML Enabled field.
  4. Click Save.

Common Issues and Troubleshooting

The SAML assertion process in SSO can fail for various reasons, such as:

  • Network timeout
  • Identity provider service down
  • Incorrect identity provider configuration
  • Internal errors in identity provider

The following table lists a few of the potential error conditions users can encounter while logging in to Zuora via SSO.

Zuora Error Message Cause Solution
Federated ID provided by SAML assertion doesn't match our records. Federated ID of the user who's trying to login via SSO is not registered in Zuora. Correctly enter the federated ID of this user in Zuora as described in
Enable SSO for a Zuora User.
Incoming SAML message is invalid: Validation of protocol message signature failed.

Okta metadata has not been uploaded by Zuora.

Contact Zuora and check if the correct metadata is being uploaded on the Zuora side.

An invalid Name ID or Default username setting was specified in the Okta SAML settings.

Notify your Okta admin to check and update the Okta SAML settings as specified in Configure Okta for SSO SAML.
HTTP Status 401
Authentication Failed
The response issue time is either too old or in the future.

Set the clock to the atomic clock.

You must use Single Sign-On to log in to Zuora

An SSO-enabled user tries to log directly into Zuora application without going through the identity provider. The user must log in from the identity provider log-in page.

Your user account is not enabled to use Single Sign-On.

A user who is not SSO-enabled in the Zuora application tries to log into Zuora from the identity provider login page. Enable SSO for this user in the Zuora application.

Your Zuora tenant is not enabled to use Single Sign-On. 

In Zuora, the tenant is not provisioned to use SSO. Contact Zuora to enable SSO for this tenant.

SAML error: User is inactive.

The user has been de-activated in the Zuora application. N/A

Original password is not correct. Please reapply or email to support@zuora.com.

An SSO-enabled user tried to change the password in the Zuora application.

SSO-enabled users should not use the Change Password page in the Zuora application to change their password.

If a user wants to use the Zuora local login, the user should contact the tenant admin.

Attempted to log into the wrong tenant.

This error message only applies when your identity provider is Okta.

The federated ID was used in this SAML requests was mapped to the different Zuora tenant.

Check and use the federated ID associated with the Zuora tenant and the Okta identity provider. 

SAML error: Your SAML IdP doesn't match our records. Please contact the administrator at your company for help.

Changes in your identity provider settings invalidated the identify provider's metadata in Zuora.

Contact Zuora and check if the correct metadata is uploaded in Zuora. 

If necessary, re-submit the correct metadata file to Zuora and wait for a notification before allowing your users to login via SSO.

SAML certificates or metadata mismatch between your identity provider and Zuora.
Your identity provider metadata is missing. This can be caused by a number missteps or internal errors.

Glossary

Identity Provider

A service which is capable of authenticating a user, generating and assigning SSO SAML token to a user session, and verifying an assigned SSO token. An identity provider can be either installed on the Zuora tenant side, or it could be a cloud based service. An example of customer installed identity provider is Microsoft AD FS, and an example of cloud based identity provider is Okta.

Service Provider

A service that is capable of delegating user authentication to an identity provider via the protocols defined by the SAML specification. The Zuora application is a service provider.

identity Provider-Initiated

A workflow that requires users to login to an identity provider first. After a user successfully logs in to an identity provider, a SAML token is presented to the service provider by the browser usually either in the URL or HTTP POST body.

Service Provider-Initiated

A workflow that allows users to access the service provider without first logging in to the identity provider. The service provider must be capable of deciding which identity provider the incoming user needs to be redirected to log in.

SAML Federation Metadata

An XML document that describes the configuration of a service provider or an identity provider. It is exchanged between two parties to build a SAML federation.

SAML Artifact Binding

A method of transmitting SAML messages via references in HTTP messages. When using this Binding, the identity provider sends the user back to the service provider with a reference, referred as an artifact. The service provider then goes back directly to the identity provider and asks for the assertion matching the reference.

SAML POST Binding

A method of transmitting SAML messages via HTTP POST actions. When using this Binding, the identity provider sends the user back to the service provider by supplying a HTTP POST request directed to the service provider and putting the assertion into the POST payload. 

Last modified
22:55, 5 Jan 2017

Tags

Classifications

(not set)