Configure inbound SCIM provisioning

SecureAuth acts as an inbound SCIM v2.0 provider, enabling external identity providers to automatically provision and manage users in SecureAuth. This guide shows you how to configure inbound SCIM v2 integration so external systems can provision users into SecureAuth.

Use cases

• Automatically provision users into SecureAuth from your HR system or identity provider (like Okta, Microsoft Entra ID, and so on)
• Synchronize user attributes from external systems into SecureAuth
• Automatically deprovision or deactivate SecureAuth users when they're removed from your external IdP
• Maintain a single source of truth for identity data in your external system while keeping SecureAuth synchronized

Prerequisites

Before you begin, ensure you have:

• Administrator access to your SecureAuth IAM tenant
• The Identity Pool ID where users will be provisioned
• Access to configure your external identity provider (for example, Okta, Microsoft Entra ID, etc.)
• Understanding of your workspace's user schemas and which custom fields are configured

Step 1: Create a SCIM service application

Create a dedicated OAuth 2.0 client application in your SecureAuth System workspace to authenticate SCIM requests.

1. In your Tenant Settings, go to the Workspace Management page, select Administrative tab and click System Workspace.

   System Workspace Access

   If you don't see the System workspace, contact Support.

   

2. In your System workspace, click Applications > Clients.

3. Click Create Client.

4. Configure the application:

   • Name – Enter a descriptive name (for example, Client for Okta SCIM Provisioning).

   • Application Type – Select Service (OAuth).

   

5. Click Create.

Step 2: Configure OAuth scopes

The SCIM client requires the scim_v2 scope to access provisioning APIs.

1. Open your newly created SCIM application.

2. Go to the Scopes tab.

3. Select the Identity check box, then click Identity to expand the list and select the scim_v2 check box.

   

4. Save your changes.

Step 3: Configure token lifetime

Choose one of the following token configuration options based on your identity provider's capabilities.

Option A: Long-lived access tokens

Use this option for identity providers without refresh token support.

1. Open your SCIM application.

2. Go to the OAuth tab, and scroll down to Token Time to Live Settings.

3. Enable Use specific token time-to-live.

4. Configure the following:

   • Access token TTL – Set to a large value (for example, 99999h for approximately 11 years).

   • Refresh token TTL – Not needed if using long-lived access tokens.

5. Save your changes.

Option B: Standard token settings

Use this option for identity providers with automatic token refresh.

Keep default TTL values:

• Access token TTL – 1 hour (3600 seconds)
• Refresh token TTL – 720 hours (30 days)

Your identity provider will automatically refresh tokens as needed.

Step 4: Obtain authentication credentials

Your identity provider needs credentials to authenticate SCIM API requests. SecureAuth supports two authentication methods.

Method A: Client credentials

Use this method for identity providers that support automatic token refresh.

1. From your SCIM application's Overview tab, copy:

   • Client ID
   • Client Secret

   

2. Provide these credentials to your identity provider administrator.

Your identity provider will use these to obtain access tokens automatically via OAuth 2.0 client credentials flow.

Method B: Pre-generated bearer token

Use this method if your identity provider requires a pre-generated bearer token or doesn't support client credentials.

Generate an access token:

curl -X POST \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "scope=scim_v2" \
  https://<TENANT_ID>.<REGION>.connect.secureauth.com/<TENANT_ID>/system/oauth2/token

Replace YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_TENANT_ID, and YOUR_REGION with your actual values.

Example response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjEzNTY5...",
  "expires_in": 359999640,
  "scope": "scim_v2",
  "token_type": "bearer"
}

note

The expires_in value reflects your configured token TTL. If you set a long-lived token (for example, 99999h), the token will remain valid for years.

Step 5: Configure your identity provider

SCIM base URL

Provide your identity provider administrator with the SCIM Base URL:

https://<TENANT_ID>.<REGION>.connect.secureauth.com/api/identity/<TENANT_ID>/system/pools/<IDENTITY_POOL_ID>/scim/v2

Example:

