SCIM

Automate user lifecycle management in Oktopost using the System for Cross-domain Identity Management (SCIM) protocol.

SCIM (System for Cross-domain Identity Management) enables you to automate user provisioning and deprovisioning in Oktopost directly from your identity provider (IdP). When integrated with platforms like Okta, Azure AD, or OneLogin, SCIM automatically creates, updates, and deactivates user accounts based on changes in your corporate directory.

SCIM provisioning is available on Oktopost Advanced plan. Contact your account manager to enable SCIM for your organization.

What is SCIM?

SCIM is an open standard protocol that provides a defined schema for representing users and groups, along with a RESTful API for managing identity information. It enables secure, automated exchange of user identity data between your identity provider and Oktopost.

Benefits

Automated Onboarding - New employees get Oktopost access automatically when added to your IdP
Real-time Updates - Profile changes in your IdP sync immediately to Oktopost
Instant Deprovisioning - Removing users from your IdP instantly revokes Oktopost access
Reduced IT Workload - Eliminate manual account creation and management tasks
Enhanced Security - Centralized control over user access and permissions
Audit Trail - Complete visibility into user provisioning activities

How SCIM Works

User Added to IdP - A new employee is added to your identity provider (e.g., Okta)
SCIM Sync Triggered - Your IdP sends a SCIM request to Oktopost's SCIM endpoint
User Created - Oktopost receives the request and creates the user account
Profile Updates - Any changes to user attributes in the IdP are synced to Oktopost
User Deactivated - When a user is removed from the IdP, their Oktopost account is deactivated

Prerequisites

Before configuring SCIM provisioning, ensure you have:

An Oktopost Advanced or Enterprise plan with SCIM enabled
Administrator access to your identity provider (Okta, Azure AD, OneLogin, etc.)
Administrator access to your Oktopost account
Your SCIM API token (available in Oktopost under Account Settings → Security → Provisioning)

SCIM Endpoints

Oktopost provides two SCIM 2.0 endpoints depending on the type of users you're provisioning:

For provisioning users who manage social media campaigns, posts, and analytics:

US Region:

https://app.oktopost.com/scim/v2

EU Region:

https://eu-app.oktopost.com/scim/v2

Advocates (Employee Advocacy Users)

For provisioning advocates who participate in your employee advocacy program:

US Region:

https://board.oktopost.com/scim/v2

EU Region:

https://eu-board.oktopost.com/scim/v2

SCIM provisioning does not support role assignment. All provisioned users are assigned the default role configured in your Oktopost account settings. To change user roles, you must update them manually in Oktopost after provisioning.

Supported Operations

Oktopost's SCIM implementation supports the following operations:

User Operations

Operation	HTTP Method	Description
Create User	POST	Create a new user account in Oktopost
Get User	GET	Retrieve user details by ID
List Users	GET	Retrieve all users with optional filtering
Update User	PUT/PATCH	Update user attributes (name, email, status, etc.)
Deactivate User	PATCH	Deactivate a user account (set active=false)

Group Operations

Operation	HTTP Method	Description
Create Group	POST	Create a new group in Oktopost
Get Group	GET	Retrieve group details by ID
List Groups	GET	Retrieve all groups with optional filtering
Update Group	PUT/PATCH	Update group membership and attributes
Delete Group	DELETE	Remove a group from Oktopost

Authentication

SCIM requests must be authenticated using a bearer token in the HTTP Authorization header.

Request Headers

Authorization: Bearer YOUR_SCIM_TOKEN
Content-Type: application/scim+json

Obtaining Your SCIM Token

You can generate your SCIM API token directly from your Oktopost account:

Navigate to Account Settings → Security → Provisioning
Click Generate Token (or Regenerate Token if one already exists)
Copy the token and store it securely
Use this token to configure your identity provider

Security Best Practices

Store your SCIM token securely and never commit it to version control. Rotate tokens periodically and immediately revoke tokens if compromised.

Configuration Guide

Step 1: Enable SCIM in Oktopost

Ensure SCIM is enabled for your Oktopost account (contact support if needed)
Navigate to Account Settings → Security → Provisioning
Click Generate Token to create your SCIM API token
Copy and securely store the token - you'll need it to configure your IdP
Note your SCIM endpoint URL based on your region (US or EU)

