Setting up SCIM on Okta

Available for Enterprise plans

SCIM is used for automatic provisioning of Pigeonhole Live accounts for new employees in an organisation, and deprovisioning the account for offboarding employees. This makes the management, creation, and deletion of Pigeonhole accounts for  an organisation more streamlined, secure, and efficient.

This article will guide you through the steps to set up SCIM for Okta. First, you will need to enable SSO for your workspace, and ensure that Domain Restrictions for your Organisation has been set up. You may need to check with your Account Manager to ensure that this is in place.

Once you've completed the initial steps, follow the instructions below to continue.


Enable SCIM provisioning on Pigeonhole Live

In your Organisation settings, click SCIM in the left side menu.

If you see this screen, the Domain Restrictions for your organisation has not been set up. Please contact your Account Manager for assistance in setting it up.

Once Domain Restrictions are in place, check Enable SCIM provisioning.

Under Provision workspaces from, select the licence from which you would like to allocate workspaces for provisioned users.

Then select an Organisation Admin to be the transferee under Transfer deprovisioned workspaces to - this is required for when the user is deprovisioned, his workspaces will be transferred over to this selected Organisation Admin. This ensures that data is retained even when an employee leaves the organisation, and that managers would have oversight and can manage this data. When done click Save.

If you are unable to select this, contact your Account Manager.

After saving, new setup information will be supplied. Click Generate Token. Please be aware that the token has a limited validity period, displayed under the token.

Enable SCIM on Okta

On Okta dashboard, under the General tab, click Edit.

For Provisioning setting, select SCIM and click save.

After this, a Provisioning tab will appear on your app menu. Click Provisioning and then click Edit in SCIM Connection.

The value for SCIM connector base URL is found in your Pigeonhole Organisation settings, SCIM tab.

For Unique identifier field for users, enter email.

Under Supported provisioning actions, select:

- Push new Users

- Push Profile Updates

Under Authentication Mode, select HTTP Header.

The value for the HTTP Header Authorization is found in your Pigeonhole dashboard, as SCIM Bearer Token. Copy this value.

Paste this value into the Authorization field and click Test connector Configuration.

If your test was successful, you should see this screen.

Click Close and Save.

Your Okta app page should now have updated settings.

Under To App, click Edit.

We now need to enable a few actions for Okta. Select Enable for:

- Create Users

- Update User Attributes

- Deactivate Users

And click Save.

At this point, you are ready to create Users, assign to this SCIM application, and check if the provisioning, update, or de-provisioning happens correctly.

Managing Users

If you have an existing integration, you can now set up automated user provisioning to the Pigeonhole Live application.

If you are managing your users through Okta, the following section will walk you through the steps of how to manually manage single users or as a group, including provisioning, editing, deprovisioning, and reactivation.

Create a user (User Provisioning)

You can manually add users on an individual basis to Okta.

In the admin dashboard on the left side menu, under Directory, click People.

In the People page, click Add person.

Fill in the details (both user name and primary email should be the same).

Once you click Save an activation email will be sent to the user’s email for them to activate.

After the user has activated their account, their name will appear on the People list.

Next, you must assign this user to the Pigeonhole application to allow them to login.

Under Applications, click Assign.

The new user will appear in the pop up. Click Assign.

Another form will appear to fill out more information.

After you’re done filling out the form, scroll to the bottom and click Save. Okta will call SCIM endpoints to provision the user.

If there are errors, an error message will be shown. You may reference Commonly Encountered Issues for troubleshooting steps.

Create a Group (Group Provisioning)

You can also assign multiple users to a group, and provision accounts for them all at once. This is useful if you have a large number of users to provision for.

On Okta dashboard, click on the Groups tab.

Click the Add group button, then a modal will pop up. Fill in the name of your desired group.

Click Save, the group will be successfully created and shown on the list.

Then, click on the group name you created and it will show more details of the group. Click on the Assign people button.

A list of users assigned to Okta will be shown. Click on the + icon to select the user you would like to add to the group. Successfully assigned users to the group will display a green tick.

Once you have completed assigning users to the group, head to the Okta application you created for Pigeonhole SCIM. Click on the Assignments tab.

Click on the Assign button, a dropdown will display. Click on Assign to Groups.

A modal will display a list of the Groups that have been created.

Click Assign for the group you would like to provision for. A new modal will display details of the assignment. Click Save and Go Back button to confirm.

In the group display modal, a group that has been Assigned will reflect the status as such, while groups that have not been assigned will remain as Assign.

Click Done to return to the Okta application and view the list of Groups added.

You can also check the list of individual users provisioned to Pigeonhole via the Filters > People tab on the left.

Assign user to a group on user creation

Once you have created Groups, when you are creating a new user in Okta, you can assign them to the Group during user creation.

Click on the People tab.

Click on Add person button and a modal will pop up

Key in the name of the Groups you would like to add the user to.

Edit a user

You can edit a user in the Application page, or in the Directory -> People page.

Applications page

In your application page, under the Assignments tab with the list of People, click the pen icon on their name row to open the edit pop up.

If you see this message saying to Reapply Mapping, click the button to apply the changes.

A form will appear and you will be able to edit the user. Scroll down and click Save to save any changes.

People directory

Under the People page in Directory, click on a user’s name to edit their profile.

This will bring you to the user’s page and the list of applications they’re assigned to.

To bring up the edit form pop up, click the pen icon on the user’s row.

Deactivate a user (User Deprovisioning)

Under the user’s page in the People directory, click More Actions, and then Deactivate.

You will be prompted to confirm this deactivation action.

Click Deactivate to continue.

On Okta, the Pigeonhole application assigned to the user will be removed on that user’s Okta account.

The user will no longer have access to Pigeonhole Live through this email address, and the user’s existing workspaces will be transferred to the transferee selected in SCIM settings.

Reactivate user

To reactivate a deactivated user, click the Activate button under their name.

This user will receive an email to activate their account and be provisioned again to the organisation. A new workspace will be assigned to the user and they will not  reactivate any existing workspaces within the Pigeonhole Organization they are in.

When a user is reactivated, they will appear in the organisation's user tab with a newly assigned workspace.

Commonly Encountered Issues

Visit the Okta support page for more support articles.

Read the error messages provided by Okta

Okta provides descriptive error messages when errors occur.

For example, if you input EmailAddress when the input is expecting Email, Okta will provide an error message saying that your input was invalid and provide a list of valid inputs.

Check the spelling of your input values

If the spelling of your inputs are incorrect, then errors can occur. Ensure the spelling is correct, and ensure the capitalization is what the input expects.

Ensure the tokens are correctly pasted

Try copy and pasting any tokens again. Invalid or expired tokens will cause authentication failures.

Contact your Account Manager

You may be lacking permissions to make configuration changes in the account. Contact your Pigeonhole Account Manager to ensure permissions and settings are enabled.

View your organisation activity with the System log

You can check the responses of the activity in your organisation by viewing the System log. If some actions were unsuccessful or there were errors, you can find the error log and details in this page.