Skip to main content

Configure single sign-on for Zuora

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

Zuora single sign-on feature is only available in Zuora Enterprise and Zuora Nine editions. See Zuora Editions for more information.

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 endpoints where the Zuora application receives the SAML assertion. The value to enter depends on the Zuora environment that you are enabling SSO in.
    • US Cloud 1 Production - https://na.zuora.com/apps/saml/SSO/alias/defaultAlias
    • US Cloud 1 API Sandbox - https://sandbox.na.zuora.com/apps/saml/SSO/alias/defaultAlias
    • US Cloud 2 Production - https://www.zuora.com/apps/saml/SSO/alias/defaultAlias
    • US Cloud 2 API Sandbox - https://apisandbox.zuora.com/apps/saml/SSO/alias/defaultAlias
    • US Performance Test - https://pt1.zuora.com/apps/saml/SSO/alias/defaultAlias
    • US Central Sandbox - https://test.zuora.com/apps/saml/SSO/alias/defaultAlias
    • EU Cloud Production - https://eu.zuora.com/apps/saml/SSO/alias/defaultAlias
    • EU Cloud API Sandbox - https://sandbox.eu.zuora.com/apps/saml/SSO/alias/defaultAlias
    • EU Central Sandbox - https://test.eu.zuora.com/apps/saml/SSO/alias/defaultAlias
  • Audience URI: The Entity ID of this Zuora application. The value to enter depends on the Zuora environment that you are enabling SSO in.
    • US Cloud 1 Production - na.zuora.com or https://na.zuora.com
    • US Cloud 1 API Sandbox - sandbox.na.zuora.com or https://sandbox.na.zuora.com
    • US Cloud 2 Production - www.zuora.com or https://www.zuora.com
    • US Cloud 2 Sandbox - apisandbox.zuora.com or https://apisandbox.zuora.com
    • US Performance Test - pt1.zuora.com or https://pt1.zuora.com
    • US Central Sandbox - test.zuora.com or https://test.zuora.com
    • EU Cloud Production - eu.zuora.com or https://eu.zuora.com
    • EU Cloud API Sandbox - sandbox.eu.zuora.com or https://sandbox.eu.zuora.com
    • EU Central Sandbox - test.eu.zuora.com or https://test.eu.zuora.com
  • Name ID format: configure this setting to Email Address format.
  • Default username: configure this setting to Email.
  • Default Relay State - Leave this setting blank.

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 tenant can be associated with only one identity provider, and one identity provider can be associated with multiple tenants by using a different application for each tenant.
  • 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 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 the 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
  • Endpoint 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 log in to Zuora via SSO.

SSO provisioning process

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

  1. Submit a request at Zuora Global Support to provide your Zuora contact with the provider metadata and logout URL. 

    The logout URL 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/IdpInitiatedSignon.aspx.

  2. Download Zuora service provider metadata from:
    • US Cloud 1 Production: https://na.zuora.com/apps/saml/metadata
    • US Cloud 1 API Sandbox: https://sandbox.na.zuora.com/apps/saml/metadata
    • US Cloud 2 Production: https://www.zuora.com/apps/saml/metadata
    • US Cloud 2 API Sandbox:  https://apisandbox.zuora.com/apps/saml/metadata
    • Performance Test:  https://pt1.zuora.com/apps/saml/metadata
    • EU Production: https://eu.zuora.com/apps/saml/metadata
    • EU Sandbox:  https://sandbox.eu.zuora.com/apps/saml/metadata
    • Central Sandbox US:  https://test.zuora.com/apps/saml/metadata
    • Central Sandbox EU:  https://test.eu.zuora.com/apps/saml/metadata
  3. You add Zuora as a service provider to your identity provider, using the metadata that you downloaded from Zuora.
  4. You retrieve your identity provider metadata and send it to your Zuora contact. The identify provider federation metadata must be fully compliant with the Metadata for the OASIS Security Assertion Markup Language (SAML) V2.0 specification.  
  5. Your Zuora contact uploads your identity provider metadata to the Zuora application environment.
  6. Your Zuora contact notifies you of a successful SSO tenant enablement.
  7. You configure your Zuora users to use SSO. For instructions, see the section below.

Configure Zuora users for single sign-on

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 Manage Users.

To enable SSO for a Zuora user, complete the following steps:

  1. Log into the Zuora application as a tenant administrator, and navigate to Settings > Administration Settings > Manage Users.
  2. In the user list, click the user for whom you want to enable SSO. The user details page opens.
  3. In the Basic Information section, select the SSO SAML Enabled field.

  4. In the Federated ID field, enter the unique SSO federated ID of this user. The federated ID must be in an email format, for example, username@domain.com.

  5. 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 SSO needs to be disabled for this user, the tenant administrator 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 is enabled, the user needs to browse to the Zuora link on their identity provider login page to re-establish a Zuora session.

Disable SSO for Zuora User

To disable a user from signing on to Zuora via SSO, complete the following steps:

  1. Log in to the Zuora application as a tenant administrator, and navigate to Settings > Administration Settings > Manage Users.
  2. In the user list, click the user for whom you want to disable SSO. The user details page opens.
  3. In the 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 the 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 that 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 a 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 log in 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 into 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 to 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 an HTTP POST request directed to the service provider and putting the assertion into the POST payload.