Integrations - Understanding Single Sign-On Errors

Introduction

This article explains the most common Single Sign-On errors faced and the reasons behind them. Please note that the errors faced could be dependent on the program, what registration types they use and their single sign-on configuration.

SAML Assertion signature is invalid. The certificate on record does not match!

This is by far the most common type of error that you may face when a single sign-on connection is broken. When a connection is setup between two systems, they first exchange whats known as a certificate. The certificate is issued by the system providing the identity of the member (identity provider) and is used so the other party (service provider) can verify the authenticity of these requests.

This error occurs when the certificate used when setting up the connection has changed or is no longer valid (they expire). The way to resolve the issue would be to obtain the new certificate from the identity provider and update it on Reward Manager or advise the client to do so.

This type of an error is critical as it usually means no members can login to the platform.

Invalid response parameter. Expected response parameter: SAMLResponse

When a SAML Token is sent from the identity provider to us, we expect it to be sent in a certain way. It needs to be sent as a POST request and in a parameter called SAMLResponse (this can be edited on the setup page). This error means the parameter we expect it to be is different to what the identity provider is sending us.

It can also mean the SAML Link on the identity providers side is not setup properly.

Could not find a user based on ID:1234 in the SAML Token. Cannot allow the user to register as JIT is disabled.

When a SAML token is sent to us, we locate the user based on a pre-defined field inside the SAML token. These are known as Attributes. If we find a matching member with the details on the SAML Token we log the user into their account. If we could not match the user, we allow them to create an account. However, we only do that if Just-In-Time (JIT) registrations are turned on in the setup. 

This error means we could not find a registered account with the identifier in the SAML token and we also cannot allow the member to go ahead and create a new account as JIT registrations are turned off on the program. To resolve this, we would need the member to have an account or their details to be uploaded before hand. i.e. through a file upload.

Could not find a user based on ID:1234 and cannot allow the user to register via JIT. Date of Birth field is missing in the SAML token.

This error is slightly different to the one above. In this case JIT registrations are turned on in the setup. However, it looks like its a self-registration program where we need two identifiers to register a member (Payroll List + Date of Birth, Payroll List + Last Name). According to the error message, we cannot allow the member to go ahead and create an account as one of the fields required to register an account on this program is missing (Date of birth field is missing).

An empty identifier is passed.

The identifier passed in the SAML token is empty and therefore we cannot match an account on our end.