Single-Sign On FAQ

This article applies to All editions.

** 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 to 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 your Identity Provider (IdP) exactly. If any fields don't match — whether you're using Azure, Okta, or another system — you'll receive an error when signing in. Configuring SSO with SAML 2.0 requires technical expertise. Centercode strongly recommends working with your organization's IT team throughout the process, and Centercode Support is available for supplementary assistance.

Attributes Mismatch (SAML and OAuth)

If attributes don't match between Centercode and your IdP, users will see this error when signing in through the IdP:

"The login system failed to provide the following required information: Username, Email Address, First Name, Last Name."

Check your IdP settings and identify the correct attribute names. Examples of possible attributes (refer to your IdP for exact values):

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 values:

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 SSO configuration change, you must update your metadata in Centercode:

1. Go to Community logo > Community configuration > Integration center > Custom SSO.

2. Hover over the SSO configuration and click the Metadata icon.

User's Email or Username Has a Conflict (SAML and OAuth)

If the username or email provided by your IdP conflicts with an existing Centercode account, users may see:

"This community only allows one account per [username or email address]. You will need to sign in using the account already associated with this community."

Enabling the User can upgrade from this field checkbox allows an existing Centercode account to be associated with an IdP account. When enabled for email, users signing in through the IdP will have their existing Centercode account upgraded to an SSO account. When disabled, the incoming account is rejected due to the conflict.

If upgrade isn't enabled, the user must change their username in the IdP, or a Centercode admin must merge the two accounts.

After any SSO configuration change, update your metadata (see steps in the previous section).

Invalid ACS Signing Certificate Public Key (SAML)

This error may mean the ACS Signing Certificate Public Key is invalid. Check your IdP for the key being used and update the ACS Signing Certificate Public Key field in Centercode.

A common issue is invalid spaces or line breaks in the key. The key must be one continuous string of characters with no breaks.

After any SSO configuration change, update your metadata (see steps above).

If you're unsure of your ACS Signing Certificate Public Key, use a Chrome plugin to inspect what your IdP is sending to Centercode. Centercode recommends SAML Tracer or SAML Chrome Panel. Sign in through your IdP with the plugin open to see the certificate and attributes being sent.

Parameters Missing in the Identity Provider Login URL (OAuth)

A common OAuth configuration issue is missing parameters in the Identity Provider Login URL, such as state or code. Verify your IdP's login URL includes all required parameters.

Invalid Token API Post Body (OAuth)

A common Token API Post Body format to use is:

client_id=%ClientId%&client_secret=%ClientSecret%redirect_uri=%RedirectUrl%&code=%Code%&grant_type=authorization_code

Missing characters — such as a percentage symbol or ampersand — will produce this error: "Your sign-in attempt was not successful. We were unable to contact the sign-in system at this time. Please try again later."

Your company's IT department can provide your ACS Signing Certificate Public Key. To gather your Centercode metadata to share with your IT contact:

1. Go to Community logo > Community configuration > Integration center > Custom SSO.

2. Hover over the SSO configuration and click the Metadata icon.

3. Copy the full text and send it to your IT contact, who will use it to configure the IdP side of the SSO setup.

How Do I Test My SSO Configuration?

Use these URLs to test your configuration. Replace the bracketed values with your own:

SAML: https://[your site]/login/saml/2/metadata.aspx/metadata.xml?p=[your setup's name]
OAuth: https://[your site]/login/oauth/2/authorize?p=[your setup's name]

How Do I Have Both an SSO Login and a Local Login?

You can run any number of SSO options alongside local authentication simultaneously. This is common for organizations where employees sign in via SSO but participants use standard local accounts.

Local authentication is controlled via the Enable local authentication checkbox in User account settings. Individual SSO options are controlled in the User access section of each SSO configuration's Modify screen.

Which Attributes Should I Enable "Upgrade" For?

Enable upgrade for attributes that your users may need to update over time — typically email address. Consider what changes are realistic for your user base and what would cause account conflicts if updated without an upgrade path.

What If I Need to Adjust a Live SSO Configuration?

1. Sign in to your Centercode implementation.

2. Update the relevant values in your Identity Provider's settings.

3. Make the corresponding changes in your Centercode SSO configuration.

4. Go to Community logo > Community configuration > Integration center > Single sign-on.

5. Hover over your SSO configuration and click Metadata to sync the settings between the two systems.

6. In an incognito window or a different browser, verify that certificates match and sign in again to confirm.

Our IdP May Have Users with Duplicate Usernames. What Will Happen?

Centercode accounts can't have duplicate usernames. Your IdP must resolve duplicates before those users sign in through SSO, or they may encounter a username conflict error.

If you can't modify your IdP, configure your SSO to ignore the Username field so Centercode doesn't collect it initially. Users will then be prompted to choose a username when creating their account.

We Updated Our Custom Domain. Now Users Can't Sign In. What Should We Do?

Your IdP has security that restricts which service provider domains it trusts. When you update your Centercode domain (for example, from beta.centercode.com to beta.awesome.com), your IdP needs to update its references to the old URL. Have your IT team update your SSO settings to reference the new domain, including the correct subdomain.

Is There a Way to Create a Local Account to Update SSO Settings When Needed?

Yes. If you've replaced local sign-in with SSO only, Centercode recommends keeping both SSO and local authentication active to maintain a fallback option. See the "How do I have both an SSO login and a local login?" section above. If you need additional help with this use case, contact Centercode Customer Support.