1. Home >
2. SCIM >
3. Step 1. Define Your SCIM User Schema

Step 1. Define Your SCIM User Schema

The first step in implementing SCIM for your app is to define a JSON schema that represents your user based on your app’s requirements. You’ll provide this schema to OneLogin as your SCIM JSON template. This template will tell the OneLogin SCIM provisioning service how to provision user values to your app.

Where to start? Take a look at the SCIM-compliant OneLogin Core User Schema, which contains the minimum set of attributes required by the OneLogin provisioning service:

OneLogin Core User Schema

{
    "schemas": [
        "urn:scim:schemas:core:1.0"
    ],
    "userName": "{$parameters.scimusername}",
    "name": {
        "givenName": "{$user.firstname}",
        "familyName": "{$user.lastname}",
        "formatted": "{$user.display_name}"
    }
}

A few things to note about this schema:

• It is an abbreviated version of the standard SCIM User Schema.

• Notice that the userName value is brought in using a parameter. For more info about parameters in the schema template, see Using Parameters in the Schema Template.

• OneLogin will set the $user.display_name value as a concatenation of the firstname and lastname values. If you need more than the minimum set of attributes, consider using the SCIM-compliant OneLogin Enterprise User Schema:

OneLogin Enterprise User Schema

{
    "schemas": [
        "urn:scim:schemas:core:1.0",
        "urn:scim:schemas:extension:enterprise:1.0"
    ],
    "userName": "{$parameters.scimusername}",
    "name": {
        "familyName": "{$user.lastname}",
        "givenName": "{$user.firstname}",
        "formatted": "{$user.display_name}"
    },
    "emails": {
        "value": "{$user.email}",
        "type": "work",
        "primary": true
    },
    "title": "{$parameters.title}",
    "urn:scim:schemas:extension:enterprise:1.0": {
        "department": "{$parameters.department}",
        "manager": {
            "managerId": "{$parameters.external_manager_id}",
            "displayName": "{$user.manager_firstname} {$user.manager_lastname}"
        }
    }
}

A few things to note about this schema:

• It includes the OneLogin Core User Schema, plus the emails, title, department, and manager attributes.

• The manager attribute is brought in using the SCIM Enterprise User Schema Extension.

• The managerId is brought in using a parameter. For more info about parameters in the schema template, see Using Parameters in the Schema Template.

If necessary, you can add other attributes to the OneLogin Core and Enterprise User Schemas from the SCIM User Schema, as well as the SCIM Enterprise User Schema Extension.

Or, you can define your schema straight from the source using the SCIM User Schema and the Enterprise User Schema Extension, if you need to extend the SCIM User Schema.

If an attribute you need isn’t covered by the SCIM User Schema and Extension, you can use custom attributes.

If you need to provision users to a group, use the Group parameter. See Provisioning Users into Groups for details.

Understanding Parameters in Your SCIM JSON Template

For development purposes, you don’t need to use parameters in your schema and can keep things simple by just using $user attributes.

Once you contact OneLogin to publish your app, we’ll take the $user attributes you’ve included in your schema and, when appropriate, replace them with parameters when we want to be able to derive values programmatically based on any of the following logic:

• Attribute relationships

• Integrations to other systems

• Other logic that we’ll build into your app’s connector

However, you’ll notice that the OneLogin Core and Enterprise User Schemas already include a couple of attributes that are brought in using parameters. For example:

• "userName": "{$parameters.scimusername}" in the OneLogin Core User Schema

  Once you contact OneLogin to publish your app, we will set up a parameter that will populate the userName value with the user’s email value or another value of your choice.

  We recommend that you set this attribute in this way so that at least one of your schema values will be populated via a parameter. This will enable the OneLogin SCIM provisioning service to automatically update provisioned users going forward.

  For example, if the user’s familyName value changes in OneLogin, the OneLogin SCIM provisioning service can automatically update the user’s familyName value in your app.

• "managerId": "{$parameters.external_manager_id}" in the OneLogin Enterprise User Schema

  OneLogin will derive this value programmatically based on attribute relationships.

Adding Custom Attributes

If you need an attribute that is not included in the SCIM standard, you can use a custom attribute. For example, here is the OneLogin Core User Schema with a few custom attributes added. Note the attributes brought in by urn:scim:my:custom:schema:

