Self Service SSO Troubleshooting Guide
Introduction
During the release of the Self-Service for SAML connections we have identified a series of issues that have arisen with some customers, we collect these for future reference in this section together with the resolution.
The ticket to create my connection is expired / has been accessed too many times
Keep in mind that the ticket usually travels quite a bit before being handled to the team responsible for setting up the connection, just make sure to make emphasis on this:
At any point, if needed a new ticket can be issued for the connection creation, in case the connection have been already created a new ticket for editing it can be provided as well.
[!IMPORTANT]
Make sure that no more than one ticket is active at once, create or edit ones, since this might lead to undesired results.
I’m landing on statista in an error page after successfully authenticating with my IdP
In most cases the issue here is that the customer is not providing a federated_id attribute to be send on the SAMLResponse. This can be spotted in the auth0 logs:
The solution is to ask the customer to release the custom federated_id on their application configuration containing a unique identifier for the user on their internal systems.
I get an error '"options.issuer" is missing'
Some clients see an error '"options.issuer" is missing' while they fill out the fields in the ticket wizard, after they click on "Create Connection".
Most probably they entered a wrong URL in the field "OpenID Provider Configuration Endpoint".
The URL needs to end with /.well-known/openid-configuration.
Good:
https://login.microsoftonline.com/ad8e5212-e255-4e18-8a6d-0f812c781ecb/.well-known/openid-configuration
Bad:
https://login.microsoftonline.com/ad8e5212-e255-4e18-8a6d-0f812c781ecb
https://login.microsoftonline.com/ad8e5212-e255-4e18-8a6d-0f812c781ecb/.well-known
We see an error "rsa routines::oaep decoding error"
The error means the customer’s SSO is trying to send us an encrypted login message that Auth0 cannot decrypt because the keys no longer match.
They can:
- Re‑download the current SAML/SSO metadata or certificate from the Auth0 connection for this application.
- From here: https://statista.eu.auth0.com/samlp/metadata?connection=example-university
- Replace the "example-university" with the real connection name from Auth0
- In their IdP (Azure AD, Okta, ADFS, Keycloak, etc.), update the SSO configuration to use this newly downloaded Auth0 certificate for encrypting SAML assertions.
- If they recently rotated keys or changed anything on their side, make sure they removed old certificates and are only using the one that matches what is currently in Auth0.
- If they want a quick diagnostic, they can temporarily turn off “assertion encryption” in their IdP for this connection:
- If SSO then works, it confirms the issue is purely with the encryption certificate/key mismatch.
- After confirming, they should turn encryption back on using the correct Auth0 certificate.
We see a "Invalid thumbprint" error
Links
Auth0 documentation on this error: Auth0 Support Center
How clients can obtain metadata/certificates from the IDP: Configure Auth0 SAML Service Provider
The Error
Clients report that they get an error that states "Unspecified error".
If you look at the Auth0 logs and you see the "Invalid thumbprint" error, that means the client uploaded a different certificate while doing the self service link, than the one they have in their IDP.
How the error looks like:
Error resolution
- Send the client a new ticket link to edit the connection, and ask them to upload the correct certificate
- If you wish to do it on your own, ask the client to provide the certificate in .cem or .pem format
- Go to Auth0 and find the connection name
- Under "Settings", delete the existing X509 certificate and upload a new one
- Click "Save" on the bottom part of the page
- Ask the client to login and monitor the logs
If the issue persists, there is a high possibility that the client is sending us the wrong certificate. Ask them to consult their IT department, and try again.
I’m not allowed / cannot set custom attributes on the application
As of writing this, there's only one instance of customers experiencing this issue.
We have a set of customers who don’t directly own their IdPs and there are restrictions about providing custom user attributes which we require to set up the connection. For this specific cases we need to rely on the mapping functionality on Auth0, in order to do this, once the connection is created, navigate to the Mappings section of the affected collection:
The following snippet shows the default mappings that need to be set to address this issue. Please make note, that for academia customer, only the federated_id attribute is required, for enterprise customers the other three attributes are required. In any case, is up to the customer to decide which attributes they release.
{
"federated_id": [
"federated_id",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress",
"name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
"given_name": [
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname",
"http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
],
"family_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
}
[!NOTE]
Connections created through self service currently don't include this mapping as default. This should be the default template for all SAML connections, an idea on how to cover this, would be to include the mapping once connections created with self service are reflected on the tenant's terraform code.
I get a non supported REDIRECT method upon starting the authentication flow.
We have identified this issue with customers using the CAS IdP, this may apply to other IdPs. The root cause can be caused by a combination of factors and the way to diagnose and fix it involves:
Check that the Sign In URL is correctly set for the connection
In Auth0 the connection should correctly reflect the desired communication method:
And that this is also reflected on the Protocol Binding select list:
Check the connection configuration on the customer IdP
As an example we have a single basic connection configuration for the CAS IdP, that has the minimal requirements to work:
{
"@class": "org.apereo.cas.support.saml.services.SamlRegisteredService",
"serviceId": "urn:auth0:statista:some_connection",
"name": "Statista",
"id": 000000000,
"attributeReleasePolicy": {
"@class": "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
"allowedAttributes": {
"@class": "java.util.TreeMap",
"unique_internal_field": ["java.util.ArrayList", ["federated_id"]]
}
},
"metadataLocation": "/path/to/metadata/statista.xml"
}
and a more complicated configuration that caused issues:
{
"@class": "org.apereo.cas.support.saml.services.SamlRegisteredService",
"serviceId": "urn:login.statista.com",
"name": "Statista",
"id": 000000000,
"description": "",
"evaluationOrder": 33,
"usernameAttributeProvider": {
"@class": "org.apereo.cas.services.PrincipalAttributeRegisteredServiceUsernameProvider",
"canonicalizationMode": "LOWER",
"usernameAttribute": "mail"
},
"environments": null,
"attributeReleasePolicy": {
"@class": "org.apereo.cas.services.ReturnMappedAttributeReleasePolicy",
"allowedAttributes": {
"@class": "java.util.TreeMap",
"givenname": ["java.util.ArrayList", ["firstname"]],
"unique_internal_id": ["java.util.ArrayList", ["federated_id"]],
"sn": ["java.util.ArrayList", ["lastname"]]
}
},
"accessStrategy": {
"@class": "org.apereo.cas.services.DefaultRegisteredServiceAccessStrategy",
"requiredAttributes": {
"@class": "java.util.LinkedHashMap",
"memberof": ["java.util.HashSet", ["role_a", "another_role"]]
}
},
"singleSignOnParticipationPolicy": {
"@class": "org.apereo.cas.services.ChainingRegisteredServiceSingleSignOnParticipationPolicy"
},
"metadataLocation": "/path/to/metadata/statista.xml",
"requiredNameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
"signAssertions": "TRUE",
"signingCredentialType": "X509"
}
Note that in the previous example the serviceId seems to contain an invalid value when compared with the working example.
Another case that might cause problems is the assertion signature is not uploaded and configured on the IdP.
I need to enable IdP initiated login flow
In some exceptional cases like this one, the client will require to enable IdP initiated flow on their connection.
-
Ask the client to update their application configuration on their IdP to make
RelayStateto be empty (this varies from IdP to IdP so please check the documentation for each individual case). -
On the Auth0 dashboard navigate to the client's connection page and to to the
IdP-Initiated SSOtab.- Change the default
Reject RequeststoAccept Requests. - Select the default application
statista. - Select the response protocol
OpenID Connect. - Add the following to the query string:
redirect_uri=https://www.statista.com/sso/callback- This indicates Auth0 that upon session validation return to the callback method onremix-sso.
- Change the default
Your configuration should look like this:
⚠️ WARNING
Make sure to hit the
Save Changesbutton.
I get a "You may have pressed the back button..." error for a SAML connection
This solution does NOT ensure that the problem will be solved but in most cases it has worked. Sometimes, this error is related to a wrong Sign In URL configured in the connection or a wrong Protocol Binding.
Example of wrong configuration:
In this case, the solution is to change the Protocol Binding to
HTTP-POSTsince theSign In URLcontainsPOSTin its path.In case the Protocol Binding cannot be changed, the customer must provide the correct
Sign In URLfor the selected protocol.