This site requires JavaScript to be enabled
External Customer KB > General > Introduction to User Provisioning
Introduction to User Provisioning
Article: KB0010298 Published: 06/06/2019 Last modified: 02/18/2020

This article provides an overview of user provisioning in OneLogin and discusses the following topics:

For app-specific provisioning configuration instructions, see the provisioning article for your app in App Integration.

For an end-to-end walkthrough of a common approach to user provisioning from Active Directory (AD) through OneLogin to an app, see User Provisioning: An End-to-End Flow.

Introduction

OneLogin provisioning makes it easy to create, update, and delete users in the applications that your organization uses. This means that you can quickly add new users to multiple apps and de-provision users from those apps instantly when they change roles or leave your organization.

In a basic provisioning workflow, you add an app to a OneLogin role, and whenever a user is added to that role, the user is created in the app.  

In a basic provisioning workflow, you map OneLogin attributes like Email, AD user name, or Title to analogous app attributes, and whenever the OneLogin attributes change, the OneLogin provisioning engine updates the user in the app.

Some apps also allow you to provision entitlements, which are user attributes that are usually associated with fine-grained app access, like app role, group, department, organization, or license level. OneLogin imports your organization's app entitlement values (such as group names or license types) and lets you map them to OneLogin attribute values.

Let's say you map the OneLogin Department "Sales" to an app's Group "Sales and Marketing."  Whenever a user with a OneLogin Department "Sales" is added to a OneLogin role that includes the app, that user is provisioned to the app as a member of the app's Sales and Marketing Group. And whenever an existing user changes Department in OneLogin, OneLogin's provisioning engine updates the user's Group entitlement.

When it's time to de-provision a user from their apps, you simply disable the user in your directory (either OneLogin or a third-party directory like Active Directory), and the user's accounts in all OneLogin-managed apps will be deleted or suspended, depending on your configuration preferences. If a user is changing roles within the organization, you can provision them to new apps and de-provision them from the apps associated with their old role simply by changing their directory attributes (like role in OneLogin or group in AD).

NOTE: User provisioning requires the Unlimited Plan. Contact OneLogin sales for more details.

SCIM provisioning

Not all apps support provisioning through OneLogin, but OneLogin supports SCIM (System for Cross-domain Identity Management), a provisioning standard that provides full support for creating, deleting, and updating users in any cloud or on-premise app.

To find out which apps support SCIM provisioning or to request that an app support SCIM, contact scim-info@onelogin.com.

For more info about developing a SCIM-enabled app, see Dev Overview of SCIM.

SAML-based "just-in-time" user provisioning

Unless stated otherwise, OneLogin user provisioning refers to user provisioning performed via an API connection.

As an alternative to API-based provisioning, some OneLogin apps provide SAML-based “just-in-time” (JIT) provisioning.

With just-in-time provisioning, instead of creating user accounts in apps manually or using an API connection, the first time a user logs in to an app via OneLogin SAML SSO, the app takes user information in the SAML assertion and creates the user’s app account on the fly.

For example, when a user without an account in Box logs in to Box via OneLogin SAML SSO for the first time, a new user account will be created in Box.

However, while API-based provisioning can keep user information between OneLogin and the app in sync beyond the initial user account creation, just-in-time provisioning only works to create the initial user account and does not keep user information in sync with OneLogin beyond that point.

To find out if an app supports just-in-time provisioning, see app-specific documentation available from our App Integration page.

Setting up basic provisioning

This section describes the typical steps for setting up user provisioning in OneLogin. For app-specific provisioning instructions, see App Integration.

  1. Add the app to OneLogin and configure it for SSO.
  2. On the app connector's Configuration tab, enter your app admin username and password to connect to the app's API.

    Click Save.

  3. On the Provisioning tab, select Enable provisioning and set up your provisioning approval and deletion workflow.

    An administrator must manually approve any provisioning action you select here, every time it occurs.

    You can choose to delete, suspend, or do nothing to a user in the app when the user is deleted in OneLogin.

  4. Click Save.

OneLogin will now be able to provision users to the app.  

You can also create rules for provisioning users to your app based on user attributes like OneLogin roles or AD security groups.  And many apps also allow you to provision user entitlements, like app permissions, roles, licenses, or group membership. For details, see below.

Mapping app attributes to OneLogin attributes

OneLogin lets you map your app's user attributes to OneLogin user attributes, giving you control over how user attributes are provisioned from OneLogin to your app. For example, when you provision to Box, you would set the Box attribute User ID to the OneLogin attribute Email. You can also configure attributes so that they are not provisioned from OneLogin but are always set within the app itself.

