SAML SSO FAQ

Single-Sign On Troubleshooting

** Configuring a new SSO in Centercode using SAML 2.0 will require a level of technical expertise. We strongly encourage you to maintain contact with the correct IT team in your organization; typically the same team you’d go for help with your company user account. Centercode Support will also be available for supplementary configuration assistance.

All Single Sign-On configuration fields must match exactly as they do from your Identity Provider (Azure, Okta, your company’s system, etc). If any fields do not correctly match the settings of your Identity Provider (often referred to as IDP), you’ll receive an error when attempting to login. The following are common possibilities as to why your SSO setup may fail:

  1. Attributes mismatch
  2. User’s email or username has a conflict
  3. Invalid ACS Signing Certificate Public Key
  4. Metadata not updated after SSO settings were changed

1. Attributes Mismatch

“The login system failed to provide the following required information:

  • Username
  • Email Address
  • First Name
  • Last Name

Please provide this information and try your login again”

If your Attributes are mismatching between Centercode and your IDP, you’ll see this error message when attempting to sign in through your IDP.

It’s recommended that you reference your IDP settings and identify the correct Attributes. Here are some examples of possible Attributes to be used, but please refer to your IDP the exact Attributes: 

  • UserName
  • Username
  • Email
  • Email Address
  • EmailAddress
  • emailaddress
  • FirstName
  • firstname
  • LastName
  • lastname

If you're using Azure AD, you may need to use "Claim names" rather than their "value"

  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
  • http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname

After any changes you’ve made to your SSO configuration, you must update your metadata within your Centercode Implementation: 

  1. Navigate into the User Authentication Management page
  2. Hover over the desired SSO configuration
  3. Click the Metadata icon

2. User’s email or username has a conflict

“This community only allows one account per <username or email address>. You will need to log in using the account that has already been associated with this community.”

If username or email is provided by your IDP and the provided username or email conflicts with an existing user account, the users may encounter this error when logging in. 

Enabling the “User can upgrade from this field” checkbox allows a username or email that already exists in your Centercode implementation to also be associated with an IdP account. When enabled for email address, users who login will have their any pre-existing Centercode account match the email address of a new account coming from your IdP. This results in the Centercode account upgrading to an SSO account. When disabled, the incoming account will be rejected due to conflict. 

If “User can upgrade from this field” is not enabled, you or the user must change their Username from your IdP. When logging in a new account will be created with a different username, which requires your Centercode Community administrator to merge the accounts together. 

After any changes you’ve made to your SSO configuration, you must update your metadata within your Centercode Implementation: 

  1. Navigate into the User Authentication Management page
  2. Hover over the desired SSO configuration
  3. Click the Metadata icon

3. Invalid ACS Signing Certificate Public Key

This message may indicate that your ACS Signing Certificate Public Key is invalid. You’ll want to check your IDP for the key being used and update your ACS Signing Certificate Public Key field within your Centercode implementation. 

A common issue is having invalid spaces or linebreaks throughout your ACS Signing Certificate Public Key. The key must be one solid string of characters.

After any changes you’ve made to your SSO configuration, you must update your metadata within your Centercode Implementation: 

  1. Navigate into the User Authentication Management page
  2. Hover over the desired SSO configuration
  3. Click the Metadata icon

Where do I get an ACS Signing Certificate Public Key?

Your company's IT department will be able to provide this.

Where can I find the metadata for my Centercode implementation?

Once that your Single Sign-On configuration has been created, you may access the metadata and present it to your IT contact. To gather the metadata information: 

  1. Navigate into the User Authentication Management page
  2. Hover over the desired SSO configuration
  3. Click the Metadata icon
  4. Copy the entirety of the text on this page and send it to your IT contact. 
    1. They’ll use the information contained within the metadata to configure the Identity Provider side of the SSO configuration. 

I don’t know my Attributes and my ACS Signing Certificate Public Key, what do I do?

If you’re unable to confirm your ACS Signing Certificate Public Key used by your Identity Provider or that you have confirmed all of your settings seem correct, utilize Chrome plugins to identify what your Identity Provider is sending to Centercode upon logging into your SAML configuration. This can be done only if your IDP Gateway and IDP Issuer fields are correct. 

We recommend these Chrome plugins:

Open the plugin and log into your identity provider that’s connected to your SAML configuration. The plugin will display the ACS Signing Certificate Public Key and Attributes that your identity provider is attempting to send. You may also want to ensure that your Identity Provider is using the correct Centercode URL (shown below).

How do I test my SSO configuration?

Once your SSO configuration is submitted, it is technically live and can be used for testing and production. The “Finalizing your SSO” step 4 of the SSO documentation is to make your SSO configuration visible on your login page.

When testing your SSO configuration  you can use the appropriate links to test your SSO setup. The text within brackets must be replaced appropriately. 

    • https://<your site>/login/saml/2/metadata.aspx/metadata.xml?p=<your setup’s name>
    • https://<your site>/login/oauth/2/metadata.aspx/metadata.xml?p=<your setup’s name>

How do I have both an SSO login and local login? 

This is fairly common for organizations with an internal account system for employees, but don't have the same system available for their testers. In this scenario, you can enforce employee logins through SSO and leave the standard local login functionality for your non-employee accounts.

Which Attributes should I enable upgrade for?

Consider what needs to be updated by your users. 

How do I set my SSO live? 

This is covered in the documentation in section 4, titled Finalizing Your SSO. 

Once the metadata is configured, the next step is to enable the SSO method for testing. The best way to do this is to enable the SSO without hiding your local login functions:

  1. Navigate into the User​ ​Authentication​ ​Management​ page
  2. Click the Centercode​ authentication method
  3. Under the Alternate Login section, select Local​ ​and​ ​Remote​ ​Logins​ from the dropdown list
  4. Click Submit​ ​to add an SSO link to your site’s Login page
  5. Log out of Centercode and click your new SSO Login link on the top-right of your login page

What if I need to make adjustments to my live SSO configuration?

  1. Log into your Centercode implementation
  2. Within your Identity Provider’s settings, update your Identity Provider’s values
  3. Within your Centercode implementation, make your desired changes to your SSO configuration
  4. Within your Centercode implementation, navigate to your User Authentication tool
  5. Hover over your saved SSO configuration and click Metadata 
    • This refreshes your metadata, syncing the settings of the 2 systems
  6. In Incognito or another browser: Verify that the certificates match and log in again

Our Identity Provider may potentially have users with duplicate usernames. What will happen?

Centercode accounts cannot have duplicate usernames. Your Identity Provider will need to handle duplicate usernames before they login through your SSO configuration, or they may encounter a username conflict.

If you're unable to make any changes to your Identity Provider, you may set your SSO configuration to ignore the Username and not have it collected initially by Centercode. This means your users will be prompted to fill in a username upon account creation.