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.
This feature is in Controlled Release. Submit 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:
See Glossary for frequently used terms in SSO.
Zuora SSO feature is fully tested and certified with the following identity providers:
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:
This version of the Zuora SSO feature requires the following:
The following requirements apply to Zuora SSO users:
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:
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.
The provisioning process to enable single sign-on for your Zuora tenant is as follows:
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:
If you use AD FS as your identity provider, the logout URL is typically the AD FS login page at
Download the Zuora service provider metadata from:
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.
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.
<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:
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.
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.
To disable a user from signing on to Zuora via SSO:
The SAML assertion process in SSO can fail for various reasons, such as:
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 |
|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 firstname.lastname@example.org.
|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.|
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.
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.
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.
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.