Check the availability in our pricing page.
SCIM (System for Cross-domain Identity Management) is an open standard that automates the exchange of user identity data across systems.
Okta includes native SCIM 2.0 support for provisioning, user synchronization, and attribute lifecycle management with third-party applications.
This article outlines how to define, expose, and map SCIM attributes in Okta so they can be consumed by external applications.
Supported SCIM Schemas #
Okta implements several SCIM 2.0 schemas, each defining a set of attributes that describe a user. These schemas are used during user provisioning and sync operations.
Core User Schema #
- URN:
urn:ietf:params:scim:schemas:core:2.0:User.
The core schema contains the standard SCIM 2.0 user attributes and is always included in outbound SCIM payloads.
Example JSON #
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "00u12345abcdXYZ",
"userName": "john.doe@example.com",
"name": {
"formatted": "John Doe",
"familyName": "Doe",
"givenName": "John",
"middleName": "A",
"honorificPrefix": "Mr.",
"honorificSuffix": "Jr."
},
"displayName": "John Doe",
"nickName": "Johnny",
"profileUrl": "https://example.com/john.doe",
"emails": [
{
"value": "john.doe@example.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"type": "work",
"streetAddress": "123 Main St",
"locality": "San Francisco",
"region": "CA",
"postalCode": "94105",
"country": "US",
"primary": true
}
],
"phoneNumbers": [
{
"value": "+1-415-555-1234",
"type": "work"
}
],
"preferredLanguage": "en-US",
"locale": "en-US",
"timezone": "America/Los_Angeles",
"active": true,
"password": "hashed-password"
}
Enterprise User Schema #
- URN:
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.
This schema extends the core user resource with enterprise-centric attributes such as department, manager, and costCenter.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName": "john.doe@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "E12345",
"costCenter": "CC1001",
"organization": "Engineering",
"division": "Software Development",
"department": "R&D",
"manager": {
"managerId": "00u67890abcdXYZ",
"displayName": "Jane Smith"
}
}
}
Custom Extension Schema #
- URN:
urn:okta:custom:schema.
Okta allows administrators to define custom schemas for attributes that fall outside the SCIM standard. This schema can use any URN string of your choice.
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:okta:custom:schema"
],
"userName": "john.doe@example.com",
"name": {
"givenName": "John",
"familyName": "Doe"
},
"urn:okta:custom:schema": {
"customEmployeeType": "Contractor",
"customStartDate": "2024-01-10",
"customSecurityClearance": "Level 3"
}
}
Creating New Custom Attributes #
To define and expose a new SCIM custom attribute in Okta, start by opening your SCIM application and navigating to Applications > Your SCIM App > Provisioning > To App.
Next, go to the Profile Editor by clicking Go to Profile Editor. From there, create a new attribute by clicking Add Attribute and configuring the following properties:
- Display Name (for example, Security Clearance Level).
- Variable Name (e.g.,
customSecurityClearance). - External Name (the SCIM attribute key, such as
urn:okta:custom:schema:customSecurityClearance). - External Namespace (the URN of your custom schema).
- Data Type (
String,Boolean,Number, orDate).
After saving the new attribute, assign it to a user profile by opening any user in Okta and confirming that the attribute appears in the profile section.
Mapping Attributes in Okta #
After creating both standard and custom attributes, they need to be mapped to ensure that data flows correctly between Okta and your SCIM-enabled application.
To do this, go to SCIM App > Provisioning > To App and click Edit to enable attribute mappings.
For each attribute you want to map, select the corresponding Okta User Profile Attribute (for example, user.profile.department) and specify the App User Attribute path (e.g., urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department). Once all mappings are configured, save your changes.
Finally, test the provisioning by updating a user in Okta and verifying that the changes propagate correctly to the target application via the SCIM API.
Example mapping table #
| OKTA Attribute | SCIM Attribute Path |
|---|---|
user.profile.firstName
|
name.givenName
|
user.profile.lastName
|
name.familyName
|
user.profile.email
|
emails[primary eq true].value
|
user.profile.department
|
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User.department
|
user.profile.customSecurityClearance
|
urn:okta:custom:schema:customSecurityClearance
|