The following procedure describes how to map user attributes from OneLogin to Google Apps, as an example. For your app--and for more detailed instructions for mapping Google Apps attributes--see the app-specific provisioning instructions in App Integration.

  1. Go to Apps > Company Apps to select the app.
  2. On the Parameters tab, map the app's user attributes to OneLogin attributes.

    This example shows the default attribute mappings for a Google Apps connector. The Google Apps attributes Email, Firstname, Lastname, and Password will be populated with whatever values are held by the mapped OneLogin user attribute.

    The mapping of Firstname and Lastname is straightforward. The mapping of the Google Apps Email and Password attributes bear some explanation. Email maps to the OneLogin Email name part attribute, because the domain is already known to Google Apps, so it doesn't hold the domain portion of the email address in its Email field. Password maps to the OneLogin SSO password--the password for the user's OneLogin account--which means that the Google Apps will use the OneLogin password as the app password.  

    Is Admin is set to False by default, allowing you to create a rule that sets a condition for provisioning Google Apps admin privileges to OneLogin users that meet specific conditions, such as membership in particular Active Directory security group. See the following step for details about creating rules.

    The remaining attributes are set to No default, which means that the attribute is set in the app and no values are passed from OneLogin. If you want to provision values from OneLogin to Google Apps for these attributes, you must enable entitlement provisioning.

  3. On the Rules tab, create rules to apply conditions to attribute mappings.

    Click New Rule to open the New Mapping dialog.

    In this example, we are creating a rule with the Condition MemberOf contains googleadmin and the Action Set is Admin to Is Admin, which gives Google Super Admin permissions to all members of the AD security group googleadmin.

    For more information, see Rules.

  4. Go to the More Actions menu and click Reapply Provisioning Mappings to apply the new rule.

    Important! You must reapply mappings any time you create or update rules!

Provisioning entitlements

Some apps allow you to provision entitlements--user attributes that are usually associated with fine-grained app access, like app role, group, department, organization, or license level. OneLogin imports your organization's app entitlement values (such as group names or license types) and lets you map them to OneLogin attribute values.

The following procedure describes how to import entitlement values from an app and create rules that enable you to assign entitlements to users in the app, depending on OneLogin attribute values. The procedure uses Google Apps as an example. For your app--and for more detailed instructions for provisioning entitlements to Google Apps--see the app-specific provisioning instructions in App Integration.

  1. Go to Apps > Company Apps to select the app.
  2. On the Configuration tab, select Provision Entitlements.
  3. On the Provisioning tab, click Refresh next to Entitlements to import the entitlement values from the app to OneLogin.
  4. On the Parameters tab, select the entitlement values that you want to make available for provisioning.

    Click the row of any attribute that holds entitlement values imported from the app. For example, Google Apps connectors let you provision entitlements for Google Groups and Organizations. If you click on the Groups row in the attribute list...

    ... you will see the available entitlement values on the Edit Field Groups dialog:

    Select the values that you want to be able to assign to Google Apps users by clicking them in the Available values box and clicking the right arrow.

    Scroll down and select Include in User Provisioning.

    Click Save. The values are now displayed on the attributes list on the Parameters tab.

    Note. Never set Default if no value selected to anything but - No default - and -- no transform -- for entitlements, like Groups, Licenses, Roles, etc.

  5. On the Rules tab, create rules to map OneLogin user attribute values to the entitlement values.

    Click New Rule to open the New Mapping dialog.

    In this example, we are creating a rule with the Condition MemberOf contains contractor and the Action Set Groups to Contractors, which puts all members of the AD security group contractor in the Google Group Contractors in Google Apps.

    For more information, see Rules.

  6. Go to the More Actions menu and click Reapply Provisioning Mappings to apply the new rule.

    Important! You must reapply mappings any time you create or update rules!

Synchronizing users

If you already have users set up in an app, you want OneLogin to know about those users and sync them to your OneLogin users.

  1. Go to Apps > Company Apps >Yourapp.
  2. Go to the More Actions menu and click Sync logins

OneLogin will retrieve the list of users currently in your app and automatically link those users to the local users assigned to the app based on the default username for the app, which for many apps is the email address.

There may be users accounts in the app that OneLogin can't sync to OneLogin users because they use different usernames. You can find and fix these unmatched users by going to the Users tab for your app connector and filtering users by Unmatched status. For more information, see Matching Users.