https://acme-corp-us.us.connect.secureauth.com/api/identity/acme-corp-us/system/pools/ba6e4b7c1f8e4aeda08ce95e99d17af8/scim/v2

warning

Do not add /Users or /Groups to the end of this URL. Most identity providers (Okta, OneLogin, Azure AD) automatically append these paths. Adding them manually will cause the integration to fail.

SecureAuth SCIM schemas and custom attributes

SecureAuth supports both the default SCIM core schema and a SecureAuth extension for custom attributes. Always include both in the schemas array:

"schemas": [
  "urn:ietf:params:scim:schemas:core:2.0:User",
  "urn:ietf:params:scim:schemas:extension:secureauthciam:2.0:User"
]

Core SCIM schema

The core SCIM 2.0 User schema provides standard attributes like userName, emails, phoneNumbers, active, and groups. SecureAuth requires only userName by default and typically maps it to the unique user identifier in your system. All other fields are optional unless made required in your Identity Pool schema or enforced by your external identity provider.

SecureAuth extension schema

SecureAuth extends SCIM with three configurable groups, visible in Users > Schemas and referenced in API requests as:

UI Tab	API Field Name	Example
PROFILE	payload	"first_name": "Jane", "last_name": "Smith"
ADMINISTRATIVE	metadata	"employee_id": "EMP-12345"
DELEGATED	businessMetadata	"project_role": "Manager"

note

All custom fields must use snake_case.

Inspect your schema

To inspect your schema and see all valid fields:

curl -X GET \
  "https://<TENANT_ID>.<REGION>.connect.secureauth.com/api/identity/<TENANT_ID>/system/pools/<POOL_ID>/scim/v2/Schemas" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Accept: application/json"

Example: Create a user

curl -X POST 'https://<TENANT_ID>.<REGION>.connect.secureauth.com/api/identity/<TENANT_ID>/system/pools/<POOL_ID>/scim/v2/Users' \
  -H "Accept: application/json" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": [
      "urn:ietf:params:scim:schemas:core:2.0:User",
      "urn:ietf:params:scim:schemas:extension:secureauthciam:2.0:User"
    ],
    "userName": "anna.jones@example.com",
    "active": true,
    "emails": [
      {
        "value": "anna.jones@example.com",
        "type": "work",
        "primary": true
      }
    ],
    "urn:ietf:params:scim:schemas:extension:secureauthciam:2.0:User": {
      "payload": {
        "first_name": "Anna",
        "last_name": "Jones"
      },
      "metadata": {
        "employee_id": "EMP-77777",
        "department": "Finance"
      },
      "businessMetadata": {
        "cost_center": "CC-456",
        "project_role": "Project Manager"
      }
    }
  }'

Example: Create a group and add a user

Create a group

To create a group in SecureAuth using SCIM, send a POST request to the /Groups endpoint with a displayName field. For example, the following command creates a group named "Finance Team":

curl -X POST 'https://<TENANT_ID>.<REGION>.connect.secureauth.com/api/identity/<TENANT_ID>/system/pools/<POOL_ID>/scim/v2/Groups' \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Finance Team",
    "externalId": "",
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"]
  }'

Add a user to a group

After you create the group and have its SCIM ID, add an existing user to it. For instance, to add Anna Jones (user ID: 79859dddf40d4b26afa2b5d9bbd9d515) to the "Finance Team" group (group ID: 308cf9c1a5c54e1799c9ff6ec3d0b2f9), use the following PATCH request:

curl -X PATCH 'https://<TENANT_ID>.<REGION>.connect.secureauth.com/api/identity/<TENANT_ID>/system/pools/<POOL_ID>/scim/v2/Groups/308cf9c1a5c54e1799c9ff6ec3d0b2f9' \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
      {
        "op": "add",
        "path": "members",
        "value": [
          {
            "value": "79859dddf40d4b26afa2b5d9bbd9d515",
            "display": "anna.jones@example.com"
          }
        ]
      }
    ]
  }'

API reference

For detailed API documentation, including all supported endpoints, request/response formats, and error codes, refer to:
SecureAuth SCIM v2 API documentation