{
    "schemas": [
        "urn:scim:schemas:core:1.0",
        "urn:scim:my:custom:schema"
    ],
    "userName": "{$parameters.scimusername}",
    "name": {
        "familyName": "{$user.lastname}",
        "givenName": "{$user.firstname}",
        "formatted": "{$user.display_name}"
    },
    "urn:scim:my:custom:schema": {
        "vi_or_emacs": "{$user.custom_fields.vi_or_emacs}"
        "tabs_or_spaces": "{$user.custom_fields.tabs_or_spaces}"
    }
}

In the example above, the template includes urn:scim:my:custom:schema and $user.custom_fields. to bring in custom SCIM values vi_or_emacs and tabs_or_spaces.

Part of the work that OneLogin will do to turn your schema into a permanent connector in our catalog will be changing these custom fields into parameters. directives. This will ensure that customers can map values from their user directory into your application.

If you do use custom fields in your SCIM implementation, please let OneLogin know. We’ll ask you to tell us about how you want them to be used so that we can accurately configure your connector to work with parameters.

A few more important notes about custom attributes:

• A OneLogin Developer account will enable you to create custom attributes. If your account does not enable you to create custom attributes, contact scim-support@onelogin.com for assistance.

• When defining your custom attribute names, do not use spaces or dashes. Use underscores or camelcase instead to help with name readability.

• Including custom attributes in your user schema requires that your app users belong to organizations that subscribe to the OneLogin Unlimited plan.

• Consider the customer’s ability to provide a value for a custom attribute. It may be useful to your app, but if you make it required, will it preclude customers from being able to uptake your app?

For more info about adding custom user fields to your SCIM test app and testing them, see Provisioning Custom User Fields to Users.

$user Attributes Reference

Here is a list of $user attributes available for OneLogin SCIM provisioning. They are paired with their related SCIM user attributes. When a SCIM user attribute value needs to be calculated by OneLogin, we provide a parameter instead.

SCIM User Schema Attribute	Proposed OneLogin $user Attribute	OneLogin Schema
userName	$parameters.scimusername	Core, Enterprise
name : givenName	$user.firstname	Core, Enterprise
name : familyName	$user.lastname	Core, Enterprise
name : formatted	$user.display_name	Core, Enterprise
groups: We do not use a schema to provision group information. Instead, we provide a parameter that brings in group information using a separate group object.	Parameter: Groups See Provisioning Users into Groups.	Core, Enterprise
emails : value	$user.email	Enterprise
title	$parameters.title	Enterprise
manager : managerId (extension)	Parameter: Manager parameters.external_manager_id See Using Parameters in the Schema Template.	Enterprise
manager : displayName (extension)	$user.manager_firstname $user.manager_lastname	Enterprise
department (extension)	$parameters.department	Enterprise
id	$user.id	Add, if needed
externalId	$user.external_id	Add, if needed
phoneNumbers : value	$user.phone	Add, if needed
locale	$user.locale_code	Add, if needed
active	$user.status	Add, if needed
meta : created	$user.created_at	Add, if needed
meta : lastModified	$user.updated_at	Add, if needed

Other Available $user Attributes

Attribute	Description
$user.activated_at	Date and time at which the user’s status was set to 1 (active).
$user.company	Company that the user works for.
$user.directory_id	ID of the directory (Active Directory, LDAP, for example) from which the user was created.
$user.distinguished_name	Synchronized from Active Directory.
$user.invalid_login_attempts	Number of sequential invalid login attempts the user has made that is less than or equal to the Maximum invalid login attempts value defined on the Session page in OneLogin. When this number reaches this value, the user account will be locked for the amount of time defined by the Lock effective period field on the Session page and this value will be reset to 0.
$user.invitation_sent_at	Date and time at which an invitation to OneLogin was sent to the user.
$user.last_login	Date and time of the user’s last login.
$user.locked_until	Date and time at which the user’s account will be unlocked.
$user.member_of	Synchronized from Active Directory.
$user.openid_name	OpenID URL that can be configured in other applications that accept OpenID for sign-in.
$user.password_changed_at	Date and time at which the user’s password was last changed.
$user.samaccountname	Synchronized from Active Directory.
$user.userprincipalname	Synchronized from Active Directory.

If you need attributes that aren’t addressed by the user attributes discussed here, consider using parameters or custom attributes.

---