Step 2: Configure Your Identity Provider

The configuration steps vary by IdP. Below are guides for common platforms:

Okta Configuration

In Okta Admin Console, go to Applications → Applications
Click Browse App Catalog
Search for "SCIM 2.0 Test App (Header Auth)" and click Add
Configure the app with a name (e.g., "Oktopost SCIM")
Click Done
Navigate to the Provisioning tab
Click Configure API Integration
Check Enable API Integration
Enter the appropriate Oktopost SCIM endpoint URL:
- For application users (social media managers):
  - US: https://app.oktopost.com/scim/v2
  - EU: https://eu-app.oktopost.com/scim/v2
- For advocates (employee advocacy):
  - US: https://board.oktopost.com/scim/v2
  - EU: https://eu-board.oktopost.com/scim/v2
Paste your SCIM token in the Authorization field
Click Test API Credentials
If successful, click Save

Azure AD Configuration

In Azure Portal, go to Azure Active Directory → Enterprise Applications
Click New application
Click Create your own application
Name it "Oktopost SCIM" and select Integrate any other application
Go to the Provisioning section
Set Provisioning Mode to Automatic
In Admin Credentials:
- Tenant URL: Enter the appropriate Oktopost SCIM endpoint:
  - For application users (US): https://app.oktopost.com/scim/v2
  - For application users (EU): https://eu-app.oktopost.com/scim/v2
  - For advocates (US): https://board.oktopost.com/scim/v2
  - For advocates (EU): https://eu-board.oktopost.com/scim/v2
- Secret Token: Enter your SCIM token
Click Test Connection
If successful, click Save

OneLogin Configuration

In OneLogin, go to Applications → Applications
Click Add App
Search for "SCIM Provisioner with SAML (SCIM v2 Core)" and select it
Configure the app name (e.g., "Oktopost SCIM")
Go to the Configuration tab
Enter the following:
- SCIM Base URL: Enter the appropriate Oktopost SCIM endpoint:
  - For application users (US): https://app.oktopost.com/scim/v2
  - For application users (EU): https://eu-app.oktopost.com/scim/v2
  - For advocates (US): https://board.oktopost.com/scim/v2
  - For advocates (EU): https://eu-board.oktopost.com/scim/v2
- SCIM Bearer Token: Your SCIM token
Click Save
Go to the Provisioning tab and enable desired provisioning actions

Step 3: Configure Provisioning Actions

Enable the provisioning actions you want to use:

Action	Description
Create Users	Automatically create Oktopost accounts for assigned users
Update User Attributes	Sync profile changes (name, email, role) from IdP to Oktopost
Deactivate Users	Automatically deactivate Oktopost accounts when users are removed
Push Groups	Create and manage Oktopost groups based on IdP groups

Step 4: Map User Attributes

Configure attribute mappings to determine which user fields sync from your IdP to Oktopost.

Standard Attributes

Oktopost Attribute	IdP Attribute	Required
userName	email	Yes
givenName	firstName	Yes
familyName	lastName	Yes
email	email	Yes
active	active	Yes

Step 5: Assign Users and Groups

In your IdP, assign users or groups to the Oktopost SCIM application
The first sync will create corresponding accounts in Oktopost
Future changes will sync automatically based on your provisioning settings

Step 6: Test the Integration

Create a test user in your IdP and assign them to Oktopost
Verify the user appears in Oktopost within a few minutes
Update the test user's name or email in the IdP
Confirm the changes sync to Oktopost
Deactivate the test user in the IdP
Verify the user is deactivated in Oktopost

User Schema

Oktopost's SCIM implementation follows the SCIM 2.0 Core Schema specification.

User Resource Example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "00U0000000000001",
  "userName": "john.doe@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe",
    "formatted": "John Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2024-01-15T10:30:00Z",
    "lastModified": "2024-01-15T10:30:00Z"
  }
}

Group Schema

Group Resource Example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
  "id": "00G0000000000001",
  "displayName": "Marketing Team",
  "members": [
    {
      "value": "00U0000000000001",
      "display": "John Doe"
    },
    {
      "value": "00U0000000000002",
      "display": "Jane Smith"
    }
  ],
  "meta": {
    "resourceType": "Group",
    "created": "2024-01-15T10:30:00Z",
    "lastModified": "2024-01-15T10:30:00Z"
  }
}

