Skip to content
English - United Kingdom
  • There are no suggestions because the search field is empty.

How do I set up SCIM using the authorisation code flow?

Connect an identity provider that uses the OAuth 2.0 authorisation code flow, so it can provision Users and Groups into SpeakUp automatically.

The SpeakUp side of this setup is the same for any identity provider that uses the authorisation code flow. Okta is the common example. If your identity provider uses client credentials instead, for example Microsoft Entra ID, see how do I set up SCIM using the client credentials flow?

SCIM provisioning is one-way, from your identity provider to SpeakUp. Changes made directly in SpeakUp to provisioned Users or Groups can be overwritten by the next sync.

On this page: Before you start · Create the App Integration · Connect your identity provider · Authorise the connection · Verify · Common problems

Before you start

  • SCIM provisioning must be enabled for your organisation. Contact your Customer Success Manager if you are not sure by clicking 'Support' and 'Contact support'.
  • You need the Administrator role in SpeakUp.
  • You need permission to configure provisioning in your identity provider.
  • You need a SpeakUp account that exists in your environment and has administrator rights, to authorise the connection at the end.

For what SCIM does and does not sync, see what is SCIM provisioning and when should I use it?

Create the App Integration

  1. Click the Settings icon in the top right corner.
  2. Go to System on the menu, then Configuration, and click API.
  3. Click + Create app integration.
  4. Enter a name for the integration.
  5. Set the Authentication method to Authorisation Code Flow (for example, Okta).
  6. Under Users and Groups, set the access to Full access. Full access is required for your identity provider to create, update, and disable Users and manage Groups. With read only access, it can only retrieve them.
  7. Click Add.

The integration does not work yet. You first need to configure OAuth in your identity provider and save its redirect URL in SpeakUp, as described below.

Connect your identity provider

Open the integration you just created. The OAuth Provisioning Configuration section shows the values your identity provider needs.

Value Used for
Authorization URL Where your identity provider sends the administrator to sign in.
Token URL Where your identity provider exchanges the authorisation code for a token.
Client ID Identifies the integration to SpeakUp.
Client Secret Authenticates the integration. Copy it exactly.
Scope The access the integration requests.

Then, in your identity provider:

  1. Set up a SCIM provisioning connection with OAuth 2 authentication, using the values above.
  2. For the SCIM base URL, use the address shown under API Endpoint Configuration on the same page.
  3. Copy the redirect URL, also called a callback URL, that your identity provider generates for the connection.

Back in SpeakUp:

  1. Paste the redirect URL into the Callback URL field under Redirect URL.
  2. Click Save.

This exchange of URLs is what distinguishes this flow from client credentials. Your identity provider needs SpeakUp's OAuth URLs, and SpeakUp needs your identity provider's callback URL. Both halves must be in place before the connection can be authorised.

Authorise the connection

  1. Authorise the connection from your identity provider.
  2. When the SpeakUp sign-in window opens, sign in with a SpeakUp account that exists in your environment and has administrator rights.

Your identity provider can now provision Users and Groups into SpeakUp.

Verify

  1. Assign a small test group of Users in your identity provider, rather than your whole organisation.
  2. In SpeakUp, go to the Users section and confirm they appear.
  3. Check that attributes such as email, name, and department match.

Newly created Users automatically receive a SpeakUp invitation email.

Then change a User's attribute in your identity provider and confirm it reaches SpeakUp on the next sync. Once that works, assign the rest of your Users and Groups.

Never change a User's email address or username from your identity provider's app assignment. These must be changed in the identity provider's own user directory. Changing them through the SCIM connection disables the User in SpeakUp.

 

Common problems

What you see What it means What to do
The connection cannot be authorised The callback URL has not been saved in SpeakUp, or does not match the one your identity provider generated. Recopy the redirect URL from your identity provider into the Callback URL field and save.
Sign-in fails when authorising The account used does not exist in this SpeakUp environment, or lacks administrator rights. Sign in with a SpeakUp administrator account from the environment you are connecting.
Provisioning is rejected The integration was created with read only access for Users and Groups. Full access is required. Check the access level on the integration detail page.
The connection test fails in your identity provider Most often the SCIM base URL or the Client Secret. Use the address shown under API Endpoint Configuration, and recopy the Client Secret with no extra spaces.
A User is unexpectedly disabled in SpeakUp Their email address or username was changed through the app assignment. Change these in your identity provider's user directory, never through the SCIM connection.

Next steps