See scim Menu

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:

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.

Note: Left as-is, this will not work unless your customer happens to have the exact same user attribute values in their user directory. 

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.


Have a Question?

Have a how-to question? Seeing a weird error? Ask us about it on StackOverflow.

Found a bug? Submit a support ticket.

Have a product idea or request? Share it with us in our Ideas Portal.

StackOverflow discussions about "scim"

Loading...