API Examples

Create User

Request:

POST /scim/v2/Users
Authorization: Bearer YOUR_SCIM_TOKEN
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName": "john.doe@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "active": true
}

Response:

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "00U0000000000001",
  "userName": "john.doe@example.com",
  "name": {
    "givenName": "John",
    "familyName": "Doe"
  },
  "emails": [
    {
      "value": "john.doe@example.com",
      "type": "work",
      "primary": true
    }
  ],
  "active": true,
  "meta": {
    "resourceType": "User",
    "created": "2024-01-15T10:30:00Z",
    "lastModified": "2024-01-15T10:30:00Z",
    "location": "https://app.oktopost.com/scim/v2/Users/00U0000000000001"
  }
}

Update User

Request:

PATCH /scim/v2/Users/00U0000000000001
Authorization: Bearer YOUR_SCIM_TOKEN
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "name.givenName",
      "value": "Jonathan"
    }
  ]
}

Deactivate User

Request:

PATCH /scim/v2/Users/00U0000000000001
Authorization: Bearer YOUR_SCIM_TOKEN
Content-Type: application/scim+json

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations": [
    {
      "op": "replace",
      "path": "active",
      "value": false
    }
  ]
}

List Users

Request:

GET /scim/v2/Users?startIndex=1&count=100
Authorization: Bearer YOUR_SCIM_TOKEN

Response:

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 250,
  "itemsPerPage": 100,
  "startIndex": 1,
  "Resources": [
    {
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
      "id": "00U0000000000001",
      "userName": "john.doe@example.com",
      "name": {
        "givenName": "John",
        "familyName": "Doe"
      },
      "active": true
    }
  ]
}

Troubleshooting

Connection Test Fails

Problem: API credentials test fails during IdP configuration

Solutions:

Verify the SCIM endpoint URL matches your account region (US vs EU)
Confirm your SCIM token is correct and hasn't expired
Check that SCIM is enabled for your Oktopost account
Ensure there are no firewall rules blocking the connection

Users Not Creating

Problem: Users assigned in IdP don't appear in Oktopost

Solutions:

Verify "Create Users" provisioning action is enabled
Check that required attributes (email, firstName, lastName) are mapped
Review IdP provisioning logs for error messages
Confirm users are actually assigned to the SCIM application in your IdP

Profile Updates Not Syncing

Problem: Changes to user profiles in IdP don't sync to Oktopost

Solutions:

Enable "Update User Attributes" provisioning action
Verify attribute mappings are configured correctly
Check if the changed attribute is included in your mapping
Review sync logs in your IdP for any errors

User Deactivation Issues

Problem: Removed users remain active in Oktopost

Solutions:

Enable "Deactivate Users" provisioning action
Verify the user was properly unassigned from the SCIM app (not just deactivated)
Check IdP logs to confirm a deactivation request was sent
Note: Deleting a deactivated user in the IdP doesn't trigger additional SCIM requests

Group Sync Failures

Problem: Groups from IdP don't sync to Oktopost

Solutions:

Enable "Push Groups" provisioning action
Verify group assignments in your IdP
Check that group names don't conflict with existing Oktopost groups
Review IdP logs for group-related errors

Best Practices

Security

Protect Your Token - Store SCIM tokens in secure credential management systems
Rotate Regularly - Request new tokens periodically and revoke old ones
Monitor Access - Review SCIM activity logs in your Oktopost account
Limit Scope - Only enable provisioning actions you actively use

Testing

Use a Test Account - Test SCIM integration in a non-production environment first
Verify All Actions - Test create, update, and deactivate operations before going live
Monitor Initial Sync - Watch the first bulk user sync carefully for any issues
Document Mappings - Keep clear documentation of your attribute mappings

Maintenance

Review Logs - Regularly check IdP provisioning logs for errors or warnings
Audit Users - Periodically review Oktopost users against your IdP to catch sync issues
Update Mappings - Adjust attribute mappings as your requirements evolve
Communicate Changes - Notify your team before making provisioning configuration changes

Check Documentation - Review this guide and your IdP's SCIM documentation
Contact Support - Email help@oktopost.com for configuration assistance
Review Logs - Check your IdP's provisioning logs for specific error messages

On this page