Single Sign-On Integrations
      Back to home
      1. Help Center
      2. Enhanced Integrations & APIs
      3. Single Sign-On Integrations

      OAuth-based Single Sign-On for Centercode

      Set up custom User Authentication using via OAuth-based SSO

      ** Configuring a new SSO in Centercode using OAuth 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.

      1. Preparing for SSO Configuration

      Several of the fields in the configuration below will require collaboration with the technical contact responsible for SSO configurations or managing your Identity Provider system. Please review the fields below and seek assistance as necessary.When seeking to configure SSO for your Centercode site, there are several key steps starting with configuring your Identity Provider (IdP - the system that controls your user accounts) to allow Centercode as a Service Provider (SP) via OAuth 2.0. The actual steps to configuring your IdP depends on the provider you use. Review the information below when configuring your IdP and ensure the expected Parameters (values provided to Centercode from your account system) are accounted for.

      Basic Options

      • Name - The internal name for the Single Sign On being created/configured. This is also used as an identifier in the SSO configuration.
      • Client ID - The ID associated with the Centercode app defined within your IdP.
      • Client Secret - The secret associated with the Centercode app defined within your IdP.
      • Redirect URL - The Centercode URL a user is sent to after logging in to your IdP.
      • Identity Provider Login URL - The URL to the login page for your IdP.
      • Token API URL - The API endpoint used to retrieve an OAuth token. 
      • Token API Headers (Optional) - The HTTP headers that may be necessary to call the token API.
      • Token API Post Body - The HTTP post body sent with a token API request.
      • Profile API URL (Optional) - A secondary API endpoint to retrieve more user profile information. 
      • Profile API Headers (Optional) - The HTTP headers that may be necessary to call the Profile API.
      • Alternate Logout URL (Optional) - If a user should be logged out of their global account when logging out of Centercode, define the address that the user will be sent to. Use %ReturnToURL% to bring the user back to the Centercode landing page.
      • Alternate Profile Edit URL (Optional) - By design, user account settings under OAuth can’t be adjusted within Centercode because they’re provided by the IdP. However, this link would be presented to your users as a shortcut to your “update my account” page. Use %ReturnToURL% to link back to this site.
      • Alternate Login Label - This is the text shown to users on the Centercode landing page which links to your SSO login page. (screenshot example)

      Identity Provider Login URL

      When authenticating via OAuth, both the state and the code parameters must be included within Redirect URL following authentication. The state value will be the same value included in the IDP Login URL and the code value will be the Authorization Code generated by the IDP. These values are injected dynamically using tags below.

      While not always required, the scope and response_type query string parameters are commonly included in the IDP Login URL. These can be excluded if your IDP doesn’t require them.

      Once Centercode has received an Authorization Code (“code”), a POST request is made to the IDP Token API endpoint to exchange that Authorization Code for an Access Token. The necessary OAuth values are most often included in the POST body, but query string parameters or headers can also be used. 

      The following variables will be automatically replaced with the associated value when each request is made within the OAuth flow.

      If you're unsure on a Token API Post Body to start with, please use this example:

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

      Token API response Example:

      {

           "access_token":"MTQ0NjJkZmQ5OTM2NDE1ZTZjNGZmZjI3",

           "token_type":"bearer",

           "expires_in":3600,

           "refresh_token":"IwOGYzYTlmM2YxOTQ5MGE3YmNmMDFkNTVk",

           "scope":"create"

      }

      Profile API URL example:

      https://api.accounts.customer.com/v2/oauth?token=%Token%

      Profile API Headers example:

      Authorization: Bearer %Token%

      Profile Parameter Configuration

      The Centecode Profile Parameter Configuration is required by Centercode and provides a way to customize how fields are mapped from the Profile API response (from the IdP side) to a Centercode user’s account.

      If your Identity Provider isn’t able to send any of these parameters, the Centercode platform will ask the user for them upon initial entry or account creation. 

      Parameters:

      • Username (Must be unique) - The JSON property that maps to Username within Centercode. This is used as a public alias that identifies users in collaborative places (ex: feedback comments).
      • Email Address (Must be unique) - The JSON property that maps to Email Address in Centercode. Email Address is the most common binding value between two account systems.
      • First Name - The JSON property that maps to First Name in Centercode.
      • Last Name - The JSON property that maps to Last Name in Centercode.

      Parameter Options:

      • User can upgrade from this field - If enabled, when a preexisting Centercode account matches email address of an incoming SSO account, the existing Centercode account will be “upgraded” to the incoming SSO account (now bound to your IdP). If disabled, an incoming account may be rejected due to a conflict between the incoming and pre-existing Username or Email Address.

        If your Community is new and all new accounts in the system should coming through your SSO, you can safely disable this checkbox. If you’re updating the existing configuration and preexisting Centercode accounts are becoming SSO accounts, this option must be enabled.
      • Provider must supply this value - When enabled, the IdP system is required to provide this parameter. If enabled, but the parameter is not provided by the IdP, the SSO will throw an error and the user won’t be able to enter the Centercode platform using this authentication method. If one of these parameters is not available from the IdP, this option should be disabled so incoming users can supply the value themselves. If enabled, the value from the IdP will be captured and locked during authentication - users will not be able to change the value provided within Centercode. Instead, they’ll need to update their information on the IdP side.

      2.   Configuring Centercode

      To begin configuring Centercode for SSO, you’ll need to login to your Centercode portal as a Community Manager and navigate to User Authentication Management (Community Logo -> Community Administration -> All Community Tools -> User Authentication). From here:

      1. Click Add a New Authentication System 
      2. Select OAuth 2.0 from the Type drop down menu
      3. You’ll see the list of Basic Option fields appear. Complete the form as appropriate
      4. Select an opportunity in the EA Foundation Team section, new users that have not previously used Centercode will be onboarded and assigned team access through this opportunity.
      5. Click Submit to finish creation of your Single Sign On.

      3.   Update IdP Centercode App Configuration

      Now that your Single Sign On has been created and configured in Centercode, the Redirect URL may need to be added as an authorized redirect URL within your Centercode App configuration. This process is usually as simple as copying the generated Redirect URL within Centercode and pasting it into a configuration field associated with the Centercode App within your IdP. That said, the configuration options for your Identity Provider may vary.

      4.   Finalizing Your SSO

      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 the top-right corner of your site’s Login page
      5. Log out of Centercode and click your new SSO Login link on your login page

      If you run into any issues while configuring SSO or have any questions, let us know! We’d be happy to guide you through this process and address any questions you may have. 

      Adding SSO to an Existing Community

      When updating an existing Centercode Community to utilize a new SSO authentication method, you need to ensure that accounts present in both systems can be combined and Centercode account activity and history is not lost. To accomplish this goal, perform the following steps:

      • To bind accounts, you must determine (or establish) a unique identifier between the two systems - Email Address. Inform your users to ensure the email address they use in your IdP system matches the email address they’re using for Centercode before they log in through SSO for the first time. This can be done in either system as long as they match. Logins without matching information will create new accounts, leaving the Centercode-only account behind (requiring merging of the accounts, done manually).
      • When users log in through SSO, non-SSO user accounts will need to merge into the new SSO accounts. To do this, you’ll adjust the SSO configuration by selecting User Can Upgrade From This Field for the Email Address attribute. Centercode will use the Email Address attribute to match users’ accounts together, allowing them to use SSO to log into what was previously a local Centercode account.
      • If Username is not provided by the Identity Provider, users may find that their desired username conflicts with one already in the Centercode system. If Username is provided by the Identity Provider and the provided Username conflicts with a non-SSO account, users may encounter an error when logging in. This may require additional action on the IDP side (change the username within the IDP).
      • The Authorization Code grant type is the only OAuth grant type Centercode currently supports for SSO integration.