Configure SCIM Provisioning with Okta

This guide will walk you through how to set up SCIM provisioning with Oktopost using Okta as your identity provider.

Requirements

To set up the automated provisioning, you must have admin access to Oktopost and to the Oktopost <> Okta application settings. 

You will want to decide if you want to set up provisioning for the admin application or for the advocacy board, as the setup is different for each from the beginning. To set up the application for SCIM provisioning with the advocacy board, click here.

Features

The following provisioning actions are supported:

• Create Users

  Creates a user in Oktopost when assigning the app to a user in Okta.

• Update User Attributes

  Okta updates the users' attributes in Oktopost when the app is assigned. Future attribute changes made to the Okta user profile will automatically overwrite the corresponding attribute value in Oktopost.

• Deactivate Users

  Deactivates a user's Oktopost account when it is unassigned in Okta or their Okta account is deactivated. Accounts can be reactivated if the app is reassigned to a user in Okta.

Configuration Steps

Configuring the Okta App

1. Go to your existing SAML application that is used for Oktopost.
2. In the Sign On tab, select "Email" for the "Application username format" 
3. Navigate to the Provisioning tab.
4.  Click Configure API Integration, then check Enable API integration.
5. Click Authenticate with Oktopost and follow the authentication steps.
6.  Once provisioning is activated, turn on the required features in the To App menu item and save your changes:
   1. Create users.
   2. Update User Attributes.
   3. Deactivate Users.

Provisioning Okta users to Oktopost

The initial step to start provisioning in Okta is assigning users to the SAML application. If you just created a SAML application to set up SSO and SCIM, you can assign users, and they will be provisioned automatically.

If you already have a SAML application with assigned users, they won't be provisioned once the provision is enabled. You have two options in Okta: 

• You can un-assign and assign users again, or
• You can contact Okta support and ask to enable a feature called "Provision out of sync users," which would add a "Provision now" button next to each user that is not provisioned after provisioning is enabled.

Provisioning to Board

If you would like to set up SCIM provisioning for board advocates, you will need to create a custom Okta app for Oktopost instead of using the pre-built one. 

To create a custom app, please follow these steps. 

1. Create a new app integration with sign in method: SAML 2.0 and a custom name (may be: Oktopost Social Advocacy)
2. In the Configure SAML section, use the following details:
   1. Single sign-on URL: https://app.oktopost.com/auth/acs (OR eu-app.oktopost.com/auth/acs if you are on the European server.)
   2. Audience URI (SP Entity ID): urn:oktopost:sp
   3. Default Relay State: null
3. Ensure that you select ‘I am an Okta customer creating a internal app’
4. Move to the General section and enable Provisioning: SCIM.
5. In the Provisioning tab, edit the SCIM Connection settings to include
   1. SCIM connector base URL: https://board.oktopost.com/scim/v2  (OR https://eu-board.oktopost.com/scim/v2  if you are on the European server.)
   2. Unique identifier field for users: userName
   3. Authentication mode: HTTP
   4. Supported provisioning actions: 1. Push New users, 2. Push Profile Updates
   5. Authorization for HTTP Header:  token from Settings->Security->Provisioning
6. Edit Provisioning to App to enable
   1. Create users
   2. Update user attributes
   3. Deactivate users
7. In Attribute mapping, remove all attributes except username, given name and family name. (optional)

Troubleshooting

There are cases where users can't be migrated via SCIM, such as:

• A user with the same email address already exists in Oktopost
• Your account reached its license limit
• Connection errors

In these cases, you can go to your team settings page and download a list of failed migrations where you see the error message. In most cases, to address them, it’s best to contact us.

Restrictions

When you change a user's information in your IdP, be sure to keep the Username and Email identical.

Support attributes (mapping)

Oktopost doesn't support all SCIM out-of-the-box user attributes. Currently, it supports only these user attributes:

• userName (mutable, requires the same value for email)
• Name (mutable)
  • name.givenName
  • name.familyName
• emails (only type=work and primary=true) (mutable)