Articles in this section

Provision for Workplace by Facebook

This article describes how to provision users from OneLogin to Workplace by Facebook using the Workplace API.

Note. Provisioning for Workplace by Facebook requires a subscription to the OneLogin Unlimited plan. To upgrade an existing plan, contact OneLogin Sales. If you are a new subscriber, you can sign up for the OneLogin Free Plan for Workplace by Facebook at www.onelogin.com/workplace.

Setting up provisioning involves four tasks:

  1. Connect to the Workplace API and enable provisioning
  2. Map Workplace user attributes to OneLogin attributes
  3. (Optional) Use rules to provision users to Workplace groups
  4. Test provisioning

Prerequisites

Configuring SAML SSO for Workplace by Facebook

Connect to the API and Enable Provisioning

  1. Go to Apps > Company Apps and select the Workplace by Facebook app to which you want to provision users.

  2. Go to the Configuration tab.

    The Subdomain should have been entered when you configured SSO for Workplace. If the Subdomain field is empty, enter your subdomain. 

  3. In order to retrieve the Community ID, you must generate a SCIM Bearer Token (access token). Open a new browser tab and log into Workplace as a System Administrator. Here you can generate the token needed to retrieve the Community ID and for the SCIM Bearer Token field. 

    Note: A Community ID is necessary if you intend to provision groups.

    In Workplace, Go to Integrations > Custom Integrations> Create Custom Integrations in lower left corner.

  4. Enter a Name and Description for the custom integration and click Create. 

  5. Click Create Access Token to generate a token. Copy this token and enter it into the SCIM Bearer Token field on the Configuration tab in OneLogin. You will use this token in the API call you'll make to retrieve the Community ID.

    Note: The access token is only displayed once. Copy and store this token in a secure place, secure notes for instance. 

  6. Grant desired permissions for your Workplace app. For a detailed description of Workplace permissions and definitions, see Workplace Permissions. Click Save.

  7. Now that you generated an access token, retrieve your Community ID by making a graph API call. Use the example Curl command below:

    ``curl -X GET \
https://graph.facebook.com/community/ \
-H 'Authorization: Bearer [your access token]' \
-H 'Cache-Control: no-cache' \```

    The graph API call returns your Community ID:

    "name": "OneLogin Dev"
"privacy": "CLOSED",
"id": "13452025411931098" (your Community ID)

  8. Copy the Community ID and paste it into the Community ID field on the Configuration tab in OneLogin.

  9. Set the SCIM Base URL to https://www.facebook.com/scim/v1/. 

  10. If your configuration is correct, the API status changes to Enabled.

    Note. The ​Suppress Invitation Emails​ option is no longer supported through the Workplace by Facebook API.

  11. When you are connected, click Save.

  12. Go to the Provisioning tab.

  13. Select Enable provisioning for Workplace by Facebook.

    Important! Once you enable this option and give users access to the app, the provisioning process will begin. You must select this option now to enable options required to complete subsequent steps. To ensure that you do not inadvertently provision users to Workplace before you are ready, enable the action controls described in the next step.

       

  14. Choose the provisioning actions that should require administrator approval.

    For any action you select, a OneLogin administrator must go to Users > Provisioning and manually approve each action for provisioning to complete. Clear these options if you want OneLogin to provision new users and user updates to Workplace without administrative approval.

    Important! When you first configure provisioning, we recommend that you enable these approval options so that you can confirm that the correct users are being provisioned with the correct entitlements. Once you have confirmed that provisioning is working as expected, you can clear these options to enable provisioning to proceed without approval, if you want.

  15. Select what happens to a user in Workplace when that user is deleted from OneLogin.

    Choose between Delete, Suspend, or Do Nothing.

    Note. According to Facebook, if a user has ever logged into their Facebook account, you cannot delete that account using the API, regardless of whether the account is currently active. Your only option is to select the Suspend option here. 
  16. Click Save.

Mapping Workplace Attributes to OneLogin Attributes

In this task, you map Workplace user attributes to default OneLogin user attributes. These mappings tell OneLogin how to populate user attribute values to Workplace when provisioning users from OneLogin. You can use these parameters to create provisioning rules (in the next task).

  1. Go to Apps > Company Apps and select your Workplace by Facebook app.

  2. Go to the Parameters tab.

  3. Select Configured by admin.

  4. For each field that you want to include in user provisioning, click the parameter row to open the Edit Field dialog, where you can change the default and select the Include in User Provisioning option. 

    See the table below for field-specific information.

    Workplace Field

    Default OneLogin Value

    SAML or Provisioning?

    Notes
    Closed Groups - No default - Provisioning

    Used to provision users to Workplace closed groups. By default, no values are passed to the Closed Groups field. If you want to configure OneLogin to provision closed group membership to Workplace users, see Using Rules to Provision Users to Workplace by Facebook Groups.
    Department - No default - Provisioning Set to Department to pass the user's OneLogin Department value to Facebook.
    Email Email SAML and Provisioning Leave Value set to Email.
    Location - No default - Provisioning Create a create a custom OneLogin field to hold this value and pass it to Workplace. This represents the "friendly" name of the user's location, which is displayed in the "Works in location" field on the user profile in Workplace.
    Manager - User Manager - Provisioning The OneLogin value cannot be changed. User Manager maps to the Manager value in the OneLogin user record.
    Name Identifier (Subject) - No default - SAML and Provisioning Typically, you would set this to Email.
    Open Groups - No default - Provisioning

    Used to provision users to Workplace public groups. By default, no values are passed to the Open Groups field. If you want to configure OneLogin to provision public group membership to Workplace users, see Using Rules to Provision Users to Workplace Groups.
    Photo - No default - Provisioning Currently this option is not functional. We are working with Facebook to bring this to you soon!
    Secret Groups - No default -  Provisioning

    Used to provision users to Workplace secret groups. By default, no values are passed to the Secret Groups field. If you want to configure OneLogin to provision secret group membership to Workplace users, see Using Rules to Provision Users to Workplace Groups.
    Start Date - No default - Provisioning Set to Start Date to pass the user's OneLogin Start Date value to Facebook.
    Title - No default - Provisioning Set to Title to pass the user's OneLogin Title value to Facebook.
  5. Click Save.

Using Rules to Provision Users to Workplace Groups

You can define rules to provision subsets of your OneLogin users into Workplace groups. For example, you can define a subset of users by filtering on a specific OneLogin user attribute value and then define an action that provisions the subset of users to a specific Workplace group.

  1. Go to Apps > Company Apps. Search for and select your Workplace app.

  2. Go to the Rules tab.

  3. Click New rule to open the New Mapping dialog, where you can set the conditions and actions that determine which users will be provisioned from from OneLogin to specific Workplace groups.

    Note: To have your Workplace groups display as available values when configuring provisioning, you must first refresh entitlements. To do this, in your Workplace app, go to the Provisioning tab and click Refresh.

  4. Give your rule a name.

  5. In the Conditions area, click + to add a condition. Use the fields to define a condition that defines a subset of users to be acted upon by the rule. Conditions are based on OneLogin user attribute values.

    For examples, see Rule Mapping Examples below.

  6. In the Actions area, click + to add an action. Use the fields to define the action that will be performed on users by the rule. Available actions include:

    • Create a new Workplace group and provision users to it

    • Provision users to an existing Workplace group

    For examples, see Rule Mapping Examples below.

  7. Click Save.

  8. To add another provisioning rule, click New rule.

  9. The order in which rules are applied matters and can impact provisioning results. Drag and drop the rule rows to put them in the order that produces correct results. To test results, see the next step, as well as Testing Provisioning.

  10. Click Show Affected Users to see which users will be affected by the provisioning rule as configured. Review the list to ensure that only intended users are listed.

  11. Click Save.

  12. 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!

Rule Mapping Examples

Here are some rule configuration examples that address common implementation scenarios.

Provision Members of an AD/LDAP Security Group to New Workplace Groups

To do this, define a rule mapping like this one:

CONDITIONS

For use cases like this one in which you are provisioning users to new Workplace groups, no conditions need to be set. All settings are configured in the Actions area.

ACTIONS

  1. In the first drop-down, select Set Closed Groups in Workplace by Facebook, Set Open Groups in Workplace by Facebook, or Set Secret Groups in Workplace by Facebook to provision OneLogin users to the selected group type in Workplace.

  2. Select the Map from OneLogin option to provision users to new Workplace groups created based on information in OneLogin.

  3. Select a For each value of member_of to provision users to Workplace based on their member_of user attribute value.

    The OneLogin member_of user attribute value is populated by Active Directory (AD) and reflects the user's membership in an AD/LDAP security group.

  4. To identify the AD/LDAP security groups that will be used to create groups in Workplace and provision users to them, provide a regular expression (regex) in the adjacent field.

    Provisioning will parse through AD/LDAP security group data and apply the regex. For each matching value, a group will be created in Workplace. Any users who are members of a matching AD/LDAP security group in OneLogin will be provisioned to the newly created group in Workplace.

    For key regex guidance and examples, see Using Regex to Provision Members of AD/LDAP Groups to New App Groups.

Provision Members of an AD/LDAP Security Group to an Existing Workplace Group

To do this, define a rule mapping like this one:

CONDITIONS

  1. In the first drop-down, select MemberOf to provision users based on their member_of user attribute value. The OneLogin member_of attribute value is populated by AD and reflects the user's membership in an AD/LDAP security group.

  2. Use the two adjacent fields to write a condition to select the AD/LDAP security groups that contain the users that you want to provision to Workplace.

ACTIONS

  1. In the first drop-down, select Set Closed Groups in Workplace by Facebook, Set Open Groups in Workplace by Facebook, or Set Secret Groups in Workplace by Facebook to provision users in the selected AD/LDAP security groups to the selected Workplace group type.

  2. Select the From Existing option to provision users to an existing Workplace group.

  3. Select the existing Workplace group to which you want to provision the users who are members of the selected AD/LDAP security group.

    If you selected a subset of Workplace groups on the Parameters tab as discussed in Mapping Workplace Attributes to OneLogin Attributes, only that subset of groups will be selectable here.

Testing Provisioning

Now that you've added Workplace to your OneLogin account and configured it to support user provisioning, you should test your provisioning setup with a new test user to confirm that provisioning from OneLogin to Workplace is working. We recommend that you perform this testing before you assign users to the Workplace app (on the Access tab).

  1. Create a test user.

    See Adding Users Manually.

  2. Give the user access to the Workplace app.

    See Assigning Apps to Users.

  3. Check the provisioning status indicator for Workplace on the Applications tab for the user.

    When the test user is successfully provisioned to Workplace, the provisioning indicator turns green and says "provisioned."

  4. Confirm that the test user was provisioned to Workplace with the correct attributes.

    Log in to your Workplace account as an administrator. You should see this test user in your account. You can also confirm that the test user received an invitation email from Workplace to continue their onboarding process.