Table of Content
Introduction
Account, Contacts, Users – The Basics
Individual User Provisioning
> Manual Provisioning
> Self-Registration
> API Provisioning
> Social Sign-On Provisioning
Just In Time Provisioning Over SAML
> Overview
> Enabling Provisioning Over SAML
> Useful Resources
Mass-User Provisioning
> Data Loader
> Bulk User Provisioning via API
> Using Identity Connect to Integrate With Active Directory
Introduction
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.
Account, Contacts, 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:
Create a contact record and associate it to an account.
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:
Contact associated with…
Impact on user provisioning…
Person account
Can only create customer users
Non-partner account *
Can only create customer users
Partner account *
Can create customer and partner users
* 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:
License
Permission
User can create…
Salesforce
“Manage External Users”
Users on Accounts he has read access to
Partner Community and Partner Portal
“Delegated External User Administrator”
Users on his Account
Customer Portal Manager and Customer Communities Plus
“Delegated External User Administrator”
Users on his Account
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:
Go to the Contact detail page.
Click Manage External User.
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:
On the Contact detail page, in the “Manage External User” menu, you’ll see “Enable Partner User” instead of “Enable Customer User”
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).
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 watchi 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:
Element
Unique for Manual?
Unique for SAML?
Comments
Account
Account Name
No
Yes
Account Number
No
Yes
See discussion of Account updates above
Account Owner
N/A
No
Contact
Last Name
No
No
Email
N/A
Yes
User
Last Name
No
No
Pre-populated from Contact; can be modified
Alias
No
No
Constructed from First Name and Last Name; can be modified
Email
No
No
Username
Yes
Yes
Must be in the form of an email address
Nickname
Yes
Yes
Constructed from Username; can be modified
Role
No
No
Choice is dependent on Communities -> Settings; names constructed from Account Name and one of ‘User’, ‘Manager’, ‘Executive’
Profile
No
No
Other Attributes
Federation ID
N/A
Yes
Organization_ID
N/A
No
Portal_ID
N/A
No
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.
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).
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.
If no matching Contact record is found, Salesforce searches for a matching Account by Account.Name or Account.AccountNumber.
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).
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:
Set up your Community accounts (Partner or Customer).
Add contacts to the accounts.
Create the Community Role that your Users will be using (for role-based users only).
Create a .csv import file for importing users.
Export the contacts for which you want to create users.
Add contact info to the .csv import file; complete empty fields.
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 synchrnoize 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 Connected 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