Important! If the app uses form-based authentication or provisions the password using an API, the Sync logins process overwrites the app passwords of the users that already exist in the app with the app passwords stored for those users in OneLogin.

Monitoring user provisioning

You can monitor user provisioning events using a few different pages in OneLogin. These pages give you access to the statuses of provisioning events, past and current, in your account. Click a status value to view details of the provisioning event.

To monitor provisioning events for all users:

Go to Users > Provisioning. The upper area of the page lists current provisioning events. The lower area of the page lists past provisioning events.

To monitor provisioning events for a specific user

Go to Users > All Users and select the user you want to see provisoning events for. Select the Applications tab.

To monitor provisioning events for a specific app

Go to Apps > Company Apps > App Name and select the Users tab.

You can sort by provisioning status to find the users you need to act on, like those in failed, pending, or unmatched status.

You can view error messages for failed provisioning statuses in the Notes column. If the error message is long, you can view the complete error message by hovering your cursor over the message. When you hover over the message, the Provisioning Status indicator also switches to say View Details; click it to open the details dialog, where you can see more information about the provisioning failure and, in some cases, retry provisioning.

Understanding and troubleshooting provisioning statuses

On any one of these pages, click a provisioning status value to access details about the provisioning event:

  • pending: Indicates that an admin must manually initiate the provisioning event. Click the status to access the ability to approve or skip (reject) the provisioning event. This pending state is the first step in the provisioning workflow if you opted to require admin approval of the user provisioning event (create, delete, or update) when configuring the app.

  • provisioning: Indicates that the user is in the process of being provisioned to the app.

  • modifying: Indicates that the user is in the process of being modified, or updated, in the app.

  • provisioned: Indicates that the user was successfully provisioned to the app.

  • failed: Indicates that the user could not be provisioned to the app. Click the status to access information about the failure. For example:

    A reason that references Invalid authentication, as shown here, most often means that OneLogin's connection to the app's provisioning API needs to be refreshed or re-authenticated. To do this, access the app (Apps > Company Apps and select your app) and click the Configuration tab. Use the controls in the API Connection area to refresh or re-authenticate your connection. For more specific details about connecting to the app's API, see the provisioning documentation for your app.

  • deleting: Indicates that the user is currently being deleted from the app. Once the deletion is complete, the provisioning event will be removed from the list of provisioning events. At this point, the deletion event can be viewed on the Provisioning page only.
  • unknown: This status is likely caused by using using the Disassociate login option on the app login for the user. To resolve this status, click the user name to display the Edit App Name Login For User Name page. Scroll down and click the Rematch login option to display various options you have for resolving the disassociation between the app and OneLogin. You have the option to take the user in the app and match it with a user in OneLogin, create a user in OneLogin, or delete the user in the app.

Applying bulk operations to users

The provisioning process can require various kinds of administrative intervention, depending on users' provisioning status, including:

  • Approve: if you've configured provisioning for the app to require admin approval, you must approve any users in pending status before they are provisioned to the app.
  • Skip: if you've configured provisioning for the app to require admin approval, you can skip (reject) users in pending status instead of approving them to be provisioned to the app.
  • Reapply mappings: apply rules to to ensure that users are provisioned with the correct attributes
  • Retry: if provisioning has failed for a user, you can retry provisioning.
  • Reset: if a user is in a "stuck" state, such as when a user is deleted directly in an application while there is a pending delete request in OneLogin, this operation sets the user back to a completely unprovisioned state, deletes any overwritten parameters, resets attributes to what they should be according to mappings, and reruns provisioning.

One handy way to perform these administrative actions is to filter users by status and then perform the action as a bulk operation on the users that are returned by the filter:

  1. Go to the Users tab for the app.
  2. Filter the users by the status you want to address:

  3. Select the action that you want to apply to the selected users from the far-right drop-down (which will be labeled Apply to filtered).

You can also apply the following bulk operations to all users in any provisioning state, without filtering:

  • Reapply mappings
  • Reset

If the operation doesn't apply to a user, no harm will befall them.

Automating provisioning approval

Once your users are set up and in sync, you can configure OneLogin to approve provisioning updates automatically.

  1. Go to Apps > Company Apps > Yourapp.
  2. On the Provisioning tab, clear the Create user and Update user checkboxes. 

    It's usually a good idea to keep Delete users checked, so that you can manually approve user deletions. 

  3. Click Save.

Expand/Collapse Comments
:     
Was this helpful?
YesYesNoNo