If you’re building or managing a Salesforce community, eventually you’ll need to create community users. This process is referred to as user provisioning.

In this article, we’ll explain the basic mechanics for provisioning a community user and give an overview of the different techniques available to provision users, either manually or in an automated fashion.

We are only focusing on external user provisioning (e.g.: a partner, a customer); we will not cover Salesforce user provisioning.

Provisioning Account, Contacts, and Users – The Basics

Whether you’re building a community for partners, customers, or other use cases, you must follow these steps to provision a community user:

1. Create a contact record and associate it to an account.

2. Create a user record from the contact and assign a user profile that has access to your communities.

The account type the contact is associated with determines the users you can provision:

* You convert an account into a “Partner account” by selecting “Manage External Account > Enable as Partner” on the Account Detail page.

Remember that the account used to create external users must be owned by an internal user, typically a Channel Manager. This applies to all account types.

External users can be created by Salesforce users or other external users who have delegated admin permissions as summarized in this table:

Links to articles: Creating Communities Users, Delegating External User Administration

Individual User Provisioning

Manual Provisioning

As an administrator, you may need to add a user when a new partner or customer needs access to your community.

To manually provision an external user for a Person account or non-partner account:

1. Go to the Contact detail page.

2. Click Manage External User.

3. Click Enable Customer User.

You are taken to the User detail page. Be sure to select a profile for the new user that has already been added to the community.

Click Save to create the user. If you enabled the “Welcome Email” for your community, an email with username and a link to set password is sent to this user. If the profile is associated with multiple Communities, the user receives one email per published community, but only the first email contains username and a link to set the password.

The flow to create a partner user is very similar, with two minor differences in the user interface:

1. On the Contact detail page, in the “Manage External User” menu, you’ll see “Enable Partner User” instead of “Enable Customer User”
2. On the User detail page, you must select a Role

As opposed to Customer Community users, Partner users are role-based. The role is defined at the Account level. The Partner Account can have between one and three roles (based on the org-level setting defined in Community settings). We suggest that you limit the number of roles for optimal performance.

Self-Registration

For B2C Communities, it often makes sense to let visitors self-register.

The self-registration user flow is as follows:

• The visitor clicks or gets redirected to the Self-Registration page

• The visitor fills in the form and submits his information

• Salesforce creates Contact and User records

• If the user profile has been previously added to the community, the user gets instant access to the community

• Optionally, he receives an email (option needs to be selected in setup)

Self-Registration can be set up in three steps:

1. Enable Self-Registration in the Community

Go to the Communities setup overlay, select the “Login Page” tab, and enable Self-Registration. Optionally, select a default profile to assign to self-registered users. Only profiles that were previously added to the community are shown.

2. Customize Self-Registration Code

Edit the CommunitiesSelfRegController to include the Account ID you want to associate self-registered users with. This step is mandatory.

If you’re creating a user associated to a license that does not have roles (e.g.: Customer Community), you’re done. Otherwise, you need to assign a role to the new user. Note that there’s a known issue that forces all self-registered users to be associated with the lowest role in the hierarchy.

In this example, we did not assign a profile ID to profileID because we’ve already associated a profile in the Self-Reg Communities setup. Setting a value in the controller will overwrite the default Self-Reg profile.

3. Customize Self-Registration pages

We provide a default Self-Registration page called CommunitiesSelfReg that you can customize and brand as needed.

If a user doesn’t create a password during self-registration—either because they left the password field blank or your organization customized the self-registration form to omit the password field—the CommunitiesSelfRegConfirm page and CommunitiesSelfRegConfirm controller confirm that a password reset email has been sent. Users landing on this page can’t log in until they reset their password.

API Provisioning

You can provision community users by using the SOAP or REST API on the User object. When using this API, keep in mind that the Community user has to be associated to a valid contact and account so these fields need to be set. The account must also be owned by a Salesforce user that has a role.

We also provide the following methods to provision a new user through Apex:

• createPortalUser(user, accountId, password) lets you create an external user associated to a Customer or Partner account.

• createPersonAccountPortalUser(user, ownerId, password) lets you create an external user associated to a Person Account.

Links: createPersonAccountPortalUser

Social Sign-On Provisioning

Social Sign-On enables users to authenticate from a range of identity providers, including Facebook, Google, Microsoft, Amazon, Paypal, any OpenID Connect provider, and even other salesforce.com orgs  ( future plans include support for LinkedIn and Twitter as well ). Social sign-on is key to a new way of acquiring prospects, and servicing customers.   As part of the process users are created or updated on the fly using Registration Handlers.

The best way to get started with Social Sign-On is to watch this video:

http://www.youtube.com/watch?v=D0YUTb-w1Yc&list=PLnobS_RgN7JamSA3iRTf2bY8sts_a_-ar&index=11

This reference on Registration Handlers is also useful:  https://www.salesforce.com/us/developer/docs/apexcode/Content/apex_auth_plugin.htm

Just-In-Time Provisioning over SAML

Overview

With Just-in-Time provisioning, you can use a SAML assertion to create regular and portal users on the fly the first time they try to log in. This eliminates the need to create user accounts in advance. For example, if you have a customer that needs access to your support Community, you don’t need to manually create the user in Salesforce. When they log in with single sign-on, their account is automatically created for them, eliminating the time and effort with on-boarding the account. This greatly simplifies the integration work required in scenarios where users need to be dynamically provisioned, by combining the provisioning and single sign-on processes into a single message.

Just-in-Time provisioning works with your SAML identity provider to pass the correct user information to Salesforce in a SAML 2.0 assertion attribute statement. You can both create and modify users, contacts, and accounts this way. Because Just-in-Time provisioning uses SAML to communicate, your organization must have SAML-based single sign-on enabled.

The following is a sample Attribute statement for performation provisioning over SAML

<saml:AttributeStatement>

  <saml:Attribute Name=”User.Username”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>testuser@123.org
     </saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name=”User.FirstName”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>Testuser
     </saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name=”User.LastName”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>Lee
     </saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name=”User.Email”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>testuser@salesforce.com
     </saml:AttributeValue>
  </saml:Attribute>

  <saml:Attribute Name=”User.PortalRole”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>Worker
     </saml:AttributeValue>
  </saml:Attribute>

  <saml:Attribute Name=”Account.Name”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>Customers
     </saml:AttributeValue>
  </saml:Attribute>

  <saml:Attribute Name=”Contact.Email”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>testuser@salesforce.com
     </saml:AttributeValue>
  </saml:Attribute>
  <saml:Attribute Name=”Contact.LastName”
     NameFormat=”urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified”>
     <saml:AttributeValue xsi:type=”xs:anyType”>Lee
     </saml:AttributeValue>
  </saml:Attribute>
</saml:AttributeStatement>

Enabling Provisioning over SAML

To enable Just-in-Time provisioning, you must explicitly enable the checkbox in Single Sign-On Settings.   For example:

Constucting your SAML Assertion

When constructing a SAML assertion for provisioning, you simply add a series of attributes to a normal single sign-on message.   The following provides guidance on configuring the assertion

SAML Subject

It’s required that you use Federation ID as your SAML Subject’s NameID.  This is a string of 512 characters or less that is used as an external id for your users.  It must be unique across the org, and it is case-sensitive.  It does not have to have any specific format (in particular, it does not need to be in the form of an email address).

Account Attributes

Three attributes are needed to specify a new Account record:

• Account.Name:  A string of 255 characters or less

• Account.AccountNumber:  A string of 40 characters or less (any characters, not necessarily numbers)

• Account.Owner:  A 15- or 18-character Salesforce ID for a Salesforce User record with a Role assigned to it

Some other fields can be populated on a new Account record, including AnnualRevenue, TickerSymbol, and custom fields.

Account Names and AccountNumbers must be unique.  This is not a problem if all Account records are created using SAML assertions, since an existing Account record with a matching Name and AccountNumber will be used.  However, if an Account record is manually created with the same Name and AccountNumber as an existing Account record (which can be done), then SAML authentication referencing that Account record will fail (“MULTIPLE_ACCOUNTS_FOUND” error).

Contact Attributes

Only two attributes are required to specify a new Contact:

• Contact.LastName:  A string

• Contact.Email:  A unique email address.  As noted above, this email address must be unique across all Contacts on all Accounts, even those Accounts not enabled as Partner Accounts.

Some other fields can be populated on a new Contact record, including FirstName and custom fields.

User Attributes

The following five attributes are required to specify a new User:

• User.LastName:  A string

• User.Email:  A string in the form of an email address.  This does not need to be unique.

• User.Username:  A string in the form of an email address that is unique across the org

• User.ProfileID:  The Salesforce ID string for an appropriate Profile, that is, one that uses a Partner Community license

• User.PortalRole:  One of ‘Worker’ (for the <Account Name> User Role), ‘Manager’, or ‘Executive’ (3)

(3) ‘Worker’ is the token for specifying the Community User role. User.FirstName is optional.

Limitations

JIT provisioning is currently not supported for Person Accounts. We plan to add support for this account type in the near future.

Summary

The following table summarizes the information needed for user provisioning via a SAML assertion and compares it to the information needed for manual provisioning:

Sequence of actions for JIT provisioning

As documented in this knowledge article, when provisioning over SAML, Salesforce first attempts to match the Federated ID to the Federation ID field of a User record.

1. If a User record with a matching Federation ID is found, the user is authenticated, and all of the editable User fields specified in the assertion are updated with the values assigned.  In addition, some of the Contact and Account fields can be updated (e.g., the Account.TickerSymbol field can be updated; Contact.LastName and Contact.FirstName can be updated).

2. If no matching User record is found, Salesforce searches all Contacts for a match based on Email. If a matching Contact is found, Salesforce creates the User record and updates the Contact fields specified.

3. If no matching Contact record is found, Salesforce searches for a matching Account by Account.Name or Account.AccountNumber.

4. If a matching Account record is found, Salesforce creates a new Contact on that Account with the last name and email address specified and then creates a User record with the specified fields (1).

5. If no matching Account is found, then Salesforce creates the Account with the specified Name, AccountNumber, and Owner; creates the Contact with the information specified (again, the Contact.Email attribute must be unique across all Contacts on all Accounts); and creates the User record (2).

(1) The Contact.Email attribute value must be unique across all Contact records on all Account records, or provisioning will fail.

(2) The specified Account Owner must have a Role or provisioning will fail.

Useful Resources

SSO with SAML on Force.com – Official Salesforce page

SAML configuration for Communities – See section “Security & Authentication”

JIT provisioning for Portals – Many attributes apply to Communities

JIT provisioning errors – When using AxiomSSO for provisioning (as opposed to authentication), errors show up in the returned URL

Guidelines for JIT provisioning – Helpful descriptions of provisioning for Accounts, Contacts, and Users and what happens in each case

Example SAML assertions

Mass-User Provisioning

Data Loader

Data Loader is a great option for non-developers who want to mass upload users. You can install it from here.

Follow these steps to mass upload users using Data Loader:

1. Set up your Community accounts (Partner or Customer).

2. Add contacts to the accounts.

3. Create the Community Role that your Users will be using (for role-based users only).

4. Create a .csv import file for importing users.

5. Export the contacts for which you want to create users.

6. Add contact info to the .csv import file; complete empty fields.

7. Import the .csv file through Data Loader.

Once your accounts and contacts are set up, create a .csv file with the following information to create new users:

– RoleId (optional, otherwise default to user role)

– FirstName

– LastName

– ContactId (use the contact id of previously created contact)

– ProfileId

– Username

– Email

– Alias

– TimeZoneSidKey

– LocaleSidKey

– EmailEncodingKey

– LanguageLocaleKey

You can easily find the value of the SID key fields or other standard fields by exporting an existing user record with Data Loader. Here is an example of csv file:

Username,FirstName,LastName,Email,Alias,TimeZoneSidKey,UserRoleId,LocaleSidKey,EmailEncodingKey,LanguageLocaleKey,ContactId,ProfileId

contact1@test.com,contact1,test,test@salesforce.com,cont1,America/Los_Angeles,00ED0000000k2yMMAQ,en_US,ISO-8859-1,en_US,003D000000QO2OBIA1,00eD0000000o8StIAI

Once the csv file is created, use Data Loader to upload it and create the User records.

Here is how the mapping will look in Data Loader :

Bulk User Provisioning via API

You can use the createPortalUser and createPersonAccountPortalUser methods in an Apex class to create users in bulk.

If you plan to mass provision Partner Person Accounts, be aware of this limit.

Using Identity Connect to Integrate With Active Directory

While most customers choose to store their users directly in Salesforce, some may wish to synchronize with Active Directory. While API or Bulk provisioning may be used, Salesforce also offers capabilities to synchronize with the directory via Salesforce Identity Connect.

While beyond the scope of this document, more information on Identity Connect can be found in the Identity implementation guide:

https://developer.salesforce.com/docs/atlas.en-us.identityImplGuide.meta/identityImplGuide/identity_id_connect.htm?language=en

Or in this video:  http://www.youtube.com/watch?v=fnLU0IoNwSw&list=PLnobS_RgN7JamSA3iRTf2bY8sts_a_-ar&index=9