Protect Your Salesforce Organization. salesforce Salesforce
Reklamë
Reklamë
Set Up and Maintain Your Salesforce Organization Protect Your Salesforce Organization
...it would be rewritten as
(Field 1 AND Field 3 AND Field 5 Field AND 7) OR
(Field 1 AND Field 3 AND Field 5 AND Field 8) OR
(Field 1 AND Field 3 AND Field 6 AND Field 7) OR
(Field 1 AND Field 3 AND Field 6 AND Field 8) OR
(Field 1 AND Field 4 AND Field 5 AND Field 7) OR
(Field 1 AND Field 4 AND Field 5 AND Field 8) OR
(Field 1 AND Field 4 AND Field 6 AND Field 7) OR
(Field 1 AND Field 4 AND Field 6 AND Field 8) OR
(Field 2 AND Field 3 AND Field 5 AND Field 7) OR
(Field 2 AND Field 3 AND Field 5 AND Field 8) OR
(Field 2 AND Field 3 AND Field 6 AND Field 7) OR
(Field 2 AND Field 3 AND Field 6 AND Field 8)OR
(Field 2 AND Field 4 AND Field 5 AND Field 7) OR
(Field 2 AND Field 4 AND Field 5 AND Field 8) OR
(Field 2 AND Field 4 AND Field 6 AND Field 7) OR
(Field 2 AND Field 4 AND Field 6 AND Field 8)
Although this matching rule is within the field limit, it exceeds the row limit of 10 when written in the standardized format, and therefore can’t be saved. You need to refine the matching rule so it uses fewer OR operators within groupings.
SEE ALSO:
Match Keys Used with Matching Rules
Protect Your Salesforce Organization
Salesforce is built from the ground up to protect your data and applications. You can also implement your own security scheme to reflect the structure and needs of your organization. Protecting your data is a joint responsibility between you and Salesforce. The Salesforce security features enable you to empower your users to do their jobs safely and efficiently.
IN THIS SECTION:
The Salesforce security features help you empower your users to do their jobs safely and efficiently. Salesforce limits exposure of data to the users that act on it. Implement security controls that you think are appropriate for the sensitivity of your data. We'll work together to protect your data from unauthorized access from outside your company and from inappropriate usage by your users.
Strengthen Your Data's Security with Shield Platform Encryption
Shield Platform Encryption gives your data a whole new layer of security while preserving critical platform functionality. It enables you to encrypt sensitive data at rest, and not just when transmitted over a network, so your company can confidently comply with privacy policies, regulatory requirements, and contractual obligations for handling private data.
518
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
After logging in, a user establishes a session with the platform. Use session security to limit exposure to your network when a user leaves the computer unattended while still logged in. It also limits the risk of internal attacks, such as when one employee tries to use another employee’s session. Choose from several session settings to control session behavior.
Activation tracks information about devices from which users have verified their identity. Salesforce prompts users to verify their identity when they access Salesforce from an unrecognized browser or application. Identity verification adds an extra layer of security on top of username and password authentication. The Activations page lists the login IP addresses and client browsers used.
Authentication means preventing unauthorized access to your organization or its data by making sure each logged in user is who they say they are.
Transaction Security is a framework that intercepts real-time Salesforce events and applies appropriate actions and notifications based on security policies you create. Transaction Security monitors events according to the policies that you set up. These policies are applied against events in your org and specify actions to take when certain event combinations occur. When a policy is triggered, you can have an action taken and receive an optional notification.
Single sign-on (SSO) lets users access authorized network resources with one login. You validate usernames and passwords against your corporate user database or other client app rather than Salesforce managing separate passwords for each resource.
Add a subdomain to your Salesforce org URL with the My Domain Salesforce feature. Having a subdomain lets you highlight your brand and makes your org more secure. A subdomain is convenient and allows you to personalize your login page.
The App Launcher is how users switch between apps. It displays tiles that link to a user’s available Salesforce, connected (third-party), and on-premises apps. You can determine which apps are available to which users and the order in which the apps appear. You can also make the App Launcher the default landing page when users first open Salesforce.
Configure File Upload and Download Security Settings
To provide more security, control the way some file types are handled during upload and download.
Salesforce certificates and key pairs are used for signatures that verify a request is coming from your organization. They are used for authenticated SSL communications with an external web site, or when using your organization as an Identity Provider. You only need to generate a Salesforce certificate and key pair if you're working with an external website that wants verification that a request is coming from a Salesforce organization.
Salesforce Security Basics
The Salesforce security features help you empower your users to do their jobs safely and efficiently. Salesforce limits exposure of data to the users that act on it. Implement security controls that you think are appropriate for the sensitivity of your data. We'll work together to protect your data from unauthorized access from outside your company and from inappropriate usage by your users.
519
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
IN THIS SECTION:
Trust starts with transparency. That’s why Salesforce displays real-time information on system performance and security on the trust site at http://trust.salesforce.com. This site provides live data on system performance, alerts for current and recent phishing and malware attempts, and tips on best security practices for your organization.
Salesforce utilizes some of the most advanced technology for Internet security available today. When you access the application using a Salesforce-supported browser, Transport Layer Security (TLS) technology protects your information using both server authentication and Classic Encryption, ensuring that your data is safe, secure, and available only to registered users in your organization.
As an admin, you can use Health Check to identify and fix potential vulnerabilities in your security settings, all from a single page. A summary score shows how your org measures against a security baseline, like the Salesforce Baseline Standard. You can upload up to five custom baselines to use instead of the Salesforce Baseline Standard.
Auditing provides information about use of the system, which can be critical in diagnosing potential or real security issues. The
Salesforce auditing features don't secure your organization by themselves; someone in your organization should do regular audits to detect potential abuse.
Salesforce Shield is a trio of security tools that admins and developers can use to build a new level of trust, transparency, compliance, and governance right into business-critical apps. It includes Platform Encryption, Event Monitoring, and Field Audit Trail. Ask your
Salesforce administrator if Salesforce Shield is available in your organization.
SEE ALSO:
Security Implementation Guide
Phishing and Malware
Trust starts with transparency. That’s why Salesforce displays real-time information on system performance and security on the trust site at http://trust.salesforce.com. This site provides live data on system performance, alerts for current and recent phishing and malware attempts, and tips on best security practices for your organization.
The Security tab on the trust site includes valuable information that can help you to safeguard your company's data. In particular, be on the alert for phishing and malware.
•
Phishing is a social engineering technique that attempts to acquire sensitive information such as usernames, passwords, and credit card details by masquerading as a trustworthy entity in an electronic communication. Phishers often direct users to enter details at a fake website whose URL and look-and-feel are almost identical to the legitimate one. As the Salesforce community grows, it has become an increasingly appealing target for phishers. You will never get an email or a phone call from a Salesforce employee asking you to reveal a password, so don’t reveal it to anyone. You can report any suspicious activities by clicking the Report a Suspicious
Email link under the Trust tab at http://trust.salesforce.com
.
•
Malware is software designed to infiltrate or damage a computer system without the owner's informed consent. It is a general term used to cover a variety of forms of hostile, intrusive, or annoying software, and it includes computer viruses and spyware.
What Salesforce Is Doing About Phishing and Malware
Customer security is the foundation of customer success, so Salesforce continues to implement the best possible practices and technologies in this area. Recent and ongoing actions include:
520
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
•
Actively monitoring and analyzing logs to enable proactive alerts to customers who have been affected.
•
Collaborating with leading security vendors and experts on specific threats.
•
Executing swift strategies to remove or disable fraudulent sites (often within an hour of detection).
•
Reinforcing security education and tightening access policies within Salesforce.
•
Evaluating and developing new technologies both for our customers and for deployment within our infrastructure.
What Salesforce Recommends You Do
Salesforce is committed to setting the standards in software-as-a-service as an effective partner in customer security. So, in addition to internal efforts, Salesforce strongly recommends that customers implement the following changes to enhance security:
•
Modify your Salesforce implementation to activate IP range restrictions. This allows users to access Salesforce only from your corporate
•
on page
608.
•
Educate your employees not to open suspect emails and to be vigilant in guarding against phishing attempts.
•
Use security solutions from leading vendors to deploy spam filtering and malware protection.
•
Designate a security contact within your organization so that Salesforce can more effectively communicate with you. Contact your
Salesforce representative with this information.
•
Consider using two-factor authentication techniques to restrict access to your network. For more information, see
•
Use Transaction Security to monitor events and take appropriate actions. For more information, see
on page 634.
Salesforce has a Security Incident Response Team to respond to any security issues. To report a security incident or vulnerability to
Salesforce, contact [email protected]
. Describe the issue in detail, and the team will respond promptly.
Security Infrastructure
Salesforce utilizes some of the most advanced technology for Internet security available today. When you access the application using a Salesforce-supported browser, Transport Layer Security (TLS) technology protects your information using both server authentication and Classic Encryption, ensuring that your data is safe, secure, and available only to registered users in your organization.
One of the core features of a multi-tenant platform is the use of a single pool of computing resources to service the needs of many different customers. Salesforce protects your organization's data from all other customer organizations by using a unique organization identifier, which is associated with each user's session. Once you log in to your organization, your subsequent requests are associated with your organization, using this identifier.
In addition, Salesforce is hosted in a secure server environment that uses a firewall and other advanced technology to prevent interference or access from outside intruders.
521
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
Security Health Check
As an admin, you can use Health Check to identify and fix potential vulnerabilities in your security settings, all from a single page. A summary score shows how your org measures against a security baseline, like the Salesforce Baseline Standard. You can upload up to five custom baselines to use instead of the Salesforce Baseline Standard.
From Setup, enter
Health Check
in the Quick Find box, then select Health Check.
In the baseline dropdown (1), choose the Salesforce Baseline Standard or a custom baseline. The baseline consists of recommended values for High-Risk, Medium-Risk, Low-Risk, and Informational
Security Settings (2). If you change settings to be less restrictive than what’s in the baseline, your health check score decreases.
Your settings are shown with information about how they compare against baseline values (3). To remediate a risk, edit the setting (4) or use Fix Risks (5) to quickly change settings to your selected baseline’s recommended values without leaving the Health Check page. You can import or export a custom baseline (6).
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view Health Check and export custom baselines:
•
View Health Check
To import custom baselines:
•
Manage Health Check
Example: Suppose that you changed your password minimum length from 8 (the default value) to 5, and changed other Password
Policies settings to be less restrictive. These changes make your users’ passwords more vulnerable to guessing and other brute force attacks. As a result, your overall score decreases, and the settings are listed as risks.
Fix Risks Limitations
Not all settings can be changed using the Fix Risks button. If a setting you want to adjust does not appear on the Fix Risks screen, change them manually using the Edit link on the Health Check page.
522
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
IN THIS SECTION:
How Is the Health Check Score Calculated?
The Health Check score is calculated by a proprietary formula that measures how well your security settings meet either the Salesforce
Baseline Standard or your selected custom baseline. Settings that meet or exceed compliance raise your score, and settings at risk lower your score.
Create a Custom Baseline for Health Check
You can import up to five custom baselines to compare your org’s security settings with your own standards, instead of using
Salesforce recommended standards. For example, if you’re a financial industry business, you can create a custom security baseline using FINRA standards.
Custom Baseline File Requirements
To import your Health Check custom baseline successfully, make sure that your file and settings meet the requirements.
SEE ALSO:
How Is the Health Check Score Calculated?
Security Implementation Guide
How Is the Health Check Score Calculated?
The Health Check score is calculated by a proprietary formula that measures how well your security settings meet either the Salesforce Baseline Standard or your selected custom baseline. Settings that meet or exceed compliance raise your score, and settings at risk lower your score.
There are four risk categories: High-Risk, Medium-Risk, Low-Risk, and Informational. The risk categories affect your Health Check score, with High-Risk settings counting the most, Low-Risk settings counting the least, and Medium-Risk settings, well, they’re in the middle. Settings in the Informational category do not factor into your Health Check score. For details, see
on page
524.
If all settings meet or exceed the standard, your total score is 100%. As you update your settings, your green bar moves to the right!
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
Recommended Actions Based on Your Score
If your total score is...
0–33%
34–66%
67–100%
We recommend to...
Remediate high risks immediately
Remediate high risks in the short term, and medium risks in the long term
Review Health Check periodically to remediate risks
523
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
Note: New Salesforce orgs have an initial score less than 100%. Use Health Check to quickly improve your score by eliminating high risks in your Password Policies and other setting groups.
The Salesforce Baseline Standard
The following are the settings, risk levels, and values from the default Salesforce Baseline Standard. If you are using a custom baseline, your information differs.
High Risk Security Settings
Setting Compliant Value
Lock sessions to the domain in which they were first used Checkbox selected
Enable the SMS method of identity confirmation
Enable clickjack protection for Setup pages
Checkbox selected
Checkbox selected
Enable clickjack protection for non-Setup for Salesforce pages
Checkbox selected
Enable clickjack protection for customer VisualForce pages with standard headers
Checkbox selected
Enable clickjack protection for customer VisualForce pages with headers disabled
Checkbox selected
Enable CSRF protection on GET requests on non-setup pages
Checkbox selected
Checkbox selected Enable CSRF protection on POST requests on non-setup pages
Require Secure Connections (HTTPS)
Require HttpOnly attribute
File Upload And Download Security Settings
Maximum invalid login attempts
Checkbox selected
Checkbox selected
No security risk file types have hybrid behavior enabled.
3
Warning Value
N/A
N/A
N/A
N/A
N/A
N/A
N/A
N/A
Critical Value
Checkbox deselected
Checkbox deselected
Checkbox deselected
Checkbox deselected
Checkbox deselected
Checkbox deselected
Checkbox deselected
Checkbox deselected
N/A
Checkbox deselected
Checkbox deselected
N/A
One or more security risk file types has hybrid behavior enabled.
N/A
5, 10 No Limit
Medium Risk Security Settings
Setting
Require a minimum 1 day password lifetime
Force relogin after Login-As-User
Enforce login IP ranges on every request
Administrators Can Log In As Any User
Compliant Value
Checkbox selected
Checkbox selected
Checkbox selected
Checkbox deselected
Warning Value
Checkbox deselected
N/A
Checkbox deselected
Checkbox selected
Critical Value
N/A
Checkbox deselected
N/A
N/A
524
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
Setting
Enforce password history
Minimum password length
User passwords expire in
Password complexity requirement
Compliant Value
3 or more passwords remembered
8
90 days or less
Warning Value
1 or 2 passwords remembered
6 or 7
180 days
Must mix alpha, numeric, and special characters, or more complex
Must mix alpha and numeric characters
Critical Value
No passwords remembered
5 or less
One year or Never expires
No restriction
Low Risk Security Settings
Setting
Obscure secret answer for password resets
Force logout on session timeout
Remote Site
Expiration Date
Password question requirement
Timeout Value
Lockout effective period
Compliant Value
Checkbox selected
Checkbox selected
No remote sites with the Disable Protocol
Security option selected
Warning Value
Checkbox deselected
Critical Value
N/A
Checkbox deselected N/A
At least one remote site created with the
Disable Protocol
Security option selected.
N/A
No certificates created, or all certificates have more than 180 days until expiration
Less than 180 days but more than 15 days until expiration of at least one certificate
Less than 15 days until expiration of at least one certificate
Cannot contain password
None N/A
2 hours or less
30 minutes or greater
4, 8, or 12 hours
Less than 30 minutes
Checkbox deselected
N/A
Informational Security Settings
Informational Security settings do not affect your Health Check score, but are valuable to review.
525
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
Setting
Key Size
Compliant Value
All certificates have a key size of 4096
Warning Value Critical Value
At least one certificate has a key size of 2048
N/A
SEE ALSO:
Create a Custom Baseline for Health Check
You can import up to five custom baselines to compare your org’s security settings with your own standards, instead of using Salesforce recommended standards. For example, if you’re a financial industry business, you can create a custom security baseline using FINRA standards.
To create a custom baseline, start with the Salesforce Baseline Standard.
EDITIONS
Available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
1. Export the Salesforce Baseline Standard file by selecting Export XML from the Baseline Controls menu.
USER PERMISSIONS
To view a custom baseline
•
View Health Check
To create a custom baseline
•
Manage Health Check
2. Open the XML file, and change the developerName
field to a unique value. You can use letters and numbers, but the name must begin with a letter. It cannot contain spaces or special characters.
3. Change the name
field from “SFDC Recommended” to a descriptive value. This field is the baseline name that displays in Salesforce.
Spaces and some special characters are allowed. If the name
field contains “SFDC recommended” or “Salesforce Baseline Standard,” your file fails to import.
4. Adjust the risk categories to customize your scoring. The risk category that each setting is in impacts your Health Check score. A setting in a higher risk category is weighted as more important than a lower one. Moving a setting to the Informational category removes it from the Health Check score calculation.
5. Modify the settings values by following the Custom Baseline File Requirements. Not all values can be changed, and some settings have restricted value options. Do not add or delete risk categories, setting names, or quotation marks. If you do, your import fails.
Note: In some security settings, a low value could be low risk, but in others, it could be high risk. For example, the lower your minimum password length value is, the riskier it is. But the lower your maximum invalid login attempts value is, the safer it is.
526
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
6. Save your file, and import it by choosing Import XML from the Baseline Controls menu.
Note: Unexpected information in the XML file causes the import to fail. If your import fails, you receive a detailed message to help resolve the problem. See Custom Baseline File Requirements in Salesforce Help for troubleshooting assistance.
7. To confirm that your file uploaded, click the baseline dropdown and select your file.
SEE ALSO:
Custom Baseline File Requirements
How Is the Health Check Score Calculated?
Custom Baseline File Requirements
To import your Health Check custom baseline successfully, make sure that your file and settings meet the requirements.
EDITIONS
XML File
Available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
Use a valid XML file, with only English language characters. The file cannot be larger than 20 KB.
Each custom baseline requires a unique Developer Name field value. As a best practice, make the
Name field value unique, because it’s the field you use to differentiate baselines on Salesforce. If
“SFDC recommended”or “Salesforce Baseline Standard” is in the Name field, your file doesn’t import. Surround each value in quotation marks, and be careful not to delete any of them when editing the file.
Custom Baseline Security Setting Fields and Values
You cannot add or delete the Health Check settings from the file, but you can change their risks and values.
There are four risk categories: High-Risk, Medium-Risk, Low-Risk, and Informational. The risk categories affect your Health Check score, with High-Risk settings counting the most, Low-Risk settings counting the least, and Medium-Risk settings, well, they’re in the middle.
You can move settings into any risk category. Settings in the Informational category do not factor into your Health Check score, so move settings that are unnecessary to your org to this category rather than deleting them.
Each security setting shows in Health Check as either compliant, warning, or critical. These statuses guide you to make your org more secure. Assign values to each status in the import file.
There are three setting types: boolean, numeric range, and enum. The values you can assign to each setting depend on the setting type.
Boolean Security Settings
527
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
Boolean settings have two attributes—compliant and noncompliant. Compliant values correspond to checkboxes in security settings.
A Boolean value of
“true”
indicates selecting the checkbox, and
“false”
represents deselecting it. Noncompliant attributes can take either warning
or critical
values.
Important:
You cannot change boolean compliant values in Health Check, although you can change noncompliant values.
Setting
LoginAccessPolicies.adminLoginAsAnyUser
SessionSettings.clickjackSetup
SessionSettings.clickjackNonSetup
SessionSettings.clickjackVisualForceHeaders
SessionSettings.clickjackVisualForceNoHeaders
SessionSettings.csrfGet
SessionSettings.csrfPost
SessionSettings.enableSmsIdentity
SessionSettings.enforceLoginIp
SessionSettings.forceLogoutOnTimeout
SessionSettings.forceRelogin
SessionSettings.lockSessionsToDomain
Accepted Values
•
“false”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”— noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
528
Set Up and Maintain Your Salesforce Organization
Setting
SessionSettings.requireSecureConnections
SessionSettings.requireHttpOnly
PasswordPolicies.minOneDayPasswordLifetime
PasswordPolicies.obscureSecretAnswer
Salesforce Security Basics
Accepted Values
•
“true”—compliant
•
“warning” or “critical”—noncompliant
•
“true”— compliant
•
“warning” or “critical”— noncompliant
•
“true”— compliant
•
“warning” or “critical”— noncompliant
•
“true”—compliant
•
“warning” or “critical”—noncompliant
Numeric Range Security Settings
Numeric range values are positive integers extended to one decimal place. You provide compliant and warning values only for numeric range settings. Critical values are assumed based on the other values in the settings. Each setting has specific validation rules, so enter only acceptable values.
Setting
PasswordPolicies.history
CertificateAndKeyManagement.certExpiration
Compliant Value
Any integer between “0.0” and “24.0”
Warning Value
Any integer between “0.0” and “24.0” that is less than the compliant value
Note: Any value less than the warning value shows as critical
Number of days—Any integer between “0.0” and
“180.0”
Any integer between “0.0” and “180.0” that is less than the compliant value
Note:
Any value less than the warning value shows as critical
FileUploadAndDownloadSecurity.hybridSecurityRiskFileTypes
Any integer “0.0” or greater Any integer greater than the compliant value
Note: Any value greater than the warning value shows as critical
CertificateAndKeyManagement.keySize
“4096.0” or “2048.0” “4096.0” or “2048.0”
Note: To not allow the 2048 key size, enter a compliant value of
“4096.0” and a warning value of any number between “2048.0” and
“4096.0”.
529
Set Up and Maintain Your Salesforce Organization
Setting
PasswordPolicies.minPasswordLength
RemoteSiteSettings.remoteSiteSettings
Salesforce Security Basics
Compliant Value
Any integer between “5.0” and “50.0”
Warning Value
Any integer between “5.0” and “50.0” that is less than the compliant value
Note:
Any value less than the warning value shows as critical
Maximum number of remote site settings allowed—Any integer greater than “0.0”
Any integer greater than the compliant value
Note: Any value greater than the warning value shows as critical
Enum Security Settings
Enum values allow you to choose between provided string texts. Use all the possible values, and decide whether they are compliant, warning, or critical status. Enum values are case-sensitive. You can assign multiple enum names to one status by separating them with commas, for example, compliant="FifteenMinutes,ThirtyMinutes,SixtyMinutes,TwoHours".
As long as all values are used, you can leave a status empty. For example, you could have all the values split between compliant and critical and leave warning empty: warning=“”
. Do not leave the compliant status empty.
Important: Use every accepted value in each setting. If a value is missing, the file doesn’t import.
Setting
PasswordPolicies.complexity
PasswordPolicies.expiration
PasswordPolicies.lockoutInterval
PasswordPolicies.maxLoginAttempts
Accepted Values
•
“UpperLowerCaseNumericSpecialCharacters”
•
“UpperLowerCaseNumeric”
•
“SpecialCharacters”
•
“AlphaNumeric”
•
“NoRestriction” (highest risk)
•
“ThirtyDays”
•
“SixtyDays”
•
“NinetyDays”
•
“SixMonths”
•
“OneYear”
•
“Never” (highest risk)
•
“Forever” (admin must reset)
•
“SixtyMinutes”
•
“ThirtyMinutes”
•
“FifteenMinutes” (highest risk)
•
“ThreeAttempts”
530
Set Up and Maintain Your Salesforce Organization
Setting
PasswordPolicies.questionRestriction
SessionSettings.timeout
Accepted Values
•
“FiveAttempts”
•
“TenAttempts”
•
“NoLimit” (highest risk)
•
“DoesNotContainPassword”
•
“None” (highest risk)
•
“FifteenMinutes”
•
“ThirtyMinutes”
•
“SixtyMinutes”
•
“TwoHours”
•
“FourHours”
•
“EightHours”
•
“TwelveHours”
•
“TwentyFourHours” (highest risk)
Salesforce Security Basics
531
Set Up and Maintain Your Salesforce Organization
Example:
Salesforce Security Basics
SEE ALSO:
Create a Custom Baseline for Health Check
Auditing
Auditing provides information about use of the system, which can be critical in diagnosing potential or real security issues. The Salesforce auditing features don't secure your organization by themselves; someone in your organization should do regular audits to detect potential abuse.
To verify that your system is actually secure, you should perform audits to monitor for unexpected changes or usage trends.
532
Set Up and Maintain Your Salesforce Organization Salesforce Security Basics
Record Modification Fields
All objects include fields to store the name of the user who created the record and who last modified the record. This provides some basic auditing information.
Login History
on page 778.
Field History Tracking
You can also enable auditing for individual fields, which will automatically track any changes in the values of selected fields. Although
789.
Setup Audit Trail
Administrators can also view a Setup Audit Trail, which logs when modifications are made to your organization’s configuration. See
on page 786.
Salesforce Shield
Salesforce Shield is a trio of security tools that admins and developers can use to build a new level of trust, transparency, compliance, and governance right into business-critical apps. It includes Platform Encryption, Event Monitoring, and Field Audit Trail. Ask your
Salesforce administrator if Salesforce Shield is available in your organization.
Platform Encryption
Platform Encryption allows you to natively encrypt your most sensitive data at rest across all your Salesforce apps. This helps you protect
PII, sensitive, confidential, or proprietary data and meet both external and internal data compliance policies while keeping critical app functionality — like search, workflow, and validation rules. You keep full control over encryption keys and can set encrypted data
permissions to protect sensitive data from unauthorized users. See Platform Encryption.
Event Monitoring
Event Monitoring gives you access to detailed performance, security, and usage data on all your Salesforce apps. Every interaction is tracked and accessible via API, so you can view it in the data visualization app of your choice. See who is accessing critical business data when, and from where. Understand user adoption across your apps. Troubleshoot and optimize performance to improve end-user experience. Event Monitoring data can be easily imported into any data visualization or application monitoring tool like Wave Analytics,
Splunk, or New Relic. To get started, check out our Event Monitoring training course.
Field Audit Trail
Field Audit Trail lets you know the state and value of your data for any date, at any time. You can use it for regulatory compliance, internal governance, audit, or customer service. Built on a big data backend for massive scalability, Field Audit Trail helps companies create a
533
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Strengthen Your Data's Security with Shield Platform Encryption
Shield Platform Encryption gives your data a whole new layer of security while preserving critical platform functionality. It enables you to encrypt sensitive data at rest, and not just when transmitted over a network, so your company can confidently comply with privacy policies, regulatory requirements, and contractual obligations for handling private data.
Shield Platform Encryption builds on the data encryption options that Salesforce offers out of the box. Data stored in many standard and custom fields and in files and attachments is encrypted using an advanced HSM-based key derivation system, so it is protected even when other lines of defense have been compromised.
Your data encryption key is never saved or shared across organizations. Instead, it is derived on demand from a master secret and your organization-specific tenant secret, and cached on an application server.
You can try out Shield Platform Encryption at no charge in Developer Edition orgs. It is available in sandboxes after it has been provisioned for your production org.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
IN THIS SECTION:
Specify the fields and files you want to encrypt. Remember that encryption is not the same thing as field-level security or object-level security. Those should already be in place before you implement your encryption strategy.
Manage Shield Platform Encryption
To provide Shield Platform Encryption for your organization, contact your Salesforce account executive. They’ll help you provision the correct license so you can get started on creating your own unique tenant secret.
How Shield Platform Encryption Works
Shield Platform Encryption relies on a unique tenant secret that you control and a master secret that's maintained by Salesforce. We combine these secrets to create your unique data encryption key. We use that key to encrypt data that your users put into Salesforce, and to decrypt data when your authorized users need it.
Platform Encryption Best Practices
Take the time to identify the most likely threats to your organization. This will help you distinguish data that needs encryption from data that doesn’t, so that you can encrypt only what you need to. Make sure that your tenant secret and keys are backed up, and be careful who you allow to manage your secrets and keys.
Tradeoffs and Limitations of Shield Platform Encryption
A security solution as powerful as Shield Platform Encryption doesn't come without some tradeoffs. When your data is encrypted, some users may see limitations to some functionality, and a few features aren't available at all. Consider the impact on your users and your overall business solution as you design your encryption strategy.
SEE ALSO:
Salesforce Platform Encryption Implementation Guide
What’s the Difference Between Classic Encryption and Shield Platform Encryption?
Salesforce Platform Encryption Architecture
534
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Encrypt Fields and Files
Specify the fields and files you want to encrypt. Remember that encryption is not the same thing as field-level security or object-level security. Those should already be in place before you implement your encryption strategy.
EDITIONS
IN THIS SECTION:
Select the fields you want to encrypt. For best results, encrypt the smallest possible number of fields.
For another layer of data protection, encrypt files and attachments. If Shield Platform Encryption is on, the body of each file or attachment is encrypted when it’s uploaded.
When you select fields or files to encrypt, Salesforce automatically checks for potential side effects and warns you if any existing settings may pose a risk to data access or your normal use of Salesforce. You have some options for how to clear up these problems.
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Retrieve Encrypted Data with Formulas
Use custom formula fields to quickly find encrypted data. You can write formulas with several operators and functions, render encrypted data in text, date, and date/time formats, and reference quick actions.
Encrypt Data in Chatter (Pilot)
Enabling Shield Platform Encryption for Chatter adds an extra layer of security to information that users share in Chatter. You can encrypt data at rest in feed posts, questions and answers, link names and URLs, comments, and poll questions and choices.
SEE ALSO:
535
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Encrypt Fields
Select the fields you want to encrypt. For best results, encrypt the smallest possible number of fields.
Depending on the size of your organization, enabling a standard field for encryption can take a few minutes.
1. Make sure that your organization has an active encryption key. If you’re not sure, check with your administrator.
2. From Setup, use the
Quick Find
box to find the Platform Encryption setup page.
3. Click Encrypt Fields.
4. Click Edit.
5. Select the fields you want to encrypt, and save your settings.
The automatic Platform Encryption validation service will now check for settings in your organization that might block encryption. You’ll receive an email with suggestions for fixing any incompatible settings.
Field values are automatically encrypted only in records created or updated after you’ve enabled encryption. Salesforce recommends updating existing records to ensure that their field values are encrypted. For example, if you encrypt the
Description
field on the Case object, use the Data
Loader to update all case records. Contact Salesforce if you need help with this.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To view setup:
•
View Setup and
Configuration
To encrypt fields:
•
Customize Application
SEE ALSO:
Field Limits with Shield Platform Encryption
Why Isn’t All of My Encrypted Data Masked?
API Guide: CustomField
Retrieve Encrypted Data with Formulas
536
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Encrypt Files and Attachments
For another layer of data protection, encrypt files and attachments. If Shield Platform Encryption is on, the body of each file or attachment is encrypted when it’s uploaded.
Note: Before you begin, make sure that your organization has an active encryption key; if you’re not sure, check with your administrator.
1. From Setup, enter
Platform Encryption
in the
Quick Find
box, then select
Platform Encryption.
2. Select Encrypt Files and Attachments.
3. Click Save.
Important: Users with access to the file can work normally with it regardless of their encryption-specific permissions. Users who are logged in to your org and have read access can search and view the body content.
Users can continue to upload files and attachments per the usual file size limits. Expansion of file sizes caused by encryption doesn’t count against these limits.
Turning on file and attachment encryption affects new files and attachments. It doesn’t automatically encrypt files and attachments that were already in Salesforce. To encrypt existing files, contact
Salesforce.
To check whether a file or attachment is encrypted, look for the encryption indicator on the detail page of the file or attachment. You can also query the isEncrypted
field on the ContentVersion object (for files) or on the Attachment object (for attachments).
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To view setup:
•
View Setup and
Configuration
To encrypt files:
•
Customize Application
Here’s What It Looks Like When a File Is Encrypted.
SEE ALSO:
The ContentVersion object
API Guide: Attachment
537
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Fix Compatibility Problems
When you select fields or files to encrypt, Salesforce automatically checks for potential side effects and warns you if any existing settings may pose a risk to data access or your normal use of Salesforce.
You have some options for how to clear up these problems.
EDITIONS
If your results include error messages, you're probably running into one or more of these limitations:
Portals
You can’t encrypt standard fields, because a customer portal or a partner portal is enabled in your organization. To deactivate a customer portal, go to the Customer Portal Settings page in
Setup. To deactivate a partner portal, go to the Partners page in Setup.
Note: Communities are not related to this issue. They are fully compatible with encryption.
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Criteria-Based Sharing Rules
You’ve selected a field that is used in a filter in a criteria-based sharing rule.
SOQL/SOSL queries
You’ve selected a field that’s used in an aggregate function in a SOQL query, or in a WHERE,
GROUP BY, or ORDER BY clause.
Available in both Salesforce
Classic and Lightning
Experience.
Formula fields
You’ve selected a field that’s referenced by a custom formula field in an unsupported way. Formulas can use BLANKVALUE, CASE,
HYPERLINK, IF, IMAGE, ISBLANK, ISNULL, and NULLVALUE, as well as concatenation (&).
Skinny tables
You’ve selected a field that's used in a skinny table.
Flows and Processes (Beta)
You’ve selected a field that’s used in one of these contexts.
•
To filter data in a flow
•
To sort data in a flow
•
To filter data in a process
•
To filter data in a dynamic record choice
•
To sort data in a dynamic record choice
Note: By default, your results only list the first 250 errors per element. You can increase the number of errors listed in your results to 5000. Contact Salesforce for help.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
538
Set Up and Maintain Your Salesforce Organization
Supported Operators, Functions, and Actions
Supported operators and functions:
•
&
and
+
(concatenate)
•
BLANKVALUE
•
CASE
•
HYPERLINK
•
IF
•
IMAGE
•
ISBLANK
•
ISNULL
•
NULLVALUE
Also supported:
•
Spanning
•
Quick actions
Formulas can return data only in text
, date
, or date/time
formats.
Strengthen Your Data's Security with Shield Platform
Encryption
Retrieve Encrypted Data with Formulas
Use custom formula fields to quickly find encrypted data. You can write formulas with several operators and functions, render encrypted data in text, date, and date/time formats, and reference quick actions.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
&
And
+
(Concatenate)
This works:
(encryptedField__c & encryptedField__c)
Why it works:
This doesn’t work:
This works because
&
is supported.
Why it doesn’t work:
LOWER(encryptedField__c & encryptedField__c)
LOWER
isn’t a supported function, and the input is an encrypted value.
Case
CASE
returns encrypted field values, but doesn’t compare them.
This works:
Why it works:
CASE(custom_field__c, "1", cf2__c, cf3__c)) where either or both cf2__c
and cf3__c
are encrypted custom_field__c
is compared to “1”. If it is true, the formula returns cf2__c
because it’s not comparing two encrypted values.
539
Set Up and Maintain Your Salesforce Organization
This doesn’t work:
Why it doesn’t work:
CASE("1", cf1__c, cf2__c, cf3__c) where cf1__c
is encrypted
You can’t compare encrypted values.
Strengthen Your Data's Security with Shield Platform
Encryption
ISBLANK
and
ISNULL
This works:
Why it works:
OR(ISBLANK(encryptedField__c), ISNULL(encryptedField__c))
Both
ISBLANK
and
ISNULL
are supported.
OR
works in this example because
ISBLANK
and
ISNULL
return a Boolean value, not an encrypted value.
Spanning
This works:
How and why you use it:
(LookupObject1__r.City & LookupObject1__r.Street) &
(LookupObject2__r.City & LookupObject2__r.Street) &
(LookupObject3__r.City & LookupObject3__r.Street) &
(LookupObject4__r.City & LookupObject4__r.Street)
Spanning retrieves encrypted data from multiple entities. For example, let’s say you work in the customer service department for Universal Containers. A customer has filed a case about a distribution problem, and you want to see the scope of the issue. You want all the shipping addresses related to this particular case. This example returns all the customers’ shipping addresses as a single string in your case layout.
Validation
The encryption validation service checks your org to make sure that it’s compatible with encrypted formula field types.
When you encrypt a given field, the validation service:
•
Retrieves all formula fields that reference the field
•
Verifies that the formula fields are compatible with encryption
•
Verifies that the formula fields aren’t used elsewhere for filtering or sorting
Limits
Up to 200 formula fields can reference a given encrypted custom field. A field that is referenced by more than 200 formula fields can’t be encrypted. If you need to reference an encrypted custom field from more than 200 formula fields, contact Salesforce.
When you specify multiple fields to encrypt at one time, the 200-field limit is applied to the whole batch. If you know that you are encrypting fields that have multiple formula fields pointing to them, encrypt those fields one at a time.
540
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Important: Beginning in Spring ’17, Shield Platform Encryption no longer masks encrypted data. To get the most out of encryption support for custom formula field types, we recommend that you approve the “Turn Off Masking for Encrypted Data” critical update.
To activate this critical update:
1. Review your field-level security settings for any field types that include encrypted data. Ensure that field access is properly set in your org.
2. From Setup, enter
Critical Updates
in the
Quick Find
box and select Critical Updates.
3. For Turn Off Masking for Encrypted Data, click Activate.
4. Refresh your browser page.
Encrypt Data in Chatter (Pilot)
Enabling Shield Platform Encryption for Chatter adds an extra layer of security to information that users share in Chatter. You can encrypt data at rest in feed posts, questions and answers, link names and URLs, comments, and poll questions and choices.
Note: We provide encryption for Chatter to selected customers through a pilot program that requires agreement to specific terms and conditions. To be nominated to participate in the program, contact Salesforce. Pilot programs are subject to change, and we can’t guarantee acceptance. Encryption for Chatter isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for encryption for Chatter in the Chatter Product group in the
Success Community.
We recommend that you implement encryption for Chatter in a dedicated Sandbox environment.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Unlike encryption for custom and standard fields, enabling encryption for Chatter encrypts all eligible Chatter fields.
1. To enable access to this feature, first contact Salesforce.
2. Assign all users in your org the View Encrypted Data permission.
3. Make sure that your org has an active encryption key. If you’re not sure, check with your administrator.
USER PERMISSIONS
To view setup:
•
View Setup and
Configuration
To encrypt fields:
•
Customize Application
4. From Setup, use the Quick Find box to find the Platform Encryption setup page.
5. Click Encrypt Chatter.
The automatic Shield Platform Encryption validation service checks for settings that could block encryption. If the service finds potential problems, you’re sent an email with suggestions for fixing the problems.
After you activate encryption for Chatter, new data that you enter into Chatter gets encrypted. Existing data is not encrypted.
Mass-encryption for historic Chatter data isn’t available. To encrypt existing data, simply edit or update the data in any supported field.
When you edit or update an encrypted Chatter field, the field’s revision history is also encrypted. For example, if you update a post, the old version of the post remains encrypted.
If you enabled Encryption for Chatter in Spring ’17 and you want to access the most up-to-date features for this pilot, deselect Encrypt
Chatter and then reselect Encrypt Chatter.
541
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Note: Beginning with Spring ’17, Shield Platform Encryption no longer masks encrypted data in the presentation layer. This may
on page 298, record access settings, and object permissions on page 301.
Manage Shield Platform Encryption
To provide Shield Platform Encryption for your organization, contact your Salesforce account executive. They’ll help you provision the correct license so you can get started on creating your own unique tenant secret.
Assign the Manage Encryption Keys, Manage Certificates, and Customize Application permissions to people you trust to manage tenant secrets and certificates. Users with the Manage Encryption
Keys permission can generate, export, import, and destroy organization-specific keys. It's a good idea to monitor the key management activities of these users regularly with the setup audit trail.
Users with both Manage Certificates and Manage Encryption Keys permissions can manage certificates and tenant secrets with the Shield Platform Encryption Bring Your Own Key (BYOK) service. You can also monitor these users’ key and certificate management activities with the setup audit trail.
Authorized developers can generate, rotate, export, destroy, and reimport tenant secrets by coding a call to the TenantSecret object in the Salesforce API.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
IN THIS SECTION:
USER PERMISSIONS
You can have Salesforce generate a unique tenant secret for your organization, or you can generate your own tenant secret using your own external resources. In either case, you manage your own tenant secret: you can rotate it, archive it, and designate other users to share responsibility for it.
To manage tenant secrets:
•
Manage Encryption Keys
Rotate Your Encryption Tenant Secrets
You control the life cycle of your data encryption keys by controlling the life cycle of your tenant secrets. It’s recommended to regularly generate a new tenant secret and archive the previously active one.
Your tenant secret is unique to your organization and to the specific data to which it applies. Salesforce recommends that you export your secret to ensure continued data access in cases where you need to gain access to the related data again.
Only destroy tenant secrets in extreme cases where access to related data is no longer needed. Your tenant secret is unique to your organization and to the specific data to which it applies. Once you destroy a tenant secret, related data is not accessible unless you previously exported the key and then import the key back into Salesforce.
Turn Shield Platform Encryption Off
At some point, you may need to disable Shield Platform Encryption for fields, files, or both. You can turn field encryption on or off individually, but file encryption is all or nothing.
SEE ALSO:
Tenant Secret API
542
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Generate a Tenant Secret
You can have Salesforce generate a unique tenant secret for your organization, or you can generate your own tenant secret using your own external resources. In either case, you manage your own tenant secret: you can rotate it, archive it, and designate other users to share responsibility for it.
When you generate a new tenant secret, any new data is encrypted using this key. However, existing sensitive data remains encrypted using previous keys. In this situation, we strongly recommend re-encrypting these fields using the latest key. Contact Salesforce for help with this.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
IN THIS SECTION:
Generate a Tenant Secret with Salesforce
Salesforce makes it easy to generate a unique tenant secret from the Setup menu.
Available in both Salesforce
Classic and Lightning
Experience.
Tenant secret types allow you to specify which kind of data you want to encrypt with a tenant secret. You can apply different key rotation cycles or key destruction policies to tenant secrets that encrypt different kinds of data. You can apply a tenant secret to search index files or other data stored in Salesforce.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
Generate Your Own Tenant Secret (BYOK)
When you supply your own tenant secret, you get the benefits of built-in Salesforce Shield
Platform Encryption plus the extra assurance that comes from exclusively managing your tenant secret.
SEE ALSO:
API Guide: TenantSecret
543
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Generate a Tenant Secret with Salesforce
Salesforce makes it easy to generate a unique tenant secret from the Setup menu.
Only authorized users can generate tenant secrets from the Platform Encryption page. Ask your
Salesforce admin to assign you the Manage Encryption Keys permission.
1. From Setup, enter
Platform Encryption
in the
Quick Find
box and select Platform
Encryption.
2. In the Choose Tenant Secret Type drop-down list, choose a data type.
3. Click Generate Tenant Secret.
How often you can generate a tenant secret depends on the tenant secret type.
•
You can generate tenant secrets for the Data in Salesforce type once every 24 hours in production orgs, and once every 4 hours in Sandbox orgs.
•
You can generate tenant secrets for the Search Index type once every 7 days.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
Manage Tenant Secrets by Type
Tenant secret types allow you to specify which kind of data you want to encrypt with a tenant secret. You can apply different key rotation cycles or key destruction policies to tenant secrets that encrypt different kinds of data. You can apply a tenant secret to search index files or other data stored in Salesforce.
Tenant secrets are categorized according to the kind of data they encrypt.
•
Data in Salesforce, which includes fields, attachments, and files other than search index files
•
Search index files
Note: Tenant secrets that were generated or uploaded before the Spring ’17 release are categorized as the Data in Salesforce type.
1. From Setup, enter
Platform Encryption
in the
Quick Find
box and select Platform
Encryption.
2. In the Choose Tenant Secret Type drop-down list, choose a data type.
The Key Management section displays all tenant secrets of that data type. If you generate or upload a tenant secret while viewing tenant secrets of a particular type, it becomes the active tenant secret for that data.
To enable search index encryption, contact your Salesforce account executive or open a support ticket.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Certificates
AND
Manage Encryption Keys
544
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Generate Your Own Tenant Secret (BYOK)
When you supply your own tenant secret, you get the benefits of built-in Salesforce Shield Platform
Encryption plus the extra assurance that comes from exclusively managing your tenant secret.
Controlling your own tenant secret entails generating a BYOK-compatible certificate, using that certificate to encrypt and secure your self-generated tenant secret, then granting the Salesforce
Shield Platform Encryption key management machinery access to your tenant secret.
EDITIONS
IN THIS SECTION:
1.
Generate a BYOK-Compatible Certificate
Use Salesforce to generate a certificate to encrypt the tenant secret that we’ll use to derive your org-specific data encryption key. You can generate a self-signed or certificate-authority (CA) signed certificate.
2.
Generate and Wrap Your Tenant Secret
Generate a random number as your tenant secret. Then calculate an SHA256 hash of the secret, and encrypt it with the public key from the certificate you generated.
3.
Once you have your tenant secret, upload it to Salesforce so that the Shield Platform Encryption key management machinery can use it to derive your org-specific data encryption key.
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
AND
Manage Certificates
Generate a BYOK-Compatible Certificate
Use Salesforce to generate a certificate to encrypt the tenant secret that we’ll use to derive your org-specific data encryption key. You can generate a self-signed or certificate-authority (CA) signed certificate.
To create a self-signed certificate:
1. In Setup, use the Quick Find box to go to the Platform Encryption page.
2. Click Upload Tenant Secret.
3. Click Create Self-Signed Certificate.
4. Enter a unique name for your certificate in the Label field. The Unique Name field to automatically assign a name based on what you entered in the Label field.
The Exportable Private Key, Use Platform Encryption, and Key Size settings are pre-selected.
This ensures that your self-signed certificate is compatible with Salesforce Shield Platform
Encryption.
Important: You can also create a BYOK-compatible self-signed certificate from the
Certificate and Key Management page. If you chose this option, you must 1) disable
Exportable Private Key, 2) specify a 4096-bit certificate size, and 3) enable Platform
Encryption.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
AND
Manage Certificates
545
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
5. When the Certificate and Key Detail page appears, click Download Certificate.
If you’re not sure whether a self-signed or CA-signed certificate is right for you, consult your organization’s security policy. See
Certificates and Keys in Salesforce Help for more about what each option implies.
To create a CA-signed certificate, follow the instructions in the Generate a Certificate Signed By a Certificate Authority topic in
Salesforce Help. Remember to manually change the Exportable Private Key, Key Size, and Platform Encryption settings to ensure that your certificate is BYOK-compatible.
SEE ALSO:
Generate a Certificate Signed by a Certificate Authority
Generate and Wrap Your Tenant Secret
Generate a random number as your tenant secret. Then calculate an SHA256 hash of the secret, and encrypt it with the public key from the certificate you generated.
1. Generate a 256-bit tenant secret using the method of your choice.
You can generate your tenant secret in one of two ways:
•
Use your own on-premise resources to generate a tenant secret programmatically, using an open source library such as Bouncy Castle or OpenSSL.
Tip:
We've provided a script on page 556 that may be useful as a guide to the process.
•
Use a key brokering partner that can generate, secure, and share access to your tenant secret.
2. Wrap your tenant secret with the public key from the BYOK-compatible certificate you generated.
Specify the OAEP padding scheme. Make sure the resulting encrypted tenant secret and hashed tenant secret files are encoded using base64.
3. Encode this encrypted tenant secret to base64.
4. Calculate an SHA-256 hash of the plaintext tenant secret.
5. Encode the SHA-256 hash of the plaintext tenant secret to base64.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
AND
Manage Certificates
546
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Upload Your Tenant Secret
Once you have your tenant secret, upload it to Salesforce so that the Shield Platform Encryption key management machinery can use it to derive your org-specific data encryption key.
1. In Setup, use the Quick Find box to go to the Platform Encryption setup page.
2. Click Upload Tenant Secret.
3. In the Upload Tenant Secret section, attach both the encrypted tenant secret and the hashed plaintext tenant secret. Click Upload.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
This tenant secret automatically becomes the active tenant secret.
Note: The tenant secret whose certificate has the latest expiration date automatically becomes the active tenant secret.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
AND
Manage Certificates
Your tenant secret is now ready to be used for key derivation. From here on, the Salesforce key derivation server will use the tenant secret you generated to derive the org-specific key that the app server will use to encrypt and decrypt your users’ data.
4. Export your tenant secret and back it up as prescribed in your organization’s security policy.
You’ll have to reimport the secret if you need to restore it. The exported secret is different from the key you uploaded. It is encrypted with a different key and has additional metadata embedded in it. See Back Up Your Tenant Secret in the Salesforce Help.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
547
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Rotate Your Encryption Tenant Secrets
You control the life cycle of your data encryption keys by controlling the life cycle of your tenant secrets. It’s recommended to regularly generate a new tenant secret and archive the previously active one.
Consult your organization’s security policies to decide how often to rotate your tenant secrets. You can rotate a tenant secret once every 24 hours in production orgs and every 4 hours in sandbox environments.
The key derivation function uses a master secret, which is rotated with each major Salesforce release.
Master secret rotation doesn’t impact your encryption keys or your encrypted data until you rotate your tenant secret.
1. From Setup, enter
Platform Encryption
in the Quick Find box, then click Platform
Encryption.
2. From the Choose Tenant Secret Type dropdown, choose a data type.
3. Check the status of the data type’s tenant secrets. Existing tenant secrets are listed as active, archived, or destroyed.
ACTIVE
Can be used to encrypt and decrypt new or existing data.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
ARCHIVED
Can’t encrypt new data. Can be used to decrypt data previously encrypted with this key when it was active.
To manage tenant secrets:
•
Manage Encryption Keys
DESTROYED
Can’t encrypt or decrypt data. Data encrypted with this key when it was active can no longer be decrypted. Files and attachments encrypted with this key can no longer be downloaded.
4. Click Generate New Tenant Secret or Upload Tenant Secret. If uploading a customer-supplied tenant secret, upload your encrypted tenant secret and tenant secret hash.
5. If you want to re-encrypt field values with a newly generated tenant secret, contact Salesforce support.
To update your data, export the objects via the API or run a report that includes the record ID. These actions trigger the encryption service to encrypt the existing data again using the newest key.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
API Guide: TenantSecret
548
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Back Up Your Tenant Secret
Your tenant secret is unique to your organization and to the specific data to which it applies.
Salesforce recommends that you export your secret to ensure continued data access in cases where you need to gain access to the related data again.
1. In Setup, use the
Quick Find
box to find the Platform Encryption setup page.
2. In the table that lists your keys, find the tenant secret you want and click Export.
3. Confirm your choice in the warning box, then save your exported file.
The file name is tenant-secret-org-<organization ID>-ver-<tenant secret version numer>.txt
. For example, tenant-secret-org-00DD00000007eTR-ver-1.txt
.
4. Note the specific version you’re exporting, and give the exported file a meaningful name. Store the file in a safe location in case you need to import it back into your organization.
Note: Your exported tenant secret is itself encrypted.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
5. To import your tenant secret again, click Import > Choose File and select your file. Make sure you’re importing the correct version of the tenant secret.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
SEE ALSO:
API Guide: TenantSecret
Destroy A Tenant Secret
Only destroy tenant secrets in extreme cases where access to related data is no longer needed.
Your tenant secret is unique to your organization and to the specific data to which it applies. Once you destroy a tenant secret, related data is not accessible unless you previously exported the key and then import the key back into Salesforce.
You are solely responsible for making sure your data and tenant secrets are backed up and stored in a safe place. Salesforce can’t help you with deleted, destroyed, or misplaced tenant secrets.
1. In Setup, use the
Quick Find
box to find the Platform Encryption setup page.
2. In the table that lists your tenant secrets, go to the row that contains the one you want to destroy and click Destroy.
3. A warning box appears. Type in the text as shown and select the checkbox acknowledging that you’re destroying a tenant secret, then click Destroy.
File previews and content that was already cached in the user’s browser may still be visible in cleartext after you destroy the key that encrypted that content, until the user logs in again.
If you create a sandbox organization from your production organization and then destroy the tenant secret in your sandbox organization, the tenant secret still exists in the production organization.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To manage tenant secrets:
•
Manage Encryption Keys
549
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
API Guide: TenantSecret
Turn Shield Platform Encryption Off
At some point, you may need to disable Shield Platform Encryption for fields, files, or both. You can turn field encryption on or off individually, but file encryption is all or nothing.
When you turn off Shield Platform Encryption, encrypted data is not mass-decrypted and any functionality that is affected by encryption is not restored. Contact Salesforce after disabling Platform
Encryption for help finalizing your changes.
1. From Setup, use the
Quick Find
box to find Platform Encryption.
2. Click Encrypt Fields, then click Edit.
3. Deselect the fields you want to stop encrypting, then click Save.
Users can see data in these fields.
4. To disable encryption for files, deselect Encrypt Files and Attachments and click Save.
The limitations and special behaviors that apply to encrypted fields persist after encryption is disabled. Any previously encrypted files and attachments may remain encrypted at rest.
Encrypted fields remain accessible after you disable encryption, as long as the key used to encrypt them has not been destroyed.
SEE ALSO:
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
USER PERMISSIONS
To view setup:
•
View Setup and
Configuration
To disable encryption:
•
Customize Application
How Shield Platform Encryption Works
Shield Platform Encryption relies on a unique tenant secret that you control and a master secret that's maintained by Salesforce. We combine these secrets to create your unique data encryption key. We use that key to encrypt data that your users put into Salesforce, and to decrypt data when your authorized users need it.
Encrypting files, fields, and attachments has no effect on your organization’s storage limits.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
IN THIS SECTION:
Shield Platform Encryption allows you to encrypt a wide variety of standard fields and custom fields. You can also encrypt files and attachments stored in Salesforce, as well as Salesforce search indexes.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
550
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Can I Bring My Own Encryption Key?
Yes. You can generate and store your tenant secret outside of Salesforce using your own crypto libraries, enterprise key management system, or hardware security module (HSM). You then grant the Salesforce Shield Platform Encryption key management machinery access to those keys. You can choose to encrypt your keys with a public key from a self-signed or CA-signed certificate.
Which User Permissions Does Shield Platform Encryption Require?
Assign permissions to your users according to their roles regarding encryption and key management. Some users need permission to select data for encryption, while other users require combinations of permissions to work with certificates or tenant secrets. You can enable these permissions for user profiles just like you would any other user permission.
Why Isn’t All of My Encrypted Data Masked?
Shield Platform Encryption uses masking only in specific circumstances. Specifically, masked characters are used to help you troubleshoot encryption key issues. If the encryption service isn’t available, data in specific encrypted fields are also masked. If you have data that you don’t want users to see, revisit those users’ field-level security settings, record access settings, and object permissions.
Behind the Scenes: The Shield Platform Encryption Process
When users submit data, the application server looks for the org-specific data encryption key in its cache. If it isn’t there, the application server gets the encrypted tenant secret from the database and asks the key derivation server to derive the key. The encryption service then encrypts the data on the application server.
Behind the Scenes: The Search Index Encryption Process
The Salesforce search engine is built on the open-source enterprise search platform software Apache Solr. The search index, which stores tokens of record data with links back to the original records stored in the database, is housed within Solr. Partitions divide the search index into segments to allow Salesforce to scale operations. Apache Lucene is used for its core library.
How Do I Deploy Shield Platform Encryption?
When you deploy Shield Platform Encryption to your organization with a tool such as Force.com IDE, Migration Tool, or Workbench, the Encrypted field attribute persists. However, if you deploy to organizations with different encryption settings, the effect depends on whether Shield Platform Encryption is enabled in the target organization.
How Does Shield Platform Encryption Work In a Sandbox?
Refreshing a sandbox from a production organization creates an exact copy of the production organization. If Shield Platform
Encryption is enabled on the production organization, all encryption settings are copied, including tenant secrets created in production.
Shield Platform Encryption Terminology
Encryption has its own specialized vocabulary. To get the most out of your Shield Platform Encryption features, it’s a good idea to familiarize yourself with the key terms, such as hardware security module, key rotation, and master secret.
What’s the Difference Between Classic Encryption and Shield Platform Encryption?
With Shield Platform Encryption, you can encrypt a variety of widely used standard fields, along with some custom fields and many kinds of files. Shield Platform Encryption also supports person accounts, cases, search, approval processes, and other key Salesforce features. Classic encryption lets you protect only a special type of custom text field, which you create for that purpose.
SEE ALSO:
https://resources.docs.salesforce.com/202/latest/en-us/sfdc/pdf/salesforce_platform_encryption_implementation_guide.pdf
What Gets Encrypted?
Shield Platform Encryption allows you to encrypt a wide variety of standard fields and custom fields. You can also encrypt files and attachments stored in Salesforce, as well as Salesforce search indexes.
551
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
IN THIS SECTION:
Which Standard Fields Can Be Encrypted?
You can encrypt certain fields on standard objects, on custom objects, and in Chatter. With some exceptions, encrypted fields work normally throughout the Salesforce user interface, business processes, and APIs.
Which Custom Fields Can Be Encrypted?
You can encrypt the contents of fields that belong to one these custom field types, on either standard or custom objects.
When you enable Shield Platform Encryption for files and attachments, all files and attachments that can be encrypted are encrypted.
The body of each file or attachment is encrypted when it’s uploaded.
Which Standard Fields Can Be Encrypted?
You can encrypt certain fields on standard objects, on custom objects, and in Chatter. With some exceptions, encrypted fields work normally throughout the Salesforce user interface, business processes, and APIs.
Note: Beginning with Spring ’17, Shield Platform Encryption no longer masks encrypted data in the presentation layer. This may
on page 298, record access settings, and object permissions on page 301.
When you encrypt a field, existing values aren't encrypted immediately. Values are encrypted only after they are touched. Contact
Salesforce for help encrypting existing data.
Encrypted Standard Fields
You can encrypt the contents of these standard field types on the Account, Contact, Case, Case Comment, and Lead objects.
Accounts (Business)
•
Account Name
•
Billing
•
Description
•
Fax
•
Website
•
Phone
•
Shipping
(encrypts
Street
and
City
)
•
Site
Person Accounts
•
Name
(Encrypts
First Name
,
Middle Name
, and
Last Name
)
•
Mailing City
Contacts
•
Assistant
•
Description
•
•
Fax
•
Home Phone
•
Mailing Address
(Encrypts
Mailing Street
and
Mailing City
)
552
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
•
Mobile
•
Name
(Encrypts
First Name
,
Middle Name
, and
Last Name
)
•
Other Address (encrypts Street and City)
•
Other Phone
•
Phone
•
Title
Cases
•
Subject
•
Description
Case Comments
•
Body
(including Internal Comments)
Leads (Beta)
•
Address
(Encrypts
Street
and
City
)
•
Company
•
Description
•
•
Fax
•
Mobile Phone
•
Name
(Encrypts
First Name
,
Middle Name
, and
Last Name
)
•
Phone
•
Other Phone
•
Title
•
Website
Chatter feed
•
Feed Comment—Body
•
Feed Item—Body
•
Feed Item—Title
•
Feed Revision—Value
These Chatter fields include feed posts, questions and answers, link names, comments, and poll questions. They don’t encrypt poll choices.
The revision history of encrypted Chatter fields is also encrypted. If you edit or update an encrypted Chatter field, the old information remains encrypted.
Note: Enabling Encryption for Chatter encrypts all eligible Chatter fields. You can’t choose to encrypt only certain Chatter fields.
Which Custom Fields Can Be Encrypted?
You can encrypt the contents of fields that belong to one these custom field types, on either standard or custom objects.
•
•
Phone
553
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
•
Text
•
Text Area
•
Text Area (Long)
•
URL
•
Date
•
Date/Time
After a custom field is encrypted, you can’t change the field type. For custom phone and email fields, you also can’t change the field format.
Important:
When you encrypt the Name field, enhanced lookups are automatically enabled. Enhanced lookups improve the user’s experience by searching only through records that have been looked up recently, and not all existing records. Switching to enhanced lookups is a one-way change. You can’t go back to standard lookups, even if you disable encryption.
You can’t use Schema Builder to create an encrypted custom field.
Some custom fields can’t be encrypted:
•
Fields that have the
Unique
or
External ID
attributes or include these attributes on previously encrypted custom fields
•
Fields on external data objects
•
Fields that are used in an account contact relation
On a custom object, the standard Name field can't be encrypted.
Which Files Are Encrypted?
When you enable Shield Platform Encryption for files and attachments, all files and attachments that can be encrypted are encrypted. The body of each file or attachment is encrypted when it’s uploaded.
These kinds of files are encrypted when you enable file encryption:
•
Files attached to email
•
Files attached to feeds
•
Files attached to records
•
Images included in Rich Text Area fields
•
Files on the Content, Libraries, and Files tabs (Salesforce Files, including file previews, and
Salesforce CRM Content files)
•
Files managed with Salesforce Files Sync and stored in Salesforce
•
Files attached to Chatter posts, comments, and the sidebar
•
Notes body text using the new Notes tool
•
Files attached to Knowledge articles
•
Quote PDFs
EDITIONS
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
SEE ALSO:
554
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Can I Bring My Own Encryption Key?
Yes. You can generate and store your tenant secret outside of Salesforce using your own crypto libraries, enterprise key management system, or hardware security module (HSM). You then grant the Salesforce Shield Platform Encryption key management machinery access to those keys. You can choose to encrypt your keys with a public key from a self-signed or CA-signed certificate.
To work with our key management machinery, your tenant secret needs to meet these specifications:
•
256-bit size
•
Encrypted with a public RSA key that is extracted from the downloaded BYOK certificate, then padded using OAEP padding
•
Once it’s encrypted, it must be encoded in standard base64
To work with encryption keys, you'll need the “Manage Encryption Keys” permission. To generate
BYOK-compatible certificates, you’ll need the “Customize Application” permission.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
IN THIS SECTION:
Bring Your Own Key (BYOK) gives you an extra layer of protection in the event of unauthorized access to critical data. It may also help you meet the regulatory requirements that come with handling financial data, such as credit card numbers; health data, such as patient care records or insurance information; or other kinds of private data, such as social security numbers, addresses, and phone numbers. Once you’ve set up your key, you can use Shield Platform Encryption as you normally would to encrypt data at rest in your
Salesforce org.
When you create and store your own key material outside of Salesforce, it’s important that you safeguard those tenant secrets. Make sure that you have a trustworthy place to archive your tenant secret; never save a tenant secret on a hard drive without a backup.
Sample Script for Generating a BYOK Tenant Secret
We’ve provided a helper script that may be handy for preparing your tenant secret for installation. It generates a random number as your tenant secret, calculates a SHA256 hash of the secret, and uses the public key from the certificate to encrypt the secret.
Troubleshooting Bring Your Own Key
One or more of these frequently asked questions may help you troubleshoot any problems that arise.
Why Bring Your Own Key?
Bring Your Own Key (BYOK) gives you an extra layer of protection in the event of unauthorized access to critical data. It may also help you meet the regulatory requirements that come with handling financial data, such as credit card numbers; health data, such as patient care records or insurance information; or other kinds of private data, such as social security numbers, addresses, and phone numbers. Once you’ve set up your key, you can use Shield Platform Encryption as you normally would to encrypt data at rest in your Salesforce org.
Shield Platform Encryption enables Salesforce administrators to manage the lifecycle of their data encryption keys while protecting these keys from unauthorized access. By controlling the lifecycle of your organization’s tenant secrets, you control the lifecycle of the data encryption keys derived from them.
Data encryption keys aren’t stored in Salesforce. Instead, they’re derived on demand whenever a key is needed to encrypt or decrypt customer data, using a master secret and a tenant secret. The
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
555
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption master secret is generated once per release for everyone by a hardware security module (HSM). The tenant secret is unique to your organization, and you control when it is generated, activated, and retired.
You can generate your tenant secrets in two ways:
•
Use the Salesforce hardware security module (HSM) key management infrastructure to have your org-specific tenant secret generated for you.
•
Use the infrastructure of your choice, such as an on-premise HSM, to generate and manage your tenant secret. This option is popularly known as “Bring Your Own Key,” although the element you’re really bringing is the tenant secret from which the key is derived.
Take Good Care of Your Keys
When you create and store your own key material outside of Salesforce, it’s important that you safeguard those tenant secrets. Make sure that you have a trustworthy place to archive your tenant secret; never save a tenant secret on a hard drive without a backup.
Back up all imported tenant secrets after you upload them to Salesforce to ensure that you have copies of your active tenant secrets. See Back Up Your Tenant Secret in the Salesforce Help.
Review your company policy on key rotation. You can rotate and update your keys on your own schedule. See Rotate Your Encryption Keys .
Important:
If you accidentally destroy a tenant secret that isn't backed up, Salesforce won’t be able to help you retrieve it.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Sample Script for Generating a BYOK Tenant Secret
We’ve provided a helper script that may be handy for preparing your tenant secret for installation.
It generates a random number as your tenant secret, calculates a SHA256 hash of the secret, and uses the public key from the certificate to encrypt the secret.
1. Download the script from the Salesforce Knowledge Base . Save it in the same directory as the certificate.
2. Run the script specifying the certificate name, like this:
./secretgen.sh
my_certificate.crt
Replace this certificate name with the actual filename of the certificate you downloaded.
Tip: If needed, use chmod +w secretgen.sh
to make sure you have write permission to the file and use chmod 775
to make it executable.
3. The script generates a number of files. Look for the two files that end with the .b64 suffix.
The files ending in .b64 are your base 64-encoded encrypted tenant secret and base 64-encoded hash of the plaintext tenant secret. You’ll need both of these files for the next step.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
556
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Troubleshooting Bring Your Own Key
One or more of these frequently asked questions may help you troubleshoot any problems that arise.
EDITIONS
I’m trying to use the script you provide, but it won’t run.
Make sure that you are running the right script for your operating system. If you are working on a Windows machine, you can install a Linux emulator and use the Linux script. These issues can also prevent the script from running:
•
You don’t have write permission in the folder you’re trying to run the script from. Try running the script from a folder that you have write permission for.
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
•
The certificate that the script references is missing. Make sure you’ve properly generated the certificate.
•
The certificate is missing or is not being referenced by the correct name. Make sure you’ve entered the correct file name for your certificate in the script.
Available in both Salesforce
Classic and Lightning
Experience.
I want to use the script you provide, but I also want to use my own random number generator.
The script we provide uses a random number generator to create a random value that is then used as your tenant secret. If you would like to use a different generator, replace head -c 32 /dev/urandom | tr '\n'
=
(or, in the Mac version, head -c 32 /dev/urandom > $PLAINTEXT_SECRET
) with a command that generates a random number using your preferred generator.
What if I want to use my own hashing process to hash my tenant secret?
No problem. Just make sure that the end result meets these requirements:
•
Uses an SHA-256 algorithm.
•
Results in a base64 encoded hashed tenant secret.
•
Generates the hash of the random number BEFORE encrypting it.
If any of these three criteria aren’t met, you won’t be able to upload your tenant secret.
How should I encrypt my tenant secret before I upload it to Salesforce?
If you’re using the script provided, the encryption process is taken care of. If you do not use the script, specify the OAEP padding scheme when you encrypt your tenant secret. Make sure the resulting encrypted tenant secret and hashed tenant secret files are encoded using base64. If either of these criteria are not met, you won’t be able to upload your tenant secret.
If you choose to not use the script provided, follow the instructions in the Generate And Wrap Your Tenant Secret Help topic.
I can’t upload my Encrypted tenant secret and Hashed tenant secret.
A handful of errors can prevent your files from uploading. Use the chart to make that sure your tenant secrets and certificates are in order.
Possible cause Solution
Your files were generated with an expired certificate.
Check the date on your certificate. If it has expired, you can renew your certificate or use another one.
Your certificate is not active, or is not a valid Bring Your Own Key certificate.
Ensure that your certificate settings are compatible with the Bring Your Own Key feature. Under the Certificate and Key Edit section of the Certificates page, select a 4096-bit certificate size, disable Exportable Private Key, and enable Platform Encryption.
You haven’t attached both the encrypted tenant secret and the hashed tenant secret.
Make sure that you attach both the encrypted tenant secret and hashed tenant secret. Both of these files should have a .b64 suffix.
557
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Possible cause
Your tenant secret or hashed tenant secret wasn’t generated properly.
Solution
Several problems can cause this error. Usually, the tenant secret or hashed tenant secret wasn't generated using the correct SSL parameters. If you are using OpenSSL, you can refer to the script for an example of the correct parameters you should use to generate and hash your tenant secret. If you are using a library other than OpenSSL, check that library's support page for help finding the correct parameters to both generate and hash your tenant secret.
Still stuck? Contact your Salesforce account executive. They'll put you in touch with someone at Salesforce who can help.
I’m still having problems with my key. Who should I talk to?
If you still have questions, contact your account executive. They’ll put you in touch with a support team specific to this feature.
Which User Permissions Does Shield Platform Encryption Require?
Assign permissions to your users according to their roles regarding encryption and key management.
Some users need permission to select data for encryption, while other users require combinations of permissions to work with certificates or tenant secrets. You can enable these permissions for user profiles just like you would any other user permission.
Manage
Encryption
Keys
Customize
Application
View
Setup and
Configuration
Manage
Certificates
View Platform Encryption Setup page
Edit Platform Encryption setup Page, excluding tenant secret and certificate management
Generate, destroy, export, and import tenant secrets
Query TenantSecret object via the API
Edit, upload, and download
HSM-protected certificates with the
Shield Platform Encryption Bring Your
Own Key service
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
The Customize Application and Manage Certificates permissions are automatically enabled for users with the System Administrator profile.
Note: Beginning with Spring ’17, Shield Platform Encryption no longer masks encrypted data in the presentation layer. This may
on page 298, record access settings, and object permissions on page 301.
558
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
Why Isn’t All of My Encrypted Data Masked?
Shield Platform Encryption uses masking only in specific circumstances. Specifically, masked characters are used to help you troubleshoot encryption key issues. If the encryption service isn’t available, data in specific encrypted fields are also masked. If you have data that you don’t want users to see, revisit those users’ field-level security settings, record access settings, and object permissions.
Encryption prevents outsiders from using your Salesforce data even if they manage to get it. It is not a way to hide data from authenticated users. User permissions are the only way to control data visibility for authenticated users. Encryption at rest is about logins, not permissions.
With Shield Platform Encryption, if a user is authorized to see a given set of data, that user sees that data whether it’s encrypted or not.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
•
Authentication means that making sure only legitimate users can get into your system. For example, a company’s Salesforce org is only for use by active employees of that company.
Anyone who is not an employee is not authenticated; that is, they are barred from logging in.
If they do somehow get their hands on the data, it’s useless to them because it is encrypted.
Available in both Salesforce
Classic and Lightning
Experience.
•
Authorization defines which data or features an authenticated user can use. For example, a sales associate can see and use data in the Leads object, but can’t see the regional forecasts, which are intended for sales managers.
Both the associate and the manager are properly logged in (authenticated), but their permissions (authorization) are different. That the data is encrypted doesn’t make any difference to them.
In general, data can be masked but not encrypted, or encrypted but not masked. For example, regulators often require that only the last four digits of a credit card number be visible to users. Applications typically mask the rest of the number, meaning they replace the digits with asterisks on the user’s screen. Without encryption, you can still read the digits that are masked if you can get to the database where they are stored.
Masking might not be enough for your credit card numbers. You may or may not want to encrypt them in the database as well. (You probably should.) If you do, authenticated users will still see the same masked values.
In this way, masking and encryption are different solutions for different problems. You mask data to hide it from users who are authenticated but not authorized to see that data. You encrypt data to prevent someone from stealing the data. (Or, more precisely, to make the data useless if someone does steal it.)
The following table shows the fields that use masking. All others don’t.
Field Type
Email, Phone, Text, Text Area,
Text Area (Long), URL
Mask
?????
What It Means
This field is encrypted, and the encryption key has been destroyed.
559
Set Up and Maintain Your Salesforce Organization
Field Type
Custom Date
Custom Date/Time
Mask
!!!!!
08/08/1888
01/01/1777
08/08/1888 12:00 PM
01/01/1777 12:00 PM
Strengthen Your Data's Security with Shield Platform
Encryption
What It Means
This service is unavailable right now. For help accessing this service, contact Salesforce.
This field is encrypted, and the encryption key has been destroyed.
This service is unavailable right now. For help accessing this service, contact Salesforce.
This field is encrypted, and the encryption key has been destroyed.
This service is unavailable right now. For help accessing this service, contact Salesforce.
You can’t enter these masking characters into an encrypted field. For example, if a Date field is encrypted and you enter 07/07/1777, you must enter a different value before it can be saved.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
Behind the Scenes: The Shield Platform Encryption Process
When users submit data, the application server looks for the org-specific data encryption key in its cache. If it isn’t there, the application server gets the encrypted tenant secret from the database and asks the key derivation server to derive the key. The encryption service then encrypts the data on the application server.
Salesforce securely generates the master and tenant secrets by using Hardware Security Modules
(HSMs). The unique key is derived by using PBKDF2, a Key Derivation Function (KDF), with the master and tenant secrets as inputs.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
560
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Shield Platform Encryption Process Flow
1. When a Salesforce user saves encrypted data, the runtime engine determines from metadata whether to encrypt the field, file, or attachment before storing it in the database.
2. If so, the encryption service checks for the matching data encryption key in cached memory.
3. The encryption service determines whether the key exists.
a. If so, the encryption service retrieves the key.
b. If not, the service sends a derivation request to a key derivation server and returns it to the encryption service running on the
Salesforce Platform.
4. After retrieving or deriving the key, the encryption service generates a random initialization vector (IV) and encrypts the data using
256-bit AES encryption.
5. The ciphertext is saved in the database or file storage. The IV and corresponding ID of the tenant secret used to derive the data encryption key are saved in the database.
Salesforce generates a new master secret at the start of each release.
SEE ALSO:
Shield Platform Encryption Terminology
Salesforce Platform Encryption Architecture
Video: Shield Platform Encryption (Lightning Experience)
561
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Behind the Scenes: The Search Index Encryption Process
The Salesforce search engine is built on the open-source enterprise search platform software Apache
Solr. The search index, which stores tokens of record data with links back to the original records stored in the database, is housed within Solr. Partitions divide the search index into segments to allow Salesforce to scale operations. Apache Lucene is used for its core library.
Note: Open a support ticket to enable Search Index Encryption.
Leveraging Shield Platform Encryption’s HSM-based key derivation architecture, metadata, and configurations, Search Index Encryption runs when Shield Platform Encryption is in use. The solution applies strong encryption on an org-specific search index (.fdt, .tim, and .tip file types) using an org-specific AES-256 bit encryption key. The search index is encrypted at the search index segment level, and all search index operations require index blocks to be encrypted in memory.
There aren’t any changes in Setup or changes to the user interface, so the added protection is seamless and determined by the organization’s encryption policy.
The only way to access the search index or the key cache is through programmatic APIs.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Before the search index files are encrypted, a Salesforce security administrator must enable Search
Index Encryption. Admins then set up their encryption policy to determine which data elements need to be embedded with encryption.
Admins configure Shield Platform Encryption by selecting fields and files to encrypt. An org-specific HSM-derived key specifically for search index encryption is derived on-demand from the tenant secret. The key material is passed to the search engine’s cache on a secure channel.
The process when a user creates or edits records:
1. The core application determines if the search index segment should be encrypted or not based on metadata.
2. If the search index segment should be encrypted, the encryption service checks for the matching search encryption key ID in the cached memory.
3. The encryption service determines if the key exists in the cache.
a. If the key exists in the cache, the encryption service uses the key for encryption.
b. Otherwise, the service sends a request to the core application, which in turn sends an authenticated derivation request to a key derivation server and returns the key to the core application server.
4. After retrieving the key, the encryption service generates a random initialization vector (IV) and encrypts the data using NSS or JCE’s
AES-256 implementation.
5. The key ID (identifier of the key being used to encrypt the index segment) and IV are saved in the search index.
The process is similar when a user searches for encrypted data:
1. When a user searches for a term, the term is passed to the search index, along with which Salesforce objects to search.
2. When the search index executes the search, the encryption service opens the relevant segment of the search index in memory and reads the key ID and IV.
3. Steps 3 through 5 of the process when a user creates or edits records are repeated.
4. The search index processes the search and returns the results to the user seamlessly.
If Salesforce admins disable encryption on a field, all index segments that were encrypted are unencrypted and the key ID is set to null.
This process can take up to seven days.
562
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
How Do I Deploy Shield Platform Encryption?
When you deploy Shield Platform Encryption to your organization with a tool such as Force.com
IDE, Migration Tool, or Workbench, the Encrypted field attribute persists. However, if you deploy to organizations with different encryption settings, the effect depends on whether Shield Platform
Encryption is enabled in the target organization.
You can use change sets to deploy Shield Platform Encryption to custom fields. Regardless of how you deploy, Salesforce automatically checks to see if the implementation violates Shield Platform
Encryption guidelines.
Source Organization
Shield Platform Encryption enabled
Shield Platform Encryption enabled
Target Organization
Shield Platform Encryption enabled
Result
The source Encrypted field attribute indicates enablement
Shield Platform Encryption not enabled
The Encrypted field attribute is ignored
Shield Platform Encryption not enabled
Shield Platform Encryption enabled
The target Encrypted field attribute indicates enablement
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
How Does Shield Platform Encryption Work In a Sandbox?
Refreshing a sandbox from a production organization creates an exact copy of the production organization. If Shield Platform Encryption is enabled on the production organization, all encryption settings are copied, including tenant secrets created in production.
Once a sandbox is refreshed, tenant secret changes are confined to your current organization. This means that when you rotate or destroy a tenant secret on sandbox, it doesn’t affect the production organization.
As a best practice, rotate tenant secrets on sandboxes after a refresh. Rotation ensures that production and sandbox use different tenant secrets. Destroying tenant secrets on a sandbox renders encrypted data unusable in cases of partial or full copies.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
563
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Shield Platform Encryption Terminology
Encryption has its own specialized vocabulary. To get the most out of your Shield Platform Encryption features, it’s a good idea to familiarize yourself with the key terms, such as hardware security module, key rotation, and master secret.
EDITIONS
Data Encryption
The process of applying a cryptographic function to data that results in ciphertext. The platform encryption process uses symmetric key encryption and a 256-bit Advanced Encryption Standard
(AES) algorithm using CBC mode, PKCS5 padding, and a randomized, 128-bit initialization vector
(IV) to encrypt field-level data and files stored on the Salesforce platform. Both data encryption and decryption occur on the application servers.
Data Encryption Keys
Shield Platform Encryption uses data encryption keys to encrypt and decrypt data. Data encryption keys are derived on a key derivation server using keying material split between a per-release master secret and an organization-specific tenant secret stored encrypted in the database as a part of your organization. The 256-bit derived keys exist in memory until evicted from the cache.
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Encrypted Data at Rest
Data that is encrypted when stored on disk. Salesforce supports encryption for fields stored in the database, documents stored in
Files, Content Libraries, and Attachments, and archived data.
Encryption Key Management
Refers to all aspects of key management, such as key creation, processes, and storage. Tenant secret management is performed by administrators or users who have the “Manage Encryption Keys” permission.
Hardware Security Module (HSM)
Used to provide cryptography processing as well as key management for authentication. Shield Platform Encryption uses HSMs to generate and store secret material and run the function that derives data encryption keys used by the encryption service to encrypt and decrypt data.
Initialization Vector (IV)
A random sequence used with a key to encrypt data.
Key Derivation Function (KDF)
Uses a pseudorandom number generator and input such as a password to derive keys. Shield Platform Encryption uses PBKDF2
(Password-based Key Derivation Function 2) with HMAC-SHA-256.
Key (Tenant Secret) Rotation
The process of generating a new tenant secret and archiving the previously active one. Active tenant secrets are used for both encryption and decryption. Archived ones are used only for decryption until all data has been re-encrypted using the new, active tenant secret.
Master HSM
The master HSM consists of a USB device used to generate secure, random secrets each Salesforce release. The master HSM is
“air-gapped” from Salesforce’s production network and stored securely in a bank safety deposit box.
Master Secret
Used in conjunction with the tenant secret and key derivation function to generate a derived data encryption key. The master secret is updated each release by Salesforce and encrypted using the per-release master wrapping key, which is in turn encrypted with the
Key Derivation Servers’ public key so it can be stored encrypted on the file system. Only HSMs can decrypt it. No Salesforce employees
have access to these keys in cleartext.
564
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Master Wrapping Key
A symmetric key is derived and used as a master wrapping key, also known as a key wrapping key, encrypting all the per-release keys and secrets bundle.
Tenant Secret
An organization-specific secret used in conjunction with the master secret and key derivation function to generate a derived data encryption key. When an organization administrator rotates a key, a new tenant secret is generated. To access the tenant secret via the API, refer to the TenantSecret object. No Salesforce employees have access to these keys in cleartext.
SEE ALSO:
Behind the Scenes: The Shield Platform Encryption Process
Platform Encryption White Paper
What’s the Difference Between Classic Encryption and Shield Platform Encryption?
With Shield Platform Encryption, you can encrypt a variety of widely used standard fields, along with some custom fields and many kinds of files. Shield Platform Encryption also supports person accounts, cases, search, approval processes, and other key Salesforce features. Classic encryption lets you protect only a special type of custom text field, which you create for that purpose.
EDITIONS
Pricing
Encryption at Rest
Feature Classic Encryption
Included in base user license
Platform Encryption
Additional fee applies
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Native Solution (No Hardware or Software
Required)
Encryption Algorithm
Available in both Salesforce
Classic and Lightning
Experience.
128-bit Advanced
Encryption Standard
(AES)
256-bit Advanced
Encryption Standard
(AES)
HSM-based Key Derivation
Manage Encryption Keys Permission
Generate, Export, Import, and Destroy Keys
PCI-DSS L1 Compliance
Masking
Mask Types and Characters
View Encrypted Data Permission Required to Read Encrypted Field Values
Encrypted Standard Fields
Encrypted Attachments, Files, and Content
565
Set Up and Maintain Your Salesforce Organization
Encrypted Custom Fields
Feature
Encrypt Existing Fields for Supported Custom Field Types
Search (UI, Partial Search, Lookups, Certain SOSL Queries)
API Access
Available in Workflow Rules and Workflow Field Updates
Available in Approval Process Entry Criteria and Approval Step
Criteria
Strengthen Your Data's Security with Shield Platform
Encryption
Platform Encryption Classic Encryption
Dedicated custom field type, limited to 175 characters
Note: Beginning with Spring ’17, Shield Platform Encryption no longer masks encrypted data in the presentation layer. This may
on page 298, record access settings, and object permissions on page 301.
SEE ALSO:
Strengthen Your Data's Security with Shield Platform Encryption
Strengthen Your Data's Security with Shield Platform Encryption
Platform Encryption Best Practices
Take the time to identify the most likely threats to your organization. This will help you distinguish data that needs encryption from data that doesn’t, so that you can encrypt only what you need to.
Make sure that your tenant secret and keys are backed up, and be careful who you allow to manage your secrets and keys.
Note: Beginning with Spring ’17, Shield Platform Encryption no longer masks encrypted data in the presentation layer. This may affect some users’ ability to work with encrypted data.
If you have data you don’t want specific users to see, revisit their field-level security settings
on page 298, record access settings, and object permissions
1. Define a threat model for your organization.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Walk through a formal threat modeling exercise to identify the threats that are most likely to affect your organization. Use your findings to create a data classification scheme, which can help you decide what data to encrypt.
Available in both Salesforce
Classic and Lightning
Experience.
2. Encrypt only where necessary.
•
Not all data is sensitive. Focus on information that requires encryption to meet your regulatory, security, compliance, and privacy requirements. Unnecessarily encrypting data impacts functionality and performance.
566
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
•
Evaluate your data classification scheme early and work with stakeholders in security, compliance, and business IT departments to define requirements. Balance business-critical functionality against security and risk measures and challenge your assumptions periodically.
3. Create a strategy early for backing up and archiving keys and data.
If your tenant secrets are destroyed, reimport them to access your data. You are solely responsible for making sure that your data and tenant secrets are backed up and stored in a safe place. Salesforce cannot help you with deleted, destroyed, or misplaced tenant secrets.
4. Read the Shield Platform Encryption considerations and understand their implications on your organization.
•
Evaluate the impact of the considerations on your business solution and implementation.
•
Test Shield Platform Encryption in a sandbox environment before deploying to a production environment.
•
Before enabling encryption, fix any violations that you uncover. For example, referencing encrypted fields in a SOQL WHERE clause triggers a violation. Similarly, if you reference encrypted fields in a SOQL ORDER BY clause, a violation occurs. In both cases, fix the violation by removing references to the encrypted fields.
5. Analyze and test AppExchange apps before deploying them.
•
If you use an app from the AppExchange, test how it interacts with encrypted data in your organization and evaluate whether its functionality is affected.
•
If an app interacts with encrypted data that's stored outside of Salesforce, investigate how and where data processing occurs and how information is protected.
•
If you suspect Shield Platform Encryption could affect the functionality of an app, ask the provider for help with evaluation. Also discuss any custom solutions that must be compatible with Shield Platform Encryption.
•
Apps on the AppExchange that are built exclusively using Force.com inherit Shield Platform Encryption capabilities and limitations.
6. Platform Encryption is not a user authentication or authorization tool. Use field-level security settings, page layout settings, and validation rules, not Platform Encryption, to control which users can see which data.
7. Grant the “Manage Encryption Keys” user permission to authorized users only.
Users with the “Manage Encryption Keys” permission can generate, export, import, and destroy organization-specific keys. Monitor the key management activities of these users regularly with the setup audit trail.
8. Mass-encrypt your existing data.
Existing field and file data is not automatically encrypted when you turn on Shield Platform Encryption. To encrypt existing field data, update the records associated with the field data. This action triggers encryption for these records so that your existing data is encrypted at rest. To encrypt existing files, contact Salesforce.
9. Don't use Currency and Number fields for sensitive data.
You can often keep private, sensitive, or regulated data safe without encrypting associated
Currency
or
Number
fields. Encrypting these fields could have broad functional consequences across the platform, such as disruptions to roll-up summary reports, report timeframes, and calculations, so they are not encryptable.
10. Communicate to your users about the impact of encryption.
Before you enable Shield Platform Encryption in a production environment, inform users about how it affects your business solution.
For example, share the information described in Shield Platform Encryption considerations, where it's relevant to your business processes.
11. Encrypt your data using the most current key.
567
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
When you generate a new tenant secret, any new data is encrypted using this key. However, existing sensitive data remains encrypted using previous keys. In this situation, Salesforce strongly recommends re-encrypting these fields using the latest key. Contact Salesforce for help with this.
SEE ALSO:
https://resources.docs.salesforce.com/202/latest/en-us/sfdc/pdf/salesforce_platform_encryption_implementation_guide.pdf
Tradeoffs and Limitations of Shield Platform Encryption
A security solution as powerful as Shield Platform Encryption doesn't come without some tradeoffs.
When your data is encrypted, some users may see limitations to some functionality, and a few features aren't available at all. Consider the impact on your users and your overall business solution as you design your encryption strategy.
IN THIS SECTION:
General Shield Platform Encryption Considerations
These considerations apply to all data that you encrypt using Shield Platform Encryption.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Which Salesforce Apps Don’t Support Shield Platform Encryption?
Some Salesforce features work as expected when you work with data that’s encrypted with
Shield Platform Encryption. Others don’t.
Shield Platform Encryption and the Lightning Experience
Shield Platform Encryption works the same way in the Lightning Experience as it does in
Salesforce Classic, with a few minor exceptions.
Available in both Salesforce
Classic and Lightning
Experience.
Field Limits with Shield Platform Encryption
Under certain conditions, encrypting a field can impose limits on the values that you store in that field. Before deciding to encrypt a field, make sure that you know these limits.
SEE ALSO:
Platform Encryption Implementation Guide
568
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
General Shield Platform Encryption Considerations
These considerations apply to all data that you encrypt using Shield Platform Encryption.
Note: Beginning with Spring ’17, Shield Platform Encryption no longer masks encrypted data in the presentation layer. This may affect some users’ ability to work with encrypted data.
If you have data you don’t want specific users to see, revisit their field-level security settings
on page 298, record access settings, and object permissions on page 301.
Leads
Lead and Case assignment rules, workflow rules, and validation rules work normally when Lead fields are encrypted. However, matching and de-duplication of records during lead import doesn’t work, and Einstein lead scoring is not available.
Apex Lead Conversion works normally, but PL-SQL-based lead conversion is not supported.
In the Lightning Email Composer, the To: field is not autopopulated when the Name or Email field is encrypted.
Note:
This beta version of encryption support in Leads is production quality but has known limitations.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Flows and Processes (Beta)
Important:
If your data is masked, flows and processes don’t work correctly. In Salesforce orgs created before Spring ’17, assign users who interact with flows or processes the View Encrypted Data permission. To avoid unexpected behavior, activate the Turn
Off Masking for Encrypted Data critical update.
You can reference encrypted fields in most places in your flows and processes. However, you can’t reference encrypted fields in these filtering or sorting contexts.
Tool
Process Builder
Cloud Flow Designer
Filtering Availability
Update Records action
Dynamic Record Choice resource
Fast Lookup element
Record Delete element
Record Lookup element
Record Update element
Sorting Availability
n/a
Dynamic Record Choice resource
Fast Lookup element
Record Lookup element
You can store the value from an encrypted field in a variable and operate on that value in your flow’s logic. You can also update the value for an encrypted field.
Paused flow interviews can result in data being saved in an unencrypted state. When a flow or process is waiting to resume, the associated flow interview is serialized and saved to the database. The flow interview is serialized and saved when:
•
Users pause a flow
•
Flows execute a Wait element
•
Processes are waiting to execute scheduled actions
569
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
If the flow or process loads encrypted fields into a variable during these processes, that data might not be encrypted at rest.
Custom Fields
You can’t use encrypted custom fields in criteria-based sharing rules.
Some custom fields can’t be encrypted.
•
Fields that have the
Unique
or
External ID
attributes or include these attributes on previously encrypted custom fields
•
Fields on external data objects
•
Fields that are used in an account contact relation
You can’t use Schema Builder to create an encrypted custom field.
SOQL/SOSL
•
Encrypted fields can’t be used with the following SOQL and SOSL clauses and functions:
–
Aggregate functions such as MAX(), MIN(), and COUNT_DISTINCT()
–
WHERE clause
–
GROUP BY clause
–
ORDER BY clause
Tip: Consider whether you can replace a WHERE clause in a SOQL query with a FIND query in SOSL.
•
When you query encrypted data, invalid strings return an
INVALID_FIELD
error instead of the expected
MALFORMED_QUERY
.
Lightning Sync
With Shield Platform Encryption enabled, Lightning Sync syncs between users’ email and calendar application and Salesforce only if the user has the "View Encrypted Data" permission.
Lightning for Outlook
With Shield Platform Encryption enabled, Lightning for Outlook users who don’t have the "View Encrypted Data" permission see masked values in Outlook for fields that are encrypted.
Salesforce for Outlook
With Shield Platform Encryption enabled, Salesforce for Outlook syncs between Microsoft Outlook and Salesforce only if the user has the "View Encrypted Data" permission.
Portals
If a portal is enabled in your organization, you can’t encrypt standard fields. Deactivate all customer portals and partner portals to enable encryption on standard fields. (Communities are supported.)
Search
If you encrypt fields with a key and then destroy the key, the corresponding search terms remain in the search index. However, you can’t decrypt the data associated with the destroyed key.
570
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Accounts, Person Accounts, and Contacts
When Person Accounts are turned on, encrypting any of the following Account fields encrypts the equivalent Contact fields, and vice versa.
•
Name
•
Description
•
Phone
•
Fax
When you encrypt any of the following Account or Contact fields, the equivalent fields in Person Accounts are also encrypted.
•
Name
•
Description
•
Mailing Address
•
Phone
•
Fax
•
Mobile
•
Home Phone
•
Other Phone
•
When the Account Name or Contact Name field is encrypted, searching for duplicate accounts or contacts to merge doesn’t return any results.
When you encrypt the First Name or Last Name field on a contact, that contact appears in the Calendar Inviter lookup only if you haven’t filtered by First Name or Last Name.
Salutation and Suffix field values in Contact records can appear masked to users without the “View Encrypted Data” permission, even if the field values aren’t encrypted.
•
When encrypted field values are included in email templates, they appear in plaintext to users with the “View Encrypted Data” permission. Otherwise, the running user’s permissions determine whether the recipient sees plaintext or masked data.
•
Users without the “View Encrypted Data” permission can’t send emails using Mass Email Contacts.
•
When the standard Email field is encrypted, email to Salesforce can’t receive inbound emails.
•
When the standard Email field is encrypted, the detail page for Contacts, Leads, or Person Accounts doesn’t flag invalid email addresses. If you need bounce processing to work as expected, don't encrypt the standard Email field.
Activities
Items in an Activity History related list may be displayed in plaintext even if the fields they refer to are encrypted.
Campaigns
Campaign member search isn’t supported when you search by encrypted fields.
571
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Notes
You can encrypt the body text of Notes created with the new Notes tool. However, the Preview file and Notes created with the old Notes tool aren’t supported.
Field Audit Trail
Data in a previously archived Field Audit Trail isn’t encrypted when you turn on Platform Encryption. For example, say that your org uses
Field Audit Trail to define a data history retention policy for an account field, such as the phone number field. When you turn on encryption for that field, new phone number records are encrypted as they are created. Previous updates to the phone number field that are stored in the Account History related list are also encrypted. However, phone number history data that is already archived in the
FieldHistoryArchive
object is stored without encryption. If you need to encrypt previously archived data, contact Salesforce.
Page Layouts
If you preview a page layout as a profile without the “View Encrypted Data” permission, the preview’s sample data isn’t masked. The sample data may be blank or may appear in plaintext.
Communities
•
For community users with the "View Encrypted Data" permission, data encryption doesn’t change anything about the community experience. However, if you encrypt the Account Name field and you’re not using Person Accounts, encryption affects how users’ roles are displayed to admins. Normally, a community user’s role name is displayed as a combination of their account name and the name of their user profile. When you encrypt the Account Name field, the account ID is displayed instead of the account name.
For example, when the Account Name field is not encrypted, users belonging to the Acme account with the Customer User profile would have a role called
Acme Customer User
. When Account Name is encrypted (and Person Accounts aren’t in use), the role is displayed as something like
001D000000IRt53 Customer User
.
•
Custom fields encrypted with Classic Encryption are masked for Community users even if they have the "View Encrypted Data" permission.
REST API
You don’t get autosuggestions via the REST API when a field is encrypted.
Data Import
You can’t use the Data Import Wizard to perform matching using master-detail relationships or update records that contain encrypted fields. You can use it to add new records, however.
Reports, Dashboards, and List Views
•
Report charts and dashboard components that display encrypted field values may be cached unencrypted.
•
You can’t sort records in list views by fields that are encrypted.
Encryption for Chatter (Pilot)
When you embed a custom component in your Chatter feed using Rich Publisher Add-Ons (Pilot), the data related to those add-ons is encoded, but it isn’t encrypted with the Shield Platform Encryption service. Unencrypted data in Rich Publisher Add-Ons includes data stored in the Extension ID, Text Representation, Thumbnail URL, Title, Payload, and PayloadVersion fields.
572
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
General
•
Encrypted fields can’t be used in:
–
Criteria-based sharing rules
–
Similar opportunities searches
–
External lookup relationships
–
Skinny tables
–
Filter criteria for data management tools
–
Duplicate Management matching rules
•
Live Agent chat transcripts are not encrypted at rest.
•
Web-to-Case is supported, but the Web Company, Web Email, Web Name, and Web Phone fields are not encrypted at rest.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
Which Salesforce Apps Don’t Support Shield Platform Encryption?
Some Salesforce features work as expected when you work with data that’s encrypted with Shield
Platform Encryption. Others don’t.
These apps don’t support data encrypted with Shield Platform Encryption. However, you can enable
Shield Platform Encryption for other apps when these apps are in use.
•
Connect Offline
•
Commerce Cloud
•
Data.com
•
Heroku (but Heroku Connect does support encrypted data)
•
Marketing Cloud (but Marketing Cloud Connect does support encrypted data)
•
Pardot (but Pardot Connect supports encrypted contact email addresses if your Pardot org allows multiple prospects with the same email address)
•
Salesforce Mobile Classic
•
Salesforce IQ
•
Social Customer Service
•
Steelbrick
•
Thunder
•
Quip
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Legacy portals (customer, self-service, and partner) don’t support data encrypted with Shield Platform Encryption. If legacy portals are active, Shield Platform Encryption can’t be enabled.
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
573
Set Up and Maintain Your Salesforce Organization Strengthen Your Data's Security with Shield Platform
Encryption
Shield Platform Encryption and the Lightning Experience
Shield Platform Encryption works the same way in the Lightning Experience as it does in Salesforce
Classic, with a few minor exceptions.
Contacts and Leads
In Lightning, if either the Name or Email field is encrypted, Salesforce doesn’t suggest email recipients from contacts you've emailed before."
Notes
Note previews in Lightning are not encrypted.
File Encryption Icon
The icon that indicates that a file is encrypted doesn’t appear in Lightning.
Date Fields
Lightning shows 12/30/0001 as the dummy date for masking encrypted date values.
Custom Field Masking
When the encryption key is destroyed, the values of encrypted custom field values may appear in plaintext until the page is refreshed.
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Field Limits with Shield Platform Encryption
Under certain conditions, encrypting a field can impose limits on the values that you store in that field. Before deciding to encrypt a field, make sure that you know these limits.
Custom Fields
If you expect users to enter non-ASCII values, such as CJK-encoded data, we recommend creating validation rules to enforce these limits:
•
Email custom field type values that contain only non-ASCII characters are limited to 70 characters.
•
Phone custom field type values that contain only non-ASCII characters are limited to 22 characters.
Case Comment Object
The Body field on the Case Comment object has a limit of 4,000 ASCII characters (or 4,000 bytes).
However, when these fields are encrypted, the character limit is lower. How much lower depends on the kind of characters you enter.
•
ASCII—2959
•
Chinese, Japanese, Korean—1333
•
Other non-ASCII—1479
EDITIONS
Available as an add-on subscription in: Enterprise,
Performance, and
Unlimited Editions. Requires purchasing Salesforce
Shield. Available in
Developer Edition at no charge for orgs created in
Summer ’15 and later.
Available in both Salesforce
Classic and Lightning
Experience.
Contact Object
When Shield Platform Encryption is enabled for the Name field on the Contact object, the character limit is lower for some character types. This is true for both Business accounts and Person accounts. ASCII character limits are not affected.
•
First Name—22 non-ASCII characters
•
Middle Name—22 non-ASCII characters
•
Last Name—70 non-ASCII characters
574
Set Up and Maintain Your Salesforce Organization Session Security
•
Mailing City—22 non_ASCII characters
Note:
This page is about Shield Platform Encryption, not Classic Encryption. What's the difference?
SEE ALSO:
Session Security
After logging in, a user establishes a session with the platform. Use session security to limit exposure to your network when a user leaves the computer unattended while still logged in. It also limits the risk of internal attacks, such as when one employee tries to use another employee’s session. Choose from several session settings to control session behavior.
You can control when an inactive user session expires. The default session timeout is two hours of inactivity. When the session timeout is reached, users are prompted with a dialog that allows them to log out or continue working. If they don’t respond to this prompt, they are logged out.
Note:
When users close a browser window or tab, they aren’t automatically logged off from their Salesforce session. Ensure that your users are aware of this behavior and that they end all sessions properly by selecting
Your Name
> Logout.
By default, Salesforce uses TLS (Transport Layer Security) and requires secure connections (HTTPS) for all communication. The
Require secure connections (HTTPS)
setting determines whether TLS (HTTPS) is required for access to Salesforce, apart from Force.com
sites, which can be accessed using HTTP. If you ask Salesforce to disable this setting and change the URL from https://
to http://
, you can still access the application. However, for added security, require all sessions to use TLS. For more information, see
on page 608.
You can restrict access to certain types of resources based on the level of security associated with the authentication (login) method for the user’s current session. By default, each login method has one of two security levels: Standard or High Assurance. You can change the session security level and define policies so specified resources are only available to users with a High Assurance level. For details, see
Session-level Security on page 612.
You can control whether your org stores user logins and whether they can appear from the Switcher with the settings
Enable caching and autocomplete on login page
,
Enable user switching
, and
Remember me until logout
.
IN THIS SECTION:
Modify Session Security Settings
You can modify session security settings to specify session connection type, timeout settings, and IP address ranges to protect against malicious attacks and more.
Set Trusted IP Ranges for Your Organization
Trusted IP Ranges define a list of IP addresses from which users can log in without receiving a login challenge for verification of their identity, such as a code sent to their mobile phone.
Monitor and protect your Salesforce org by reviewing active sessions and session details on the User Session Information page. You can create custom list views, view details about a user associated with a specific session, and easily end suspicious sessions. Salesforce admins can view all user sessions for an org; non-admins see only their own sessions.
575
Set Up and Maintain Your Salesforce Organization Session Security
Learn about the session types in the User Session Information page to help you monitor and protect your organization.
SEE ALSO:
Set Trusted IP Ranges for Your Organization
Modify Session Security Settings
You can modify session security settings to specify session connection type, timeout settings, and
IP address ranges to protect against malicious attacks and more.
1. From Setup, enter
Session Settings
in the Quick Find box, then select Session Settings.
2. Customize the session security settings.
Field
Timeout value
Description
Length of time after which the system logs out inactive users. For Portal users, the timeout is between 10 minutes and 24 hours even though you can only set it as low as 15 minutes. Select a value between 15 minutes and 24 hours. Choose a shorter timeout period if your org has sensitive information and you want to enforce stricter security.
Note: The last active session time value isn’t updated until halfway through the timeout period. So if you have a 30-minute timeout, the system doesn’t check for activity until 15 minutes have passed. For example, if you update a record after 10 minutes, the last active session time value isn’t updated because there was no activity after 15 minutes. You’re logged out in 20 more minutes (30 minutes total), because the last active session time wasn’t updated. Suppose that you update a record after 20 minutes. That’s
5 minutes after the last active session time is checked. Your timeout resets, and you have another 30 minutes before being logged out, for a total of 50 minutes.
Disable session timeout warning popup
Determines whether the system prompts inactive users with a timeout warning message. Users are prompted
30 seconds before timeout as specified by the
Timeout value
.
Force logout on session timeout
Requires that when sessions time out for inactive users, current sessions become invalid. The browser refreshes and returns to the login page. To access the org, the user must log in again.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
The Lock sessions to the IP address from which they originated
setting is available in: Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
All other settings available in: Personal, Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
USER PERMISSIONS
To modify session security settings:
•
Customize Application
576
Set Up and Maintain Your Salesforce Organization Session Security
Field Description
Note: Do not select
Disable session timeout warning popup
when using this setting.
Lock sessions to the IP address from which they originated
Determines whether user sessions are locked to the IP address from which the user logged in, helping to prevent unauthorized persons from hijacking a valid session.
Note:
This setting can inhibit various applications and mobile devices.
Lock sessions to the domain in which they were first used
Require secure connections
(HTTPS)
Require HttpOnly attribute
Associates a current UI session for a user, such as a community user, with a specific domain. The setting helps prevent unauthorized use of the session
ID in another domain. This setting is enabled by default for orgs created with the Spring ’15 release or later.
Determines whether HTTPS is required to log in to or access Salesforce, apart from Force.com sites, which can be accessed using HTTP.
This setting is enabled by default for security reasons. This setting does not apply to API requests. All API requests require HTTPS.
Note: The Reset Passwords for Your Users page can only be accessed using HTTPS.
Require secure connections
(HTTPS) for all third-party domains
Determines whether HTTPS is required for connecting to third-party domains.
This setting is enabled by default on accounts created after the Summer ’17 release.
Force relogin after Login-As-User
Determines whether an administrator who is logged in as another user is returned to their previous session after logging out as the secondary user.
If the setting is enabled, an administrator must log in again to continue using
Salesforce after logging out as the user. Otherwise, the administrator is returned to the original session after logging out as the user. This setting is enabled by default for new orgs beginning with the Summer ’14 release.
Restricts session ID cookie access. A cookie with the HttpOnly attribute is not accessible via non-HTTP methods, such as calls from JavaScript.
Note: If you have a custom or packaged application that uses
JavaScript to access session ID cookies, selecting
Require
HttpOnly attribute
breaks your application. It denies the application access to the cookie. If
Require HttpOnly attribute
is selected, the AJAX Toolkit debugging window isn’t available.
Use POST requests for cross-domain sessions
Sets the org to send session information using a POST request, instead of a
GET request, for cross-domain exchanges. An example of a cross-domain exchange is when a user is using a Visualforce page. In this context, POST requests are more secure than GET requests because POST requests keep the
577
Set Up and Maintain Your Salesforce Organization Session Security
Field Description
session information in the body of the request. However, if you enable this setting, embedded content from another domain, such as:
<img src="https://acme.force.com/pic.jpg"/> sometimes doesn’t display.
Enforce login IP ranges on every request
Restricts the IP addresses from which users can access Salesforce to only the
IP addresses defined in
Login IP Ranges
. If this setting is enabled, login
IP ranges are enforced on each page request, including requests from client applications. If this setting isn’t enabled, login IP ranges are enforced only when a user logs in. This setting affects all user profiles that have login IP restrictions.
Enable caching and autocomplete on login page
Allows the user’s browser to store usernames. If enabled, after initial login, usernames are auto-filled into the
Username
field on the login page. If the user selected Remember me on the login page, the username persists after the session expires or the user logs out. The username also appears on the
Switcher. This setting is selected by default for all orgs.
Note: If you disable this setting, the Remember me option doesn’t appear on your org’s login page or from the Switcher.
Enable secure and persistent browser caching to improve performance
Enable user switching
Enables secure data caching in the browser to improve page reload performance by avoiding extra round trips to the server. This setting is selected by default for all orgs. We don’t recommend disabling this setting, but if your company’s policy doesn’t allow browser caching even if the data is encrypted, you can disable it.
Determines whether the Switcher appears when your org’s users select their profile picture. This setting is selected by default for all organizations. The
Enable caching and autocomplete on login page
setting must also be enabled. Deselect the
Enable user switching
setting to prevent your org from appearing in Switchers on other orgs. It also prevents your org users from seeing the Switcher when they select their profile picture.
Remember until logout
Normally, usernames are cached only while a session is active or if a user selects Remember Me. For SSO sessions, the remember option isn't available.
So, once the session expires, the username disappears from the login page and the Switcher. By enabling
Remember me until logout
, the cached usernames are deleted only if the user explicitly logs out. If the session times out, they appear on the Switcher as inactive. This way, if the users are on their own computer and allow a session to timeout, they can select the username to reauthenticate. If they're on a shared computer, the username is deleted immediately when the user logs out.
This setting applies to all your org’s users. This option isn't enabled by default.
However, we encourage you to enable it as a convenience to your users. Keep
578
Set Up and Maintain Your Salesforce Organization Session Security
Field Description
this setting disabled if your org doesn't expose all your SSO or authentication providers on your login page.
Enable the SMS method of identity confirmation
Allows users to receive a one-time PIN delivered via SMS. If this setting is selected, administrators or users must verify their mobile phone number before taking advantage of this feature. This setting is selected by default for all orgs.
Require security tokens for API logins from callouts (API version
31.0 and earlier)
In API version 31.0 and earlier, requires the use of security tokens for API logins from callouts. Examples are Apex callouts or callouts using the AJAX proxy. In
API version 32.0 and later, security tokens are required by default.
Login IP Ranges
(for Contact Manager,
Group, and Professional Editions)
Specifies a range of IP addresses users must log in from (inclusive), or the login fails.
To specify a range, click New and enter a Start IP Address and End IP Address to define the range, which includes the start and end values.
This field is not available in Enterprise, Unlimited, Performance, and Developer
Editions. In those editions, you can specify a valid Login IP Range in the user profile settings.
Let users use a security key
(U2F)
Allows users to use a U2F security key for two-factor authentication and identity verification. Instead of using Salesforce Authenticator, a one-time password generated by an authenticator app, or one-time passwords sent by email or
SMS, users insert their registered U2F security key into a USB port to complete verification.
Require identity verification during two-factor authentication registration
Requires users to confirm their identities to add a two-factor authentication method, such as Salesforce Authenticator, instead of requiring a relogin as before.
Require identity verification for change of email address
Requires users to confirm their identities to change email addresses instead of requiring a relogin as before.
Note: To get the emails to confirm identity, make sure that users have access to their previously registered email accounts.
Allow location-based automated verifications with Salesforce
Authenticator
Allow only from trusted IP addresses
Allows users to verify identity by automatically approving notifications in
Salesforce Authenticator, whenever users are in trusted locations such as a home or office. If you allow automated verifications, you can allow them from any location or restrict them to only trusted IP addresses, such as your corporate network.
Allow Lightning Login
Enable clickjack protection for
Setup pages
Allows users to use Lightning Login for password-free Salesforce logins, relying on Salesforce Authenticator for identity verification.
Protects against clickjack attacks on setup Salesforce pages. Clickjacking is also known as a user interface redress attack. (Setup pages are available from the Setup menu.)
579
Set Up and Maintain Your Salesforce Organization Session Security
Field
Enable clickjack protection for non-Setup Salesforce pages
Enable clickjack protection for customer Visualforce pages with standard headers
Description
Protects against clickjack attacks on non-setup Salesforce pages. Clickjacking is also known as a user interface redress attack. Setup pages already include protection against clickjack attacks. (Setup pages are available from the Setup menu.) This setting is selected by default for all orgs.
Protects against clickjack attacks on your Visualforce pages with headers enabled. Clickjacking is also known as a user interface redress attack.
Warning: If you use custom Visualforce pages within a frame or iframe, you sometimes see a blank page or the page displays without the frame. For example, Visualforce pages in a page layout don’t function when clickjack protection is on.
Enable clickjack protection for customer Visualforce pages with headers disabled
Protects against clickjack attacks on your Visualforce pages with headers disabled when setting showHeader="false"
on the page. Clickjacking is also known as a user interface redress attack.
Warning: If you use custom Visualforce pages within a frame or iframe, you sometimes see a blank page or the page displays without the frame. For example, Visualforce pages in a page layout don’t function when clickjack protection is on.
Enable CSRF protection on GET requests on non-setup pages
Enable CSRF protection on POST requests on non-setup pages
Enable XSS protection
Enable Content Sniffing protection
Logout URL
Protects against Cross Site Request Forgery (CSRF) attacks by modifying non-Setup pages. Non-Setup pages include a random string of characters in the URL parameters or as a hidden form field. With every GET and POST request, the application checks the validity of this string of characters. The application doesn’t execute the command unless the value found matches the expected value. This setting is selected by default for all orgs.
Protects against cross-site scripting attacks. If a reflected cross-site scripting attack is detected, the browser shows a blank page with no content.
Prevents the browser from inferring the MIME type from the document content. It also prevents the browser from executing malicious files (JavaScript,
Stylesheet) as dynamic content.
Redirects users to a specific page after they log out of Salesforce, such as an authentication provider’s page or a custom-branded page. This URL is used only if no logout URL is specified in the identity provider, SAML single sign-on, or external authentication provider settings. If no value is specified for
Logout
URL
, the default is https://login.salesforce.com
, unless
MyDomain is enabled. If My Domain is enabled, the default is https://customdomain.my.salesforce.com
.
3. Click Save.
580
Set Up and Maintain Your Salesforce Organization Session Security
Session Security Levels
You can restrict access to certain types of resources based on the level of security associated with the authentication (login) method for the user’s current session. By default, each login method has one of two security levels: Standard or High Assurance. You can change the session security level and define policies so specified resources are only available to users with a High Assurance level.
The different authentication methods are assigned these security levels, by default.
•
Username and Password — Standard
•
Delegated Authentication — Standard
•
Activation — Standard
•
Lightning Login — Standard
•
Two-Factor Authentication — High Assurance
•
Authentication Provider — Standard
•
SAML — Standard
Note: The security level for a SAML session can also be specified using the
SessionLevel
attribute of the SAML assertion sent by the identity provider. The attribute can take one of two values,
STANDARD
or
HIGH_ASSURANCE
.
To change the security level associated with a login method:
1. From Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings.
2. Under Session Security Levels, select the login method.
3. To move the method to the proper category, click the Add or Remove arrow.
Currently, the only features that use session-level security are reports and dashboards in Salesforce and connected apps. You can set policies requiring High Assurance on these types of resources. You can also specify an action to take if the session used to access the resource is not High Assurance. The supported actions are:
•
Block — Blocks access to the resource by showing an insufficient privileges error.
•
Raise session level — Prompts users to complete two-factor authentication. When users authenticate successfully, they can access the resource. For reports and dashboards, you can apply this action when users access reports or dashboards, or just when they export and print them.
Warning: Raising the session level to high assurance by redirecting the user to complete two-factor authentication is not a supported action in Lightning Experience. If your org has Lightning Experience enabled, and you set a policy that requires a high assurance session to access reports and dashboards, Lightning Experience users with a standard assurance session are blocked from reports and dashboards. Also, they don’t see the icons for these resources in the navigation menu. As a workaround, users with a standard assurance session can log out and log in again using an authentication method that is defined as high assurance by their org. Then they have access to reports and dashboards. Or, they can switch to Salesforce Classic, where they’re prompted to raise the session level when they attempt to access reports and dashboards.
To set a High Assurance required policy for accessing a connected app:
1. From Setup, enter
Connected Apps
in the
Quick Find
box, then select the option for managing connected apps.
2. Click Edit next to the connected app.
3. Select High Assurance session required.
4. Select one of the actions presented.
5. Click Save.
To set a High Assurance required policy for accessing reports and dashboards:
1. From Setup, enter
Access Policies
in the
Quick Find
box, then select Access Policies.
581
Set Up and Maintain Your Salesforce Organization Session Security
2. Select High Assurance session required.
3. Select one of the actions presented.
4. Click Save.
Session levels have no impact on resources in the app other than connected apps, reports, and dashboards for which explicit security policies have been defined.
SEE ALSO:
Set Trusted IP Ranges for Your Organization
Trusted IP Ranges define a list of IP addresses from which users can log in without receiving a login challenge for verification of their identity, such as a code sent to their mobile phone.
EDITIONS
Note: Who Sees What: Organization Access (Salesforce Classic)
Watch how you can restrict login through IP ranges and login hours.
To help protect your organization’s data from unauthorized access, you can specify a list of IP addresses from which users can log in without receiving a login challenge. However, this does not restrict access, entirely, for users outside of the Trusted IP Range. After these users complete the login challenge (usually by entering a code sent to their mobile device or email address), they can log in.
1. From Setup, enter
Network Access
in the
Quick Find
box, then select Network
Access.
2. Click New.
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
USER PERMISSIONS
To view network access:
•
Login Challenge Enabled
To change network access:
•
Manage IP Addresses
3. Enter a valid IP address in the
Start IP Address
field and a higher IP address in the
End IP Address
field.
The start and end addresses define the range of allowable IP addresses from which users can log in, including the start and end values. If you want to allow logins from a single IP address, enter the same address in both fields.
The start and end IP addresses must be in an IPv4 range and include no more than 33,554,432 addresses (2
25
, a /7 CIDR block).
4. Optionally, enter a description for the range. For example, if you maintain multiple ranges, enter details about the part of your network that corresponds to this range.
5. Click Save.
Note: For organizations that were activated before December 2007, Salesforce automatically populated your organization’s trusted IP address list in December 2007, when this feature was introduced. The IP addresses from which trusted users had already accessed Salesforce during the past six months were added.
SEE ALSO:
Restrict Where and When Users Can Log In to Salesforce
Security Implementation Guide
582
Set Up and Maintain Your Salesforce Organization Session Security
User Sessions
Monitor and protect your Salesforce org by reviewing active sessions and session details on the
User Session Information page. You can create custom list views, view details about a user associated with a specific session, and easily end suspicious sessions. Salesforce admins can view all user sessions for an org; non-admins see only their own sessions.
When you manually end a user’s session by clicking the Remove button, the user must log in again to the organization.
The following table contains information about the fields you can view on this page. Due to the nature of geolocation technology, the accuracy of geolocation fields (for example, country, city, postal code) may vary.
Field
City
Country
Country Code
Created
Latitude
Location
Longitude
Login Type
Parent Session ID
Postal Code
Session ID
Session Type
Source IP
Subdivision
User Type
Username
Updated
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
Description
The city where the user’s IP address is physically located. This value is not localized.
The country where the user’s IP address is physically located. This value is not localized.
The ISO 3166 code for the country where the user’s IP address is physically located. This value is not localized. For more information, see Country Codes - ISO 3166 .
The date and time stamp of when the session began.
The latitude where the user’s IP address is physically located.
The approximate location of the IP address from where the user logged in. To show more geographic information, such as approximate city and postal code, create a custom view to include those fields.
This value is not localized.
The longitude where the user’s IP address is physically located.
The type of login associated with the session. Some login types include Application, SAML, and Portal.
If a session has a parent, this ID is the parent’s unique ID.
The postal code where the user’s IP address is physically located. This value is not localized.
The unique ID for the session.
The type of session the user is logged in to. For example, common ones are UI, Content, API, and
Visualforce.
The IP address associated with the session.
The name of the subdivision where the user’s IP address is physically located. This value is not localized.
The profile type associated with the session.
The username used when logged in to the session. To view the user’s profile page, click the username.
The date and time stamp of the last session update due to activity. For example, during a UI session, users make frequent changes to records and other data as they work. With each change, both the
Updated
and
Valid Until
date and time stamps are refreshed.
583
Set Up and Maintain Your Salesforce Organization Session Security
Field
Valid Until
Description
If you don’t end the session manually, the date and time stamp of when the session automatically expires.
SEE ALSO:
The Elements of User Authentication
Understanding Session Types
Learn about the session types in the User Session Information page to help you monitor and protect your organization.
You can view the session type for a specific user on the User Session Information page. To access the page from Setup, enter
Session Management
in the
Quick Find
box, then select
Session Management.
Session types indicate the type of session a user is utilizing to access an organization. Session types can be persistent or temporary and accessed via the user interface, API, or other methods, such as an OAuth authentication process.
The following table describes the session types.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
Session Type
API
APIOnlyUser
Chatter Networks
ChatterNetworksAPIOnly
Content
OauthApprovalUI
Oauth2
SiteStudio
SitePreview
SubstituteUser
TempContentExchange
TempOauthAccessTokenFrontdoor
Description
Created when accessing an organization through the API.
Created to enable a password reset in the user interface for API-only users.
Created when using Chatter Networks or Chatter Communities.
Created when using the Chatter Networks or Chatter Communities API.
Created when serving user-uploaded content.
A session that only allows access to the OAuth approval page.
Created via OAuth flows. For example, if you use OAuth authentication for a connected app, this type of session is created.
Created when using the Sites Studio user interface.
A session that is initiated when an internal canvas app is invoked. This will always be a child session with a UI parent session.
A session created when one user logs in via another user. For example, if an administrator logs in as another user, a SubstituteUser session is created.
A temporary user interface session to switch to the content domain, such as the user interface into which users type in their credentials.
A temporary session via the OAuth access token assertion flow that cannot be refreshed and must be mapped to a regular session type.
584
Set Up and Maintain Your Salesforce Organization Activations
Session Type
TempVisualforceExchange
TempUIFrontdoor
UI
UserSite
Visualforce
WDC_API
Description
A temporary session to switch to the Visualforce domain.
A temporary session that cannot be refreshed and must be mapped to a regular session type.
Created when using a user interface page.
Initiated when a canvas application is invoked. Always a child session with a UI parent session.
Created via a Visualforce page.
A session using the Work.com API. This is always a child session and cannot be used in the user interface.
SEE ALSO:
The Elements of User Authentication
Activations
Activation tracks information about devices from which users have verified their identity. Salesforce prompts users to verify their identity when they access Salesforce from an unrecognized browser or application. Identity verification adds an extra layer of security on top of username and password authentication. The Activations page lists the login IP addresses and client browsers used.
When a user logs in from outside a trusted IP range and uses a browser or app we don’t recognize, the user is challenged to verify identity. We use the highest-priority verification method available for each user. In order of priority, the methods are:
1. Verification via push notification or location-based automated verification with the Salesforce
Authenticator mobile app (version 2 or later) connected to the user’s account.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in all editions
2. Verification via a U2F security key registered with the user’s account.
3. Verification code generated by a mobile authenticator app connected to the user’s account.
4. Verification code sent via SMS to the user’s verified mobile phone.
5. Verification code sent via email to the user’s email address.
After identity verification is successful, the user doesn’t have to verify identity again from that browser or app, unless the user:
•
Manually clears browser cookies, sets the browser to delete cookies, or browses in private or incognito mode
•
Deselects Don’t ask again on the identity verification page
The Activations page in Setup lists the login IP addresses and client browser information of devices from which users have verified their identity. You can revoke the browser activation status for one, many, or all users.
For example, a user reports a lost device and is issued a new one. You can revoke the activation status of the browser on the lost device so that anyone attempting to access the org from that device has to verify their identity. This identity verification adds a layer of security while allowing users to stay productive.
Users can view their own Activations page to check their login IP addresses and client browser information. End users can revoke the activation status only for their own activated browsers.
585
Set Up and Maintain Your Salesforce Organization Authenticate Users
For example, a user logs in to the org. On the user’s Activations page, several different browsers are activated, but the user has only logged in from a single browser on a work laptop. The user immediately revokes the activation status of those browsers the user doesn’t recognize. Because this user is challenged for identity verification using a code sent via SMS to the user’s mobile device, anyone else who tries to log in from one of the deactivated browsers can’t get the texted verification code. Without the code, the hacker fails the identity verification challenge. The user can then report the potential security breach.
IN THIS SECTION:
View your users’ activations and revoke activation status to prevent security breaches.
SEE ALSO:
Use Activations
View your users’ activations and revoke activation status to prevent security breaches.
To see login IP and browser information about devices from which users have verified their identity, from Setup, enter
Activations
in the
Quick Find
box, then select Activations.
You can revoke activation status by selecting one or more entries in the Activated Client Browser list, clicking Remove, and confirming the action. Users can view and revoke only their own activated browsers. A user who logs in from a deactivated browser is prompted to verify identity, unless the login IP address is within a trusted IP range.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in all editions
Note: When a user deselects the Don’t ask again option that appears on the identity verification page, the browser isn’t activated.
Advise your users to deselect this option whenever they log in from a public or shared device.
SEE ALSO:
Authenticate Users
Authentication means preventing unauthorized access to your organization or its data by making sure each logged in user is who they say they are.
IN THIS SECTION:
The Elements of User Authentication
Salesforce provides a variety of ways to authenticate users. Build a combination of authentication methods that fits the needs of your organization and your users' use patterns.
Choose login settings to ensure that your users are who they say they are.
586
Set Up and Maintain Your Salesforce Organization Authenticate Users
The Elements of User Authentication
Salesforce provides a variety of ways to authenticate users. Build a combination of authentication methods that fits the needs of your organization and your users' use patterns.
IN THIS SECTION:
Salesforce has its own system of user authentication, but some companies prefer to use an existing single sign-on capability to simplify and standardize their user authentication.
Network-based security limits where users can log in from, and when they can log in. This is different from user authentication, which only determines who can log in. Use network-based security to limit the window of opportunity for an attacker and to make it more difficult for an attacker to use stolen credentials.
CAPTCHA Security for Data Exports
By request, Salesforce can require users to pass a simple text-entry user verification test to export data from Salesforce. This type of network-based security helps prevent malicious users from accessing your organization’s data, and can reduce the risk of automated attacks.
Restrict Where and When Users Can Log In to Salesforce
You can restrict the hours during which users can log in and the range of IP addresses from which they can log in and access
Salesforce. If IP address restrictions are defined for a user’s profile and a login originates from an unknown IP address, Salesforce does not allow the login. These restrictions help protect your data from unauthorized access and phishing attacks.
As a Salesforce admin, you can enhance your org’s security by requiring a second level of authentication for every user login. You can also require two-factor authentication when a user meets certain criteria, such as attempting to view reports or access a connected app.
Login flows allow administrators to build post-authentication processes to match their business practices, associate the flow with a user profile, and send the user through that flow when logging in. Use login flows to collect registration information from users, provide a terms of service acceptance form, prompt the user for a second factor of authentication, and other customization.
SEE ALSO:
CAPTCHA Security for Data Exports
Single Sign-On
Salesforce has its own system of user authentication, but some companies prefer to use an existing single sign-on capability to simplify and standardize their user authentication.
You have two options to implement single sign-on—federated authentication using Security Assertion Markup Language (SAML) or delegated authentication.
587
Set Up and Maintain Your Salesforce Organization Authenticate Users
•
Federated authentication using Security Assertion Markup Language (SAML) lets you send authentication and authorization data between affiliated but unrelated web services. You can log in to Salesforce from a client app. Salesforce enables federated authentication for your org automatically.
•
Delegated authentication SSO integrates Salesforce with an authentication method that you choose. You can integrate authentication with your LDAP (Lightweight Directory Access Protocol) server or use a token instead of a password for authentication. You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their Salesforce-managed password.
Delegated authentication offers the following benefits.
–
Uses a stronger form of user authentication, such as integration with a secure identity provider
–
Makes your login page private and accessible only behind a corporate firewall
–
Differentiates your org from all other companies that use Salesforce to reduce phishing attacks
You must contact Salesforce to enable delegated authentication before you can configure it on your org.
•
Authentication providers let your users log in to your Salesforce org using their login credentials from an external service provider.
Salesforce supports the OpenID Connect protocol, which lets users log in from any OpenID Connect provider, such as Google, PayPal, and LinkedIn. When an authentication provider is enabled, Salesforce doesn’t validate a user’s password. Instead, Salesforce uses the user’s login credentials from the external service provider to establish authentication credentials.
Identity Providers
An identity provider is a trusted provider that lets you use single sign-on (SSO) to access other websites. A service provider is a website that hosts apps. You can enable Salesforce as an identity provider and define one or more service providers. Your users can then access other apps directly from Salesforce using SSO. SSO can be a great help to your users—instead of having to remember many passwords, they only have to remember one.
For more information, see “Identity Providers and Service Providers” in the Salesforce online help.
SEE ALSO:
The Elements of User Authentication
Network-Based Security
Network-based security limits where users can log in from, and when they can log in. This is different from user authentication, which only determines who can log in. Use network-based security to limit the window of opportunity for an attacker and to make it more difficult for an attacker to use stolen credentials.
SEE ALSO:
The Elements of User Authentication
CAPTCHA Security for Data Exports
By request, Salesforce can require users to pass a simple text-entry user verification test to export data from Salesforce. This type of network-based security helps prevent malicious users from accessing your organization’s data, and can reduce the risk of automated attacks.
588
Set Up and Maintain Your Salesforce Organization Authenticate Users
To pass the test, users must type two words displayed on an overlay into the overlay’s text box field, and click a Submit button. Salesforce uses CAPTCHA technology provided by reCaptcha to verify that a person, as opposed to an automated program, has correctly entered the text into the overlay. CAPTCHA stands for “Completely Automated Public Turing test to tell Computers and Humans Apart.”
SEE ALSO:
The Elements of User Authentication
Restrict Where and When Users Can Log In to Salesforce
You can restrict the hours during which users can log in and the range of IP addresses from which they can log in and access Salesforce.
If IP address restrictions are defined for a user’s profile and a login originates from an unknown IP address, Salesforce does not allow the login. These restrictions help protect your data from unauthorized access and phishing attacks.
Login Hours
For each profile, you can set the hours when users can log in. See:
•
View and Edit Login Hours in the Enhanced Profile User Interface
•
View and Edit Login Hours in the Original Profile User Interface
Two-Factor Authentication for User Interface Logins
For each profile, you can require users to use a second form of authentication when they log in via the user interface. See
Authentication Login Requirements on page 621 and
Set Two-Factor Authentication Login Requirements and Custom Policies for Single
Sign-On, Social Sign-On, and Communities
.
Two-Factor Authentication for API Logins
For each profile, you can require a verification code (also called a time-based one-time password, or TOTP) instead of the standard security token. Users connect an authenticator app that generates verification codes to their account. Users with the “Two-Factor
Authentication for API Logins” permission use a code instead of the standard security token whenever it’s requested, such as when
Login IP Address Ranges
For Enterprise, Performance, Unlimited, Developer, and Database.com editions, you can set the Login IP Range addresses from which users can log in on an individual profile. Users outside of the Login IP Range set on a profile can’t access your Salesforce org.
For Contact Manager, Group, and Professional Editions, set the Login IP Range. From Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings.
Login IP Address Range Enforcement for All Access Requests
You can restrict all access to Salesforce to the IP addresses included in Login IP Ranges in users’ profiles. For example, suppose a user logs in successfully from an IP address defined in Login IP Ranges. The user then moves to a different location and has a new IP address that is outside of Login IP Ranges. When the user refreshes the browser or tries to access Salesforce, including access from a client application, the user is denied. To enable this option, from Setup, enter
Session Settings
in the
Quick Find
box, select
Session Settings, and then select Enforce login IP ranges on every request. This option affects all user profiles that have login IP restrictions.
589
Set Up and Maintain Your Salesforce Organization Authenticate Users
Org-wide Trusted IP Ranges
For all users, you can set a list of IP address ranges from which they can always log in without receiving a login challenge. These users
.
When users log in to Salesforce via the user interface, the API, or a desktop client such as Salesforce for Outlook, Connect Offline, Connect for Office, or the Data Loader, Salesforce confirms that the login is authorized as follows.
1. Salesforce checks whether the user’s profile has login hour restrictions. If login hour restrictions are specified for the user’s profile, any login outside the specified hours is denied.
2. If the user has the “Two-Factor Authentication for User Interface Logins” permission, Salesforce prompts the user for a second form of authentication upon logging in. If the user’s account isn’t already connected to a mobile authenticator app such as Salesforce
Authenticator, Salesforce first prompts the user to connect the app.
3. If the user has the “Two-Factor Authentication for API Logins” permission and has connected an authenticator app to the account,
Salesforce returns an error if the user uses the standard security token. The user has to enter a verification code (time-based one-time password) generated by the authenticator app instead.
4. Salesforce then checks whether the user’s profile has IP address restrictions. If IP address restrictions are defined for the user’s profile, logins from an undesignated IP address are denied, and logins from a specified IP address are allowed. If the Enforce login IP ranges
on every request session setting is enabled, the IP address restrictions are enforced for each page request, including requests from client applications.
5. If profile-based IP address restrictions are not set, Salesforce checks whether the user is logging in from a device used to access
Salesforce before.
•
If the user’s login is from a device and browser that Salesforce recognizes, the login is allowed.
•
If the user’s login is from an IP address in your org’s trusted IP address list, the login is allowed.
•
If the user’s login is not from a trusted IP address or a device and browser Salesforce recognizes, the login is blocked.
Whenever a login is blocked or returns an API login fault, Salesforce has to verify the user’s identity:
•
For access via the user interface, the user is prompted to verify using Salesforce Authenticator (version 2 or later), or to enter a verification code.
Note:
Users aren’t asked for a verification code the first time they log in to Salesforce.
•
For access via the API or a client, users must add their security token to the end of their password to log in. Or, if “Two-Factor
Authentication on API Logins” is set on the user profile, users enter a verification code generated by an authenticator app.
A security token is an automatically generated key from Salesforce. For example, if a user’s password is
mypassword
, and the security token is
XXXXXXXXXX
, the user must enter
mypasswordXXXXXXXXXX
to log in. Or some client applications have a separate field for the security token.
Users can obtain their security token by changing their password or resetting their security token via the Salesforce user interface.
When a user changes a password or resets a security token, Salesforce sends a new security token to the email address on the user’s
Salesforce record. The security token is valid until the user resets the security token, changes a password, or has a password reset.
Tip: Before you access Salesforce from a new IP address, we recommend that you get your security token from a trusted network using Reset My Security Token.
Tips on Setting Login Restrictions
Consider the following when setting login restrictions.
•
When a user’s password is changed, the security token is reset. Log in via the API or a client can be blocked until the user adds the automatically generated security token to the end of the password.
590
Set Up and Maintain Your Salesforce Organization Authenticate Users
•
Partner Portal and Customer Portal users aren’t required to activate their browser to log in.
•
For more information on API login faults, see the Core Data Types Used in API Calls topic in the
SOAP API Developer's Guide
.
•
If single sign-on (SSO) is enabled for your org, API and desktop client users can log in to Salesforce unless their profile has IP address restrictions set and they try to log in from outside of the range defined. Also the SSO authority usually handles login lockout policies for users with the “Is Single Sign-On Enabled” permission. However, if the security token is enabled for your org, your org’s login lockout settings determine how many times users can attempt to log in with an invalid security token before being locked out of
Salesforce.
•
These events count toward the number of times users can attempt to log in with an invalid password before getting locked out of
Salesforce, as defined in your org’s login lockout settings.
–
Each time users are prompted to verify identity
–
Each time users incorrectly add the security token or verification code to the end of their password to log in to Salesforcevia the
API or a client
IN THIS SECTION:
Restrict Login IP Ranges in the Enhanced Profile User Interface
Control login access at the user level by specifying a range of allowed IP addresses on a user’s profile. When you define IP address restrictions for a profile, a login from any other IP address is denied.
Restrict Login IP Addresses in the Original Profile User Interface
Control login access at the user level by specifying a range of allowed IP addresses on a user’s profile. When you define IP address restrictions for a profile, a login from any other IP address is denied.
View and Edit Login Hours in the Enhanced Profile User Interface
For each profile, you can specify the hours when users can log in.
View and Edit Login Hours in the Original Profile User Interface
Specify the hours when users can log in based on the user profile.
Set Trusted IP Ranges for Your Organization
Trusted IP Ranges define a list of IP addresses from which users can log in without receiving a login challenge for verification of their identity, such as a code sent to their mobile phone.
Two-Factor Authentication
As a Salesforce admin, you can enhance your org’s security by requiring a second level of authentication for every user login. You can also require two-factor authentication when a user meets certain criteria, such as attempting to view reports or access a connected app.
Salesforce Identity Verification
When a user logs in from outside a trusted IP range and uses a browser or app we don’t recognize, the user is challenged to verify identity. We use the highest-priority verification method available for each user. In order of priority, the methods are:
1. Verification via push notification or location-based automated verification with the Salesforce
Authenticator mobile app (version 2 or later) connected to the user’s account.
2. Verification via a U2F security key registered with the user’s account.
3. Verification code generated by a mobile authenticator app connected to the user’s account.
4. Verification code sent via SMS to the user’s verified mobile phone.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and Contact
Manager Editions
591
Set Up and Maintain Your Salesforce Organization Authenticate Users
5. Verification code sent via email to the user’s email address.
After identity verification is successful, the user doesn’t have to verify identity again from that browser or app, unless the user:
•
Manually clears browser cookies, sets the browser to delete cookies, or browses in private or incognito mode
•
Deselects Don’t ask again on the identity verification page
Org Policies That Require Two-Factor Authentication
You can set policies that require a second level of authentication on every login, every login through the API (for developers and client applications), or for access to specific features. Your users can provide the second factor by downloading and installing a mobile authenticator app, such as the Salesforce Authenticator app or the Google Authenticator app, on their mobile device. They can also use a U2F security key as the second factor. After they connect an authenticator app or register a security key with their account in Salesforce, they use them whenever your org’s policies require two-factor authentication.
The Salesforce Authenticator mobile app (version 2 and later) sends a push notification to the user’s mobile device when activity on the
Salesforce account requires identity verification. The user responds on the mobile device to verify or block the activity. The user can enable location services for the app and automate verifications from trusted locations, such as a home or office. Salesforce Authenticator also generates verification codes, sometimes called “time-based one-time passwords” (TOTPs). Users can choose to enter a password plus the code instead of responding to a push notification from the app for two-factor verification. Or they can get a verification code from another authenticator app.
If users lose or forget the device they usually use for two-factor authentication, you can generate a temporary verification code for them.
You set when the code expires, from 1 to 24 hours after you generate it. Your user can use the code multiple times until it expires. A user can have only one temporary code at a time. If a user needs a new code while the old code is still valid, you can expire the old code, then generate a new one. Users can expire their own valid codes in their personal settings.
SEE ALSO:
Set Two-Factor Authentication Login Requirements
Restrict Where and When Users Can Log In to Salesforce
Connect Salesforce Authenticator (Version 2 or Later) to Your Account for Identity Verification
Verify Your Identity with a One-Time Password Generator App or Device
Disconnect Salesforce Authenticator (Version 2 or Later) from a User’s Account
Disconnect a User’s One-Time Password Generator App
Generate a Temporary Identity Verification Code
Expire a Temporary Verification Code
Delegate Two-Factor Authentication Management Tasks
592
Set Up and Maintain Your Salesforce Organization Authenticate Users
Custom Login Flows
Login flows allow administrators to build post-authentication processes to match their business practices, associate the flow with a user profile, and send the user through that flow when logging in. Use login flows to collect registration information from users, provide a terms of service acceptance form, prompt the user for a second factor of authentication, and other customization.
Use the Flow Designer to create login flows, and then associate those flows with specific profiles in your organization. You can connect the same flow to multiple profiles. Users with the profile are directed to the login flow after they authenticate, but before the user is directed to the organization’s content. The login flow screens are embedded within the standard Salesforce login page for an integrated user login experience.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
Login flows support all the Salesforce user interface authentication methods, including username and password, delegated authentication,
SAML single sign-on, and social sign-on through a third-party authentication provider. You can apply login flows to Salesforce organizations, communities, and portals.
Note: You can’t apply login flows to API logins or when sessions are passed to the UI through frontdoor.jsp
from a non-UI login process. Only flows of type Flow are supported.
IN THIS SECTION:
Use the Cloud Flow Designer to build a login flow process, then associate the finished flow with a profile.
Connect a Login Flow to a Profile
After you create a login flow in Flow Designer and activate the flow, you associate it with a profile in your organization. Users with that profile are then directed to the login flow.
593
Set Up and Maintain Your Salesforce Organization Authenticate Users
Create a Login Flow
Use the Cloud Flow Designer to build a login flow process, then associate the finished flow with a profile.
When a user’s profile is associated with a login flow, the user is directed to the flow as part of the authentication process. The login flow screens are embedded in the standard Salesforce login page.
During the authentication process, these users have restricted access to the login flow screens. At the end of a successful authentication and completion of the login flow, the user is redirected to the organization. Otherwise, an explicit action can be defined within the flow to deny access.
For example, an administrator can create a login flow that implements a custom two-factor authentication process to add a desired security layer. A flow like this uses Apex methods to get the session context, extract the user’s IP address, and verify if the request is coming from a Trusted
IP Range. (To find or set the Trusted IP Range, from Setup, enter
Network Access
in the
Quick Find
box, then select Network Access.) If the request is coming from within a Trusted
IP Range address, Salesforce skips the flow and logs the user into the organization. Otherwise,
Salesforce invokes the flow providing one of three options.
1. Direct the user to log in with additional credentials, such as a time-based one-time password
(TOTP).
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To open, edit, or create a flow in the Cloud Flow
Designer:
•
Manage Force.com Flow
2. Force the user to log out.
3. Direct the user to a page with more options.
You can also build login flows that direct users to customized pages, such as forms to gather more information, or pages providing users with additional information.
Build Your Own Login Flow
Use the following process to build your own login flow.
1. Create a new flow using the Flow Designer and Apex.
For example, you can design a custom IP-based two-factor authentication flow that requires a second factor of authentication only if the user is logging in from outside of the corporate Trusted IP Range. (To find or set the Trusted IP Range, from Setup, enter
Network Access
in the
Quick Find
box, then select Network Access.)
Note: Do not set the Login IP Ranges directly in the user profile. The Login IP Ranges set directly in a profile restrict access to the organization for users of that profile who are outside that range, entirely, and those users cannot enter the login flow process.
The flow should contain the following.
a. A new Apex class defining an Apex plugin that implements from the (
Process.Plugin
) and uses the
Auth.SessionManagement
class to access the time-based one-time password (TOTP) methods and services. The new
Apex class for the plugin generates a time-based key with a quick response (QR) code to validate the TOTP provided by the user against the TOTP generated by Salesforce.
b. A screen element to scan a QR code.
c. A decision element to handle when the token is valid and when the token is invalid.
594
Set Up and Maintain Your Salesforce Organization Authenticate Users
Within the flow, you can set input variables. If you use the following specified names, these values will be populated for the flow when it starts.
Name
LoginFlow_LoginType
LoginFlow_IpAddress
LoginFlow_LoginIpAddress
LoginFlow_UserAgent
LoginFlow_Platform
LoginFlow_Application
LoginFlow_Community
LoginFlow_SessionLevel
LoginFlow_UserId
Value Description
The type of login, such as Application, OAuth, or SAML
The user’s current IP address
The user’s IP address used during login, which can change after authentication
The user agent string provided by the user’s browser
The operating system for the user
Application used to request authentication
Current Community, if this login flow applies to a Community
The current session security level, Standard or High Assurance
The user’s 18-character ID.
During the flow, you can assign the following, pre-defined variables values for specific behavior.
Note: The flow loads these values only after a UI screen is refreshed (a user clicking a button does not load the values, a new screen must be added to the flow for the values to be loaded).
Name
LoginFlow_FinishLocation
LoginFlow_ForceLogout
Value Description
A Text value. Provide a string that defines where the user goes after completing the login flow. The string should be a valid
Salesforce URL (the user cannot leave the organization and stay in the flow) or relative path.
A Boolean value. Set this variable to true
to log the user out, immediately, and force the user to exit the flow.
2. Save the flow.
3. Activate the flow.
595
Set Up and Maintain Your Salesforce Organization Authenticate Users
4. Connect the login flow to a profile.
SEE ALSO:
https://developer.salesforce.com/page/Login-Flows
Connect a Login Flow to a Profile
Connect a Login Flow to a Profile
After you create a login flow in Flow Designer and activate the flow, you associate it with a profile in your organization. Users with that profile are then directed to the login flow.
1. From Setup, enter
Login Flows
in the
Quick Find
box, then select Login Flows.
2. Click New.
3. Enter a name to reference the login flow association when you edit or delete it. The name doesn’t need to be unique.
4. Select the login flow for the profile. The drop-down list includes all the available flows saved in the Flow Designer. Only active flows of type Flow are supported.
5. Select a user license for the profile to which you want to connect the flow. The profile list then shows profiles with that license.
6. Select the profile to connect to the login flow.
7. Click Save.
Users of the profile are now directed to the login flow.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
After you associate the login flow, you can edit or delete the flows listed on this login flows page.
You can associate a login flow with one or more profiles. However, a profile can’t be connected to more than one login flow.
SEE ALSO:
Configure User Authentication
Choose login settings to ensure that your users are who they say they are.
IN THIS SECTION:
Restrict Where and When Users Can Log In to Salesforce
You can restrict the hours during which users can log in and the range of IP addresses from which they can log in and access
Salesforce. If IP address restrictions are defined for a user’s profile and a login originates from an unknown IP address, Salesforce does not allow the login. These restrictions help protect your data from unauthorized access and phishing attacks.
Improve your Salesforce org security with password protection. You can set password history, length, and complexity requirements along with other values. In addition, you can specify what to do if a user forgets their password.
596
Set Up and Maintain Your Salesforce Organization Authenticate Users
Expire Passwords for All Users
As an administrator, you can expire passwords for all users any time you want to enforce extra security for your organization. After expiring passwords, all users are prompted to reset their password the next time they log in.
Modify Session Security Settings
You can modify session security settings to specify session connection type, timeout settings, and IP address ranges to protect against malicious attacks and more.
Enable Lightning Login for Password-Free Logins
Say goodbye to the hassle of weak passwords, forgotten passwords, and locked-out accounts. Give your users the enhanced speed, convenience, and security of password-free logins. Enable Lightning Login, assign the required permission to your users, and encourage them to individually enroll in Lightning Login.
Use the Cloud Flow Designer to build a login flow process, then associate the finished flow with a profile.
Connect a Login Flow to a Profile
After you create a login flow in Flow Designer and activate the flow, you associate it with a profile in your organization. Users with that profile are then directed to the login flow.
Set Up Two-Factor Authentication
Admins enable two-factor authentication through permissions or profile settings. Users register devices for two-factor authentication—such as mobile authenticator apps or U2F security keys—through their own personal settings.
Restrict Where and When Users Can Log In to Salesforce
You can restrict the hours during which users can log in and the range of IP addresses from which they can log in and access Salesforce.
If IP address restrictions are defined for a user’s profile and a login originates from an unknown IP address, Salesforce does not allow the login. These restrictions help protect your data from unauthorized access and phishing attacks.
Login Hours
For each profile, you can set the hours when users can log in. See:
•
View and Edit Login Hours in the Enhanced Profile User Interface
•
View and Edit Login Hours in the Original Profile User Interface
Two-Factor Authentication for User Interface Logins
For each profile, you can require users to use a second form of authentication when they log in via the user interface. See
Authentication Login Requirements on page 621 and
Set Two-Factor Authentication Login Requirements and Custom Policies for Single
Sign-On, Social Sign-On, and Communities
.
Two-Factor Authentication for API Logins
For each profile, you can require a verification code (also called a time-based one-time password, or TOTP) instead of the standard security token. Users connect an authenticator app that generates verification codes to their account. Users with the “Two-Factor
Authentication for API Logins” permission use a code instead of the standard security token whenever it’s requested, such as when
597
Set Up and Maintain Your Salesforce Organization Authenticate Users
Login IP Address Ranges
For Enterprise, Performance, Unlimited, Developer, and Database.com editions, you can set the Login IP Range addresses from which users can log in on an individual profile. Users outside of the Login IP Range set on a profile can’t access your Salesforce org.
For Contact Manager, Group, and Professional Editions, set the Login IP Range. From Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings.
Login IP Address Range Enforcement for All Access Requests
You can restrict all access to Salesforce to the IP addresses included in Login IP Ranges in users’ profiles. For example, suppose a user logs in successfully from an IP address defined in Login IP Ranges. The user then moves to a different location and has a new IP address that is outside of Login IP Ranges. When the user refreshes the browser or tries to access Salesforce, including access from a client application, the user is denied. To enable this option, from Setup, enter
Session Settings
in the
Quick Find
box, select
Session Settings, and then select Enforce login IP ranges on every request. This option affects all user profiles that have login IP restrictions.
Org-wide Trusted IP Ranges
For all users, you can set a list of IP address ranges from which they can always log in without receiving a login challenge. These users
.
When users log in to Salesforce via the user interface, the API, or a desktop client such as Salesforce for Outlook, Connect Offline, Connect for Office, or the Data Loader, Salesforce confirms that the login is authorized as follows.
1. Salesforce checks whether the user’s profile has login hour restrictions. If login hour restrictions are specified for the user’s profile, any login outside the specified hours is denied.
2. If the user has the “Two-Factor Authentication for User Interface Logins” permission, Salesforce prompts the user for a second form of authentication upon logging in. If the user’s account isn’t already connected to a mobile authenticator app such as Salesforce
Authenticator, Salesforce first prompts the user to connect the app.
3. If the user has the “Two-Factor Authentication for API Logins” permission and has connected an authenticator app to the account,
Salesforce returns an error if the user uses the standard security token. The user has to enter a verification code (time-based one-time password) generated by the authenticator app instead.
4. Salesforce then checks whether the user’s profile has IP address restrictions. If IP address restrictions are defined for the user’s profile, logins from an undesignated IP address are denied, and logins from a specified IP address are allowed. If the Enforce login IP ranges
on every request session setting is enabled, the IP address restrictions are enforced for each page request, including requests from client applications.
5. If profile-based IP address restrictions are not set, Salesforce checks whether the user is logging in from a device used to access
Salesforce before.
•
If the user’s login is from a device and browser that Salesforce recognizes, the login is allowed.
•
If the user’s login is from an IP address in your org’s trusted IP address list, the login is allowed.
•
If the user’s login is not from a trusted IP address or a device and browser Salesforce recognizes, the login is blocked.
Whenever a login is blocked or returns an API login fault, Salesforce has to verify the user’s identity:
•
For access via the user interface, the user is prompted to verify using Salesforce Authenticator (version 2 or later), or to enter a verification code.
Note:
Users aren’t asked for a verification code the first time they log in to Salesforce.
598
Set Up and Maintain Your Salesforce Organization Authenticate Users
•
For access via the API or a client, users must add their security token to the end of their password to log in. Or, if “Two-Factor
Authentication on API Logins” is set on the user profile, users enter a verification code generated by an authenticator app.
A security token is an automatically generated key from Salesforce. For example, if a user’s password is
mypassword
, and the security token is
XXXXXXXXXX
, the user must enter
mypasswordXXXXXXXXXX
to log in. Or some client applications have a separate field for the security token.
Users can obtain their security token by changing their password or resetting their security token via the Salesforce user interface.
When a user changes a password or resets a security token, Salesforce sends a new security token to the email address on the user’s
Salesforce record. The security token is valid until the user resets the security token, changes a password, or has a password reset.
Tip:
Before you access Salesforce from a new IP address, we recommend that you get your security token from a trusted network using Reset My Security Token.
Tips on Setting Login Restrictions
Consider the following when setting login restrictions.
•
When a user’s password is changed, the security token is reset. Log in via the API or a client can be blocked until the user adds the automatically generated security token to the end of the password.
•
Partner Portal and Customer Portal users aren’t required to activate their browser to log in.
•
For more information on API login faults, see the Core Data Types Used in API Calls topic in the
SOAP API Developer's Guide
.
•
If single sign-on (SSO) is enabled for your org, API and desktop client users can log in to Salesforce unless their profile has IP address restrictions set and they try to log in from outside of the range defined. Also the SSO authority usually handles login lockout policies for users with the “Is Single Sign-On Enabled” permission. However, if the security token is enabled for your org, your org’s login lockout settings determine how many times users can attempt to log in with an invalid security token before being locked out of
Salesforce.
•
These events count toward the number of times users can attempt to log in with an invalid password before getting locked out of
Salesforce, as defined in your org’s login lockout settings.
–
Each time users are prompted to verify identity
–
Each time users incorrectly add the security token or verification code to the end of their password to log in to Salesforcevia the
API or a client
IN THIS SECTION:
Restrict Login IP Ranges in the Enhanced Profile User Interface
Control login access at the user level by specifying a range of allowed IP addresses on a user’s profile. When you define IP address restrictions for a profile, a login from any other IP address is denied.
Restrict Login IP Addresses in the Original Profile User Interface
Control login access at the user level by specifying a range of allowed IP addresses on a user’s profile. When you define IP address restrictions for a profile, a login from any other IP address is denied.
View and Edit Login Hours in the Enhanced Profile User Interface
For each profile, you can specify the hours when users can log in.
View and Edit Login Hours in the Original Profile User Interface
Specify the hours when users can log in based on the user profile.
Set Trusted IP Ranges for Your Organization
Trusted IP Ranges define a list of IP addresses from which users can log in without receiving a login challenge for verification of their identity, such as a code sent to their mobile phone.
599
Set Up and Maintain Your Salesforce Organization Authenticate Users
Restrict Login IP Ranges in the Enhanced Profile User Interface
Control login access at the user level by specifying a range of allowed IP addresses on a user’s profile.
When you define IP address restrictions for a profile, a login from any other IP address is denied.
1. From Setup, enter
Profiles
in the
Quick Find
box, then select Profiles.
2. Select a profile and click its name.
3. In the profile overview page, click Login IP Ranges.
4. Specify allowed IP addresses for the profile.
•
To add a range of IP addresses from which users can log in, click Add IP Ranges. Enter a valid IP address in the
IP Start Address
and a higher-numbered IP address in the
IP End Address
field. To allow logins from only a single IP address, enter the same address in both fields.
•
To edit or remove ranges, click Edit or Delete for that range.
Important:
•
The IP addresses in a range must be either IPv4 or IPv6. In ranges, IPv4 addresses exist in the IPv4-mapped IPv6 address space
::ffff:0:0
to
::ffff:ffff:ffff
, where
::ffff:0:0
is
0.0.0.0
and
::ffff:ffff:ffff
is
255.255.255.255.
A range can’t include IP addresses both inside and outside of the IPv4-mapped IPv6 address space. Ranges like
255.255.255.255
to
::1:0:0:0
or
::
to
::1:0:0:0
aren’t allowed.
•
Partner User profiles are limited to five IP addresses. To increase this limit, contact
Salesforce.
•
The Salesforce Mobile Classic app can bypass IP ranges that are defined for profiles.
Salesforce Mobile Classic initiates a secure connection to Salesforce over the mobile carrier’s network. However, the mobile carrier’s IP addresses can be outside of the IP ranges allowed for the user’s profile. To prevent bypassing IP definitions on a profile,
disable Salesforce Mobile Classic
on page 869 for that user.
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Custom Profiles available in:
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view login IP ranges:
•
View Setup and
Configuration
To edit and delete login IP ranges:
•
Manage Profiles and
Permission Sets
5. Optionally enter a description for the range. If you maintain multiple ranges, use the Description field to provide details, like which part of your network corresponds to this range.
Note: You can further restrict access to Salesforce to only those IPs in Login IP Ranges. To enable this option, in Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings and select Enforce login IP ranges on every
request. This option affects all user profiles that have login IP restrictions.
600
Set Up and Maintain Your Salesforce Organization Authenticate Users
Restrict Login IP Addresses in the Original Profile User Interface
Control login access at the user level by specifying a range of allowed IP addresses on a user’s profile.
When you define IP address restrictions for a profile, a login from any other IP address is denied.
EDITIONS
1. How you restrict the range of valid IP addresses on a profile depends on your Salesforce edition.
•
If you’re using an Enterprise, Unlimited, Performance, or Developer edition, from Setup, enter
Profiles
in the
Quick Find
box, then select Profiles, and select a profile.
Available in: Salesforce
Classic and Lightning
Experience
•
If you’re using a Professional, Group, or Personal edition, from Setup, enter
Session
Settings
in the
Quick Find
box, then select Session Settings.
Available in all editions
USER PERMISSIONS
2. Click New in the Login IP Ranges related list.
To view login IP ranges:
3. Enter a valid IP address in the
IP Start Address
field and a higher-numbered IP address in the
IP End Address
field.
•
View Setup and
Configuration
The start and end addresses define the range of allowable IP addresses from which users can log in. To allow logins from a single IP address, enter the same address in both fields.
•
The IP addresses in a range must be either IPv4 or IPv6. In ranges, IPv4 addresses exist in the IPv4-mapped IPv6 address space
::ffff:0:0
to
::ffff:ffff:ffff
, where
To edit and delete login IP ranges:
•
Manage Profiles and
Permission Sets
::ffff:0:0
is
0.0.0.0
and
::ffff:ffff:ffff
is
255.255.255.255.
A range can’t include IP addresses both inside and outside of the IPv4-mapped IPv6 address space. Ranges like
255.255.255.255
to
::1:0:0:0
or
::
to
::1:0:0:0
aren’t allowed.
•
Partner User profiles are limited to five IP addresses. To increase this limit, contact Salesforce.
•
The Salesforce Mobile Classic app can bypass IP ranges that are defined for profiles. Salesforce Mobile Classic initiates a secure connection to Salesforce over the mobile carrier’s network. However, the mobile carrier’s IP addresses can be outside of the IP
on page
869 for that user.
4. Optionally enter a description for the range. If you maintain multiple ranges, use the Description field to provide details, such as which part of your network corresponds to this range.
5. Click Save.
Note:
Cache settings on static resources are set to private when accessed via a Force.com site whose guest user's profile has restrictions based on IP range or login hours. Sites with guest user profile restrictions cache static resources only within the browser.
Also, if a previously unrestricted site becomes restricted, it can take up to 45 days for the static resources to expire from the Salesforce cache and any intermediate caches.
Note: You can further restrict access to Salesforce to only those IPs in Login IP Ranges. To enable this option, in Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings and select Enforce login IP ranges on every
request. This option affects all user profiles that have login IP restrictions.
SEE ALSO:
Set Trusted IP Ranges for Your Organization
View and Edit Login Hours in the Original Profile User Interface
Work in the Original Profile Interface
601
Set Up and Maintain Your Salesforce Organization Authenticate Users
View and Edit Login Hours in the Enhanced Profile User Interface
For each profile, you can specify the hours when users can log in.
1. From Setup, enter
Profiles
in the
Quick Find
box, then select Profiles.
2. Select a profile and click its name.
3. In the profile overview page, scroll down to Login Hours and click Edit.
4. Set the days and hours when users with this profile can log in to the organization.
To allow users to log in at any time, click Clear all times. To prohibit users from using the system on a specific day, set the start and end times to the same value.
If users are logged in when their login hours end, they can continue to view their current page, but they can’t take any further action.
Note: The first time login hours are set for a profile, the hours are based on the organization’s
Default Time Zone
as specified on the Company Information page in Setup. After that, any changes to the organization’s
Default Time Zone
won’t change the time zone for the profile’s login hours. As a result, the login hours are always applied at those exact times even if a user is in a different time zone or if the organization’s default time zone is changed.
Depending on whether you’re viewing or editing login hours, the hours may appear differently.
On the Login Hours edit page, hours are shown in your specified time zone. On the profile overview page, they appear in the organization’s original default time zone.
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Custom Profiles available in:
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view login hour settings:
•
View Setup and
Configuration
To edit login hour settings:
•
Manage Profiles and
Permission Sets
SEE ALSO:
Enhanced Profile User Interface Overview
View and Edit Login Hours in the Original Profile User Interface
Specify the hours when users can log in based on the user profile.
1. From Setup, enter
Profiles
in the
Quick Find
box, then select Profiles, and select a profile.
2. Click Edit in the Login Hours related list.
3. Set the days and hours when users with this profile can use the system.
To allow users to log in at any time, click Clear All Times. To prohibit users from using the system on a specific day, set the start and end times to the same value.
If users are logged in when their login hours end, they can continue to view their current page, but they can’t take any further action.
4. Click Save.
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
USER PERMISSIONS
To set login hours:
•
Manage Profiles and
Permission Sets
602
Set Up and Maintain Your Salesforce Organization Authenticate Users
Note: The first time login hours are set for a profile, the hours are based on the organization’s
Default Time Zone
as specified on the Company Information page in Setup. After that, any changes to the organization’s
Default Time Zone won’t change the time zone for the profile’s login hours. As a result, the login hours are always applied at those exact times even if a user is in a different time zone or if the organization’s default time zone is changed.
Depending on whether you’re viewing or editing login hours, the hours appear differently. On the profile detail page, hours are shown in your specified time zone. On the Login Hours edit page, they appear in the organization’s default time zone.
SEE ALSO:
Work in the Original Profile Interface
Restrict Login IP Addresses in the Original Profile User Interface
Set Trusted IP Ranges for Your Organization
Trusted IP Ranges define a list of IP addresses from which users can log in without receiving a login challenge for verification of their identity, such as a code sent to their mobile phone.
EDITIONS
Note: Who Sees What: Organization Access (Salesforce Classic)
Watch how you can restrict login through IP ranges and login hours.
To help protect your organization’s data from unauthorized access, you can specify a list of IP addresses from which users can log in without receiving a login challenge. However, this does not restrict access, entirely, for users outside of the Trusted IP Range. After these users complete the login challenge (usually by entering a code sent to their mobile device or email address), they can log in.
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
USER PERMISSIONS
1. From Setup, enter
Access.
Network Access
in the
Quick Find
box, then select Network
To view network access:
•
Login Challenge Enabled
To change network access:
•
Manage IP Addresses
2. Click New.
3. Enter a valid IP address in the
Start IP Address
field and a higher IP address in the
End IP Address
field.
The start and end addresses define the range of allowable IP addresses from which users can log in, including the start and end values. If you want to allow logins from a single IP address, enter the same address in both fields.
The start and end IP addresses must be in an IPv4 range and include no more than 33,554,432 addresses (2
25
, a /7 CIDR block).
4. Optionally, enter a description for the range. For example, if you maintain multiple ranges, enter details about the part of your network that corresponds to this range.
5. Click Save.
Note:
For organizations that were activated before December 2007, Salesforce automatically populated your organization’s trusted IP address list in December 2007, when this feature was introduced. The IP addresses from which trusted users had already accessed Salesforce during the past six months were added.
SEE ALSO:
Restrict Where and When Users Can Log In to Salesforce
Security Implementation Guide
603
Set Up and Maintain Your Salesforce Organization Authenticate Users
Set Password Policies
Improve your Salesforce org security with password protection. You can set password history, length, and complexity requirements along with other values. In addition, you can specify what to do if a user forgets their password.
For your organization’s security, you can set various password and login policies.
Note:
User passwords cannot exceed 16,000 bytes.
Logins are limited to 3,600 per hour per user. This limit applies to organizations created after
Summer ’08.
1. From Setup, enter
Password Policies
in the
Quick Find
box, then select Password
Policies.
2. Customize the password settings.
Field
User passwords expire in
Enforce password history
Minimum password length
Description
The length of time until user passwords expire and must be changed. The default is 90 days.
This setting isn’t available for Self-Service portals. This setting doesn’t apply to users with the “Password Never Expires” permission.
If you change the
User passwords expire in
setting, the change affects a user’s password expiration date if that user’s new expiration date is earlier than the old expiration date or if you remove an expiration by selecting
Never expires
.
Save users’ previous passwords so that they must always reset their password to a new, unique password. Password history is not saved until you set this value. The default is
3 passwords remembered
. You cannot select
No passwords remembered unless you select
Never expires
for the
User passwords expire in
field.
This setting isn’t available for Self-Service portals.
The minimum number of characters required for a password. When you set this value, existing users aren’t affected until the next time they change their passwords. The default is
8 characters
.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
USER PERMISSIONS
To set password policies:
•
Manage Password
Policies
604
Set Up and Maintain Your Salesforce Organization
Field
Password complexity requirement
Password question requirement
Maximum invalid login attempts
Lockout effective period
605
Authenticate Users
Description
The requirement for which types of characters must be used in a user’s password.
Complexity levels:
•
No restriction
—allows any password value and is the least secure option.
•
Must mix alpha and numeric characters
—requires at least one alphabetic character and one number, which is the default.
•
Must mix alpha, numeric, and special characters
—requires at least one alphabetic character, one number, and one of the following special characters:
!
# $ % - _ = + < >
.
•
Must mix numbers and uppercase and lowercase letters
—requires at least one number, one uppercase letter, and one lowercase letter.
•
Must mix numbers, uppercase and lowercase letters, and special characters
—requires at least one number, one uppercase letter, and one lowercase letter, and one of the following special characters:
! # $ % - _ = + < >
.
Note: Only the special characters listed meet the requirement. Other symbol characters are not considered special characters.
The values are
Cannot contain password
, meaning that the answer to the password hint question cannot contain the password itself; or
None
, the default, for no restrictions on the answer. The user’s answer to the password hint question is required. This setting is not available for Self-Service portals,
Customer Portals, or partner portals.
The number of login failures allowed for a user before they become locked out. This setting isn’t available for Self-Service portals.
The duration of the login lockout. The default is 15 minutes. This setting isn’t available for Self-Service portals.
Note: If users are locked out, they must wait until the lockout period expires. Alternatively, a user with the “Reset
User Passwords and Unlock Users” permission can unlock them from Setup with the following procedure:
a. Enter
Users
in the
Quick Find
box.
b. Select Users.
c. Selecting the user.
Set Up and Maintain Your Salesforce Organization Authenticate Users
Field Description
d. Click Unlock.
This button is only available when a user is locked out.
Obscure secret answer for password resets
This feature hides answers to security questions as you type. The default is to show the answer in plain text.
Note: If your org uses the Microsoft Input Method Editor
(IME) with the input mode set to Hiragana, when you type
ASCII characters, they’re converted in Japanese characters in normal text fields. However, the IME doesn’t work properly in fields with obscured text. If your org’s users cannot properly enter their passwords or other values after enabling this feature, disable the feature.
Require a minimum 1 day password lifetime
When you select this option, a password can’t be changed more than once in a 24-hour period.
3. Customize the forgotten password and locked account assistance information.
Note: This setting is not available for Self-Service portals, Customer Portals, or partner portals.
Field
Message
Help link
Description
If set, this message appears in the “We can’t reset your password” email. Users receive this email when they lock themselves out by trying to reset their password too many times. The text also appears at the bottom of the Answer Your Security Question page when users reset their passwords.
You can tailor the text to your organization by adding the name of your internal help desk or a system administrator. For the email, the message appears only for accounts that need an administrator to reset them. Lockouts due to time restrictions get a different system email message.
If set, this link displays with the text defined in the
Message field. In the “We can’t reset your password” email, the URL displays exactly as typed in the
Help link
field, so the user can see where the link goes. This URL display format is a security feature, because the user is not within a Salesforce organization.
On the Answer Your Security Question page, the
Help link
URL combines with the text in the
Message
field to make a clickable link. Security isn’t an issue, because the user is in a
Salesforce organization when changing passwords.
Valid protocols:
606
Set Up and Maintain Your Salesforce Organization
Field
Authenticate Users
Description
•
http
•
https
•
mailto
4. Specify an alternative home page for users with the “API Only User” permission. After completing user management tasks such as resetting a password, API-only users are redirected to the URL specified here, rather than to the login page.
5. Click Save.
SEE ALSO:
View and Edit Password Policies in Profiles
Expire Passwords for All Users
As an administrator, you can expire passwords for all users any time you want to enforce extra security for your organization. After expiring passwords, all users are prompted to reset their password the next time they log in.
To expire passwords for all users, except those users with the “Password Never Expires” permission:
1. From Setup, enter
Expire All Passwords
in the
Quick Find
box, then select
Expire All Passwords.
2. Select Expire all user passwords.
3. Click Save.
The next time users log in, they are prompted to reset their password.
Considerations When Expiring Passwords
•
Users might need to activate their computers to log in to Salesforce.
•
Expire all user passwords
doesn’t affect Self-Service portal users, because they aren’t direct Salesforce users.
SEE ALSO:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
USER PERMISSIONS
To expire all passwords:
•
Manage Internal Users
607
Set Up and Maintain Your Salesforce Organization Authenticate Users
Modify Session Security Settings
You can modify session security settings to specify session connection type, timeout settings, and
IP address ranges to protect against malicious attacks and more.
1. From Setup, enter
Session Settings
in the Quick Find box, then select Session Settings.
2. Customize the session security settings.
Field
Timeout value
Description
Length of time after which the system logs out inactive users. For Portal users, the timeout is between 10 minutes and 24 hours even though you can only set it as low as 15 minutes. Select a value between 15 minutes and 24 hours. Choose a shorter timeout period if your org has sensitive information and you want to enforce stricter security.
Note: The last active session time value isn’t updated until halfway through the timeout period. So if you have a 30-minute timeout, the system doesn’t check for activity until 15 minutes have passed. For example, if you update a record after 10 minutes, the last active session time value isn’t updated because there was no activity after 15 minutes. You’re logged out in 20 more minutes (30 minutes total), because the last active session time wasn’t updated. Suppose that you update a record after 20 minutes. That’s
5 minutes after the last active session time is checked. Your timeout resets, and you have another 30 minutes before being logged out, for a total of 50 minutes.
Disable session timeout warning popup
Determines whether the system prompts inactive users with a timeout warning message. Users are prompted
30 seconds before timeout as specified by the
Timeout value
.
Force logout on session timeout
Requires that when sessions time out for inactive users, current sessions become invalid. The browser refreshes and returns to the login page. To access the org, the user must log in again.
Note: Do not select
Disable session timeout warning popup
when using this setting.
Lock sessions to the IP address from which they originated
Determines whether user sessions are locked to the IP address from which the user logged in, helping to prevent unauthorized persons from hijacking a valid session.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
The Lock sessions to the IP address from which they originated
setting is available in: Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
All other settings available in: Personal, Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
USER PERMISSIONS
To modify session security settings:
•
Customize Application
608
Set Up and Maintain Your Salesforce Organization Authenticate Users
Field Description
Note: This setting can inhibit various applications and mobile devices.
Lock sessions to the domain in which they were first used
Require secure connections
(HTTPS)
Require secure connections
(HTTPS) for all third-party domains
Associates a current UI session for a user, such as a community user, with a specific domain. The setting helps prevent unauthorized use of the session
ID in another domain. This setting is enabled by default for orgs created with the Spring ’15 release or later.
Determines whether HTTPS is required to log in to or access Salesforce, apart from Force.com sites, which can be accessed using HTTP.
This setting is enabled by default for security reasons. This setting does not apply to API requests. All API requests require HTTPS.
Note: The Reset Passwords for Your Users page can only be accessed using HTTPS.
Determines whether HTTPS is required for connecting to third-party domains.
This setting is enabled by default on accounts created after the Summer ’17 release.
Force relogin after Login-As-User
Determines whether an administrator who is logged in as another user is returned to their previous session after logging out as the secondary user.
If the setting is enabled, an administrator must log in again to continue using
Salesforce after logging out as the user. Otherwise, the administrator is returned to the original session after logging out as the user. This setting is enabled by default for new orgs beginning with the Summer ’14 release.
Require HttpOnly attribute
Restricts session ID cookie access. A cookie with the HttpOnly attribute is not accessible via non-HTTP methods, such as calls from JavaScript.
Note:
If you have a custom or packaged application that uses
JavaScript to access session ID cookies, selecting
Require
HttpOnly attribute
breaks your application. It denies the application access to the cookie. If
Require HttpOnly attribute
is selected, the AJAX Toolkit debugging window isn’t available.
Use POST requests for cross-domain sessions
Sets the org to send session information using a POST request, instead of a
GET request, for cross-domain exchanges. An example of a cross-domain exchange is when a user is using a Visualforce page. In this context, POST requests are more secure than GET requests because POST requests keep the session information in the body of the request. However, if you enable this setting, embedded content from another domain, such as:
<img src="https://acme.force.com/pic.jpg"/> sometimes doesn’t display.
609
Set Up and Maintain Your Salesforce Organization Authenticate Users
Field Description
Enforce login IP ranges on every request
Restricts the IP addresses from which users can access Salesforce to only the
IP addresses defined in
Login IP Ranges
. If this setting is enabled, login
IP ranges are enforced on each page request, including requests from client applications. If this setting isn’t enabled, login IP ranges are enforced only when a user logs in. This setting affects all user profiles that have login IP restrictions.
Enable caching and autocomplete on login page
Allows the user’s browser to store usernames. If enabled, after initial login, usernames are auto-filled into the
Username
field on the login page. If the user selected Remember me on the login page, the username persists after the session expires or the user logs out. The username also appears on the
Switcher. This setting is selected by default for all orgs.
Note: If you disable this setting, the Remember me option doesn’t appear on your org’s login page or from the Switcher.
Enable secure and persistent browser caching to improve performance
Enable user switching
Enables secure data caching in the browser to improve page reload performance by avoiding extra round trips to the server. This setting is selected by default for all orgs. We don’t recommend disabling this setting, but if your company’s policy doesn’t allow browser caching even if the data is encrypted, you can disable it.
Determines whether the Switcher appears when your org’s users select their profile picture. This setting is selected by default for all organizations. The
Enable caching and autocomplete on login page
setting must also be enabled. Deselect the
Enable user switching
setting to prevent your org from appearing in Switchers on other orgs. It also prevents your org users from seeing the Switcher when they select their profile picture.
Remember until logout
Normally, usernames are cached only while a session is active or if a user selects Remember Me. For SSO sessions, the remember option isn't available.
So, once the session expires, the username disappears from the login page and the Switcher. By enabling
Remember me until logout
, the cached usernames are deleted only if the user explicitly logs out. If the session times out, they appear on the Switcher as inactive. This way, if the users are on their own computer and allow a session to timeout, they can select the username to reauthenticate. If they're on a shared computer, the username is deleted immediately when the user logs out.
This setting applies to all your org’s users. This option isn't enabled by default.
However, we encourage you to enable it as a convenience to your users. Keep this setting disabled if your org doesn't expose all your SSO or authentication providers on your login page.
Enable the SMS method of identity confirmation
Allows users to receive a one-time PIN delivered via SMS. If this setting is selected, administrators or users must verify their mobile phone number before taking advantage of this feature. This setting is selected by default for all orgs.
610
Set Up and Maintain Your Salesforce Organization Authenticate Users
Field Description
Require security tokens for API logins from callouts (API version
31.0 and earlier)
In API version 31.0 and earlier, requires the use of security tokens for API logins from callouts. Examples are Apex callouts or callouts using the AJAX proxy. In
API version 32.0 and later, security tokens are required by default.
Login IP Ranges
(for Contact Manager,
Group, and Professional Editions)
Specifies a range of IP addresses users must log in from (inclusive), or the login fails.
To specify a range, click New and enter a Start IP Address and End IP Address to define the range, which includes the start and end values.
This field is not available in Enterprise, Unlimited, Performance, and Developer
Editions. In those editions, you can specify a valid Login IP Range in the user profile settings.
Let users use a security key
(U2F)
Allows users to use a U2F security key for two-factor authentication and identity verification. Instead of using Salesforce Authenticator, a one-time password generated by an authenticator app, or one-time passwords sent by email or
SMS, users insert their registered U2F security key into a USB port to complete verification.
Require identity verification during two-factor authentication registration
Requires users to confirm their identities to add a two-factor authentication method, such as Salesforce Authenticator, instead of requiring a relogin as before.
Require identity verification for change of email address
Requires users to confirm their identities to change email addresses instead of requiring a relogin as before.
Note:
To get the emails to confirm identity, make sure that users have access to their previously registered email accounts.
Allow location-based automated verifications with Salesforce
Authenticator
Allow only from trusted IP addresses
Allows users to verify identity by automatically approving notifications in
Salesforce Authenticator, whenever users are in trusted locations such as a home or office. If you allow automated verifications, you can allow them from any location or restrict them to only trusted IP addresses, such as your corporate network.
Allow Lightning Login
Enable clickjack protection for
Setup pages
Enable clickjack protection for non-Setup Salesforce pages
Allows users to use Lightning Login for password-free Salesforce logins, relying on Salesforce Authenticator for identity verification.
Protects against clickjack attacks on setup Salesforce pages. Clickjacking is also known as a user interface redress attack. (Setup pages are available from the Setup menu.)
Protects against clickjack attacks on non-setup Salesforce pages. Clickjacking is also known as a user interface redress attack. Setup pages already include protection against clickjack attacks. (Setup pages are available from the Setup menu.) This setting is selected by default for all orgs.
611
Set Up and Maintain Your Salesforce Organization Authenticate Users
Field
Enable clickjack protection for customer Visualforce pages with standard headers
Description
Protects against clickjack attacks on your Visualforce pages with headers enabled. Clickjacking is also known as a user interface redress attack.
Warning: If you use custom Visualforce pages within a frame or iframe, you sometimes see a blank page or the page displays without the frame. For example, Visualforce pages in a page layout don’t function when clickjack protection is on.
Enable clickjack protection for customer Visualforce pages with headers disabled
Protects against clickjack attacks on your Visualforce pages with headers disabled when setting showHeader="false"
on the page. Clickjacking is also known as a user interface redress attack.
Warning: If you use custom Visualforce pages within a frame or iframe, you sometimes see a blank page or the page displays without the frame. For example, Visualforce pages in a page layout don’t function when clickjack protection is on.
Enable CSRF protection on GET requests on non-setup pages
Enable CSRF protection on POST requests on non-setup pages
Enable XSS protection
Enable Content Sniffing protection
Logout URL
Protects against Cross Site Request Forgery (CSRF) attacks by modifying non-Setup pages. Non-Setup pages include a random string of characters in the URL parameters or as a hidden form field. With every GET and POST request, the application checks the validity of this string of characters. The application doesn’t execute the command unless the value found matches the expected value. This setting is selected by default for all orgs.
Protects against cross-site scripting attacks. If a reflected cross-site scripting attack is detected, the browser shows a blank page with no content.
Prevents the browser from inferring the MIME type from the document content. It also prevents the browser from executing malicious files (JavaScript,
Stylesheet) as dynamic content.
Redirects users to a specific page after they log out of Salesforce, such as an authentication provider’s page or a custom-branded page. This URL is used only if no logout URL is specified in the identity provider, SAML single sign-on, or external authentication provider settings. If no value is specified for
Logout
URL
, the default is https://login.salesforce.com
, unless
MyDomain is enabled. If My Domain is enabled, the default is https://customdomain.my.salesforce.com
.
3. Click Save.
Session Security Levels
You can restrict access to certain types of resources based on the level of security associated with the authentication (login) method for the user’s current session. By default, each login method has one of two security levels: Standard or High Assurance. You can change the session security level and define policies so specified resources are only available to users with a High Assurance level.
The different authentication methods are assigned these security levels, by default.
•
Username and Password — Standard
612
Set Up and Maintain Your Salesforce Organization Authenticate Users
•
Delegated Authentication — Standard
•
Activation — Standard
•
Lightning Login — Standard
•
Two-Factor Authentication — High Assurance
•
Authentication Provider — Standard
•
SAML — Standard
Note:
The security level for a SAML session can also be specified using the
SessionLevel
attribute of the SAML assertion sent by the identity provider. The attribute can take one of two values,
STANDARD
or
HIGH_ASSURANCE
.
To change the security level associated with a login method:
1. From Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings.
2. Under Session Security Levels, select the login method.
3. To move the method to the proper category, click the Add or Remove arrow.
Currently, the only features that use session-level security are reports and dashboards in Salesforce and connected apps. You can set policies requiring High Assurance on these types of resources. You can also specify an action to take if the session used to access the resource is not High Assurance. The supported actions are:
•
Block — Blocks access to the resource by showing an insufficient privileges error.
•
Raise session level — Prompts users to complete two-factor authentication. When users authenticate successfully, they can access the resource. For reports and dashboards, you can apply this action when users access reports or dashboards, or just when they export and print them.
Warning: Raising the session level to high assurance by redirecting the user to complete two-factor authentication is not a supported action in Lightning Experience. If your org has Lightning Experience enabled, and you set a policy that requires a high assurance session to access reports and dashboards, Lightning Experience users with a standard assurance session are blocked from reports and dashboards. Also, they don’t see the icons for these resources in the navigation menu. As a workaround, users with a standard assurance session can log out and log in again using an authentication method that is defined as high assurance by their org. Then they have access to reports and dashboards. Or, they can switch to Salesforce Classic, where they’re prompted to raise the session level when they attempt to access reports and dashboards.
To set a High Assurance required policy for accessing a connected app:
1. From Setup, enter
Connected Apps
in the
Quick Find
box, then select the option for managing connected apps.
2. Click Edit next to the connected app.
3. Select High Assurance session required.
4. Select one of the actions presented.
5. Click Save.
To set a High Assurance required policy for accessing reports and dashboards:
1. From Setup, enter
Access Policies
in the
Quick Find
box, then select Access Policies.
2. Select High Assurance session required.
3. Select one of the actions presented.
4. Click Save.
613
Set Up and Maintain Your Salesforce Organization Authenticate Users
Session levels have no impact on resources in the app other than connected apps, reports, and dashboards for which explicit security policies have been defined.
SEE ALSO:
Enable Lightning Login for Password-Free Logins
Say goodbye to the hassle of weak passwords, forgotten passwords, and locked-out accounts. Give your users the enhanced speed, convenience, and security of password-free logins. Enable Lightning
Login, assign the required permission to your users, and encourage them to individually enroll in
Lightning Login.
Password-free logins rely on Salesforce Authenticator (version 2 or later), the two-factor authentication mobile app that’s available as a free download for iOS and Android devices. Lightning
Logins add a layer of security by requiring two factors of authentication for login.
•
The first factor is something that the user has—a mobile device that has Salesforce Authenticator installed and connected with the user’s Salesforce account.
•
The second factor is something that the user is, such as a fingerprint, or something that the user knows, such as a PIN. The second level of authentication enhances security by requiring access to the mobile device and the user’s fingerprint or PIN.
Lightning Login isn’t limited to orgs using Lightning Experience. It works in Salesforce Classic, too.
All internal users (not external community users) are eligible for Lightning Login by default, but you can decide whether to make it available to all users. You can also determine user eligibility by using the Lightning Login User permission.
1. From Setup, enter
Session Settings
in the Quick Find box, then select Session Settings.
2. Review the default settings for Lightning Login.
a. Make sure that Allow Lightning Login is enabled.
You can disable Allow Lightning Login at any time to switch users back to username and password logins.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Database.com,
Developer, Enterprise,
Group, Performance,
Professional, and Unlimited
Editions
USER PERMISSIONS
To edit system permissions in profiles:
•
Manage Profiles and
Permission Sets
To enable Lightning Login:
•
Customize Application
b. Decide if you want to make Lightning Login available to all users or only users with the Lightning Login User permission.
c. Confirm that a Standard session security level is appropriate for this login method.
Lightning Login establishes a Standard security level for the user’s session. Standard is the default security level for the Username
Password method that Lightning Login typically replaces. If needed, you can change the security level to High Assurance.
3. Assign the Lightning Login User permission to users in the user profile (for cloned or custom profiles only) or permission set. Lightning
Login isn’t supported for external users.
614
Set Up and Maintain Your Salesforce Organization Authenticate Users
Consider these points about how Lightning Login relates to other login, identity verification, and two-factor authentication features.
•
You can monitor your users’ Lightning Login activity using Login History or Identity Verification History tools.
•
If enrolled users attempt a Lightning Login from an unrecognized browser or device, Salesforce requires login using username and password, along with identity verification.
•
If an enrolled user previously logged in from a browser and selected Remember me, login hints on the login page show a lightning bolt next to past usernames that are Lightning Login–enabled.
Note:
For Lightning Login to display login hints properly in the Apple Safari browser, change the Cookies and website data option in the browser. Advise your users to change it from Allow from websites I visit to Always allows.
•
If your org sets a two-factor authentication policy for logins, the Lightning Login method satisfies the second factor requirement.
Salesforce does not separately require users with the Two-Factor Authentication for User Interface Logins permission to provide a second factor.
•
If your org has defined a transaction security policy that requires two-factor authentication, Lightning Login isn’t supported. Enrolled users who attempt a Lightning Login must use log in with username and password instead.
IN THIS SECTION:
Enroll in Lightning Login for Password-Free Logins
Enroll in Lightning Login so that you can enjoy the enhanced speed, convenience, and security of password-free logins.
Cancel a User’s Lightning Login Enrollment
Cancel a user’s Lightning Login enrollment if the user is no longer eligible to use Lightning Login.
Enroll in Lightning Login for Password-Free Logins
Enroll in Lightning Login so that you can enjoy the enhanced speed, convenience, and security of password-free logins.
If a Salesforce admin has made you eligible to enroll in Lightning Login, enroll yourself (an admin can’t enroll for you).
1. Have your mobile device in hand so that you’re ready to approve the enrollment notification.
Lightning Login requires Salesforce Authenticator (version 2 or later), the two-factor authentication mobile app that’s available as a free download for iOS and Android devices. If you aren’t already using Salesforce Authenticator, enrollment includes a few extra steps. You’re guided through downloading and installing Salesforce Authenticator, connecting it to your
Salesforce account, and setting up a second factor of authentication (a fingerprint or PIN).
2. From your personal settings, enter
Advanced User Details
in the
Quick Find box, then select Advanced User Details. No results? Enter
Personal Information
in the
Quick Find
box, then select Personal Information.
3. Click Enroll next to the
Lightning Login
field.
If you don’t see this option, your admin hasn’t made you eligible to enroll.
4. At the prompt, check the Salesforce Authenticator notification on your mobile device and approve the request.
5. At the prompt, provide your fingerprint or PIN on the mobile device.
Now you’re ready to use this login method.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Database.com,
Developer, Enterprise,
Group, Performance,
Professional, and Unlimited
Editions
USER PERMISSIONS
To enroll in Lightning Login:
•
Lightning Login User
615
Set Up and Maintain Your Salesforce Organization Authenticate Users
1. Click—On the Salesforce login page, look for the lightning bolt next to your Lightning Login–enabled username, and click your username. If the login page asks for both username and password, you can enter only your username, skip the password field, and click Log In.
2. Tap—On your mobile device, tap the notification from the Salesforce Authenticator app.
3. Touch—Verify your identity with your fingerprint or PIN. Presto! You’re logged in.
While enrolled, if you’re ever without your mobile device, you can still log in with your username and password. If you disconnect
Salesforce Authenticator from your Salesforce account, Lightning Login isn’t allowed until you connect Salesforce Authenticator again.
You can cancel your enrollment at any time, and so can an admin.
Cancel a User’s Lightning Login Enrollment
Cancel a user’s Lightning Login enrollment if the user is no longer eligible to use Lightning Login.
1. From Setup, enter
Users
in the
Quick Find
box, then select Users.
2. Click the user’s name.
3. On the user’s detail page, click Cancel next to the
Lightning Login
field.
Your users can cancel their own enrollment. In personal settings, they go to the Advanced User
Details page and click Cancel next to the
Lightning Login
field.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and Contact
Manager Editions
USER PERMISSIONS
To cancel a user’s Lightning
Login enrollment:
•
Manage Users
Create a Login Flow
Use the Cloud Flow Designer to build a login flow process, then associate the finished flow with a profile.
When a user’s profile is associated with a login flow, the user is directed to the flow as part of the authentication process. The login flow screens are embedded in the standard Salesforce login page.
During the authentication process, these users have restricted access to the login flow screens. At the end of a successful authentication and completion of the login flow, the user is redirected to the organization. Otherwise, an explicit action can be defined within the flow to deny access.
For example, an administrator can create a login flow that implements a custom two-factor authentication process to add a desired security layer. A flow like this uses Apex methods to get the session context, extract the user’s IP address, and verify if the request is coming from a Trusted
IP Range. (To find or set the Trusted IP Range, from Setup, enter
Network Access
in the
Quick Find
box, then select Network Access.) If the request is coming from within a Trusted
IP Range address, Salesforce skips the flow and logs the user into the organization. Otherwise,
Salesforce invokes the flow providing one of three options.
1. Direct the user to log in with additional credentials, such as a time-based one-time password
(TOTP).
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To open, edit, or create a flow in the Cloud Flow
Designer:
•
Manage Force.com Flow
616
Set Up and Maintain Your Salesforce Organization Authenticate Users
2. Force the user to log out.
3. Direct the user to a page with more options.
You can also build login flows that direct users to customized pages, such as forms to gather more information, or pages providing users with additional information.
Build Your Own Login Flow
Use the following process to build your own login flow.
1. Create a new flow using the Flow Designer and Apex.
For example, you can design a custom IP-based two-factor authentication flow that requires a second factor of authentication only if the user is logging in from outside of the corporate Trusted IP Range. (To find or set the Trusted IP Range, from Setup, enter
Network Access
in the
Quick Find
box, then select Network Access.)
Note:
Do not set the Login IP Ranges directly in the user profile. The Login IP Ranges set directly in a profile restrict access to the organization for users of that profile who are outside that range, entirely, and those users cannot enter the login flow process.
The flow should contain the following.
a. A new Apex class defining an Apex plugin that implements from the (
Process.Plugin
) and uses the
Auth.SessionManagement
class to access the time-based one-time password (TOTP) methods and services. The new
Apex class for the plugin generates a time-based key with a quick response (QR) code to validate the TOTP provided by the user against the TOTP generated by Salesforce.
b. A screen element to scan a QR code.
c. A decision element to handle when the token is valid and when the token is invalid.
Within the flow, you can set input variables. If you use the following specified names, these values will be populated for the flow when it starts.
Name
LoginFlow_LoginType
LoginFlow_IpAddress
LoginFlow_LoginIpAddress
LoginFlow_UserAgent
LoginFlow_Platform
Value Description
The type of login, such as Application, OAuth, or SAML
The user’s current IP address
The user’s IP address used during login, which can change after authentication
The user agent string provided by the user’s browser
The operating system for the user
617
Set Up and Maintain Your Salesforce Organization Authenticate Users
Name
LoginFlow_Application
LoginFlow_Community
LoginFlow_SessionLevel
LoginFlow_UserId
Value Description
Application used to request authentication
Current Community, if this login flow applies to a Community
The current session security level, Standard or High Assurance
The user’s 18-character ID.
During the flow, you can assign the following, pre-defined variables values for specific behavior.
Note:
The flow loads these values only after a UI screen is refreshed (a user clicking a button does not load the values, a new screen must be added to the flow for the values to be loaded).
Name
LoginFlow_FinishLocation
LoginFlow_ForceLogout
Value Description
A Text value. Provide a string that defines where the user goes after completing the login flow. The string should be a valid
Salesforce URL (the user cannot leave the organization and stay in the flow) or relative path.
A Boolean value. Set this variable to true
to log the user out, immediately, and force the user to exit the flow.
2. Save the flow.
3. Activate the flow.
4. Connect the login flow to a profile.
SEE ALSO:
https://developer.salesforce.com/page/Login-Flows
Connect a Login Flow to a Profile
Connect a Login Flow to a Profile
After you create a login flow in Flow Designer and activate the flow, you associate it with a profile in your organization. Users with that profile are then directed to the login flow.
1. From Setup, enter
Login Flows
in the
Quick Find
box, then select Login Flows.
2. Click New.
3. Enter a name to reference the login flow association when you edit or delete it. The name doesn’t need to be unique.
4. Select the login flow for the profile. The drop-down list includes all the available flows saved in the Flow Designer. Only active flows of type Flow are supported.
5. Select a user license for the profile to which you want to connect the flow. The profile list then shows profiles with that license.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
618
Set Up and Maintain Your Salesforce Organization Authenticate Users
6. Select the profile to connect to the login flow.
7. Click Save.
Users of the profile are now directed to the login flow.
After you associate the login flow, you can edit or delete the flows listed on this login flows page.
You can associate a login flow with one or more profiles. However, a profile can’t be connected to more than one login flow.
SEE ALSO:
Set Up Two-Factor Authentication
Admins enable two-factor authentication through permissions or profile settings. Users register devices for two-factor authentication—such as mobile authenticator apps or U2F security keys—through their own personal settings.
EDITIONS
You can customize two-factor authentication in the following ways.
•
Require it for every login. Set the two-factor login requirement for every time the user logs in to Salesforce. You can also enable this feature for API logins, which includes the use of client applications like the Data Loader. For more information, see
or Set Two-Factor Authentication Login Requirements for API Access .
•
Use “stepped up” authentication (also known as “high assurance” authentication). Sometimes you don’t need two-factor authentication for every user’s login, but you want to secure certain resources. If the user tries to use a connected app or reports, Salesforce prompts the user to
verify identity. For more information, see Session Security Levels .
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and Contact
Manager Editions
•
Use profile policies and session settings. First, in the user profile, set the
Session security level required at login
field to High Assurance. Then set session security levels in your org’s session settings to apply the policy for particular login methods. In your org’s session settings, check the session security levels to make sure that Two-Factor Authentication is in the
High Assurance column. For more information, see
Set Two-Factor Authentication Login Requirements and Custom Policies for
Single Sign-On, Social Sign-On, and Communities
.
Warning:
If Two-Factor Authentication is in the Standard column, users get an error when they log in with a method that grants standard-level security.
•
Use login flows. Use the Flow Designer and profiles to build post-authentication requirements as the user logs in, including custom two-factor authentication processes. For more information, see the following examples.
–
Login Flows
–
Implementing SMS-Based Two-Factor Authentication
–
Enhancing Security with Two-Factor Authentication (Salesforce Classic)
IN THIS SECTION:
Set Two-Factor Authentication Login Requirements
As a Salesforce admin, you can require your users to use a second factor of authentication when they log in.
619
Set Up and Maintain Your Salesforce Organization Authenticate Users
Use profile policies and session settings to set two-factor authentication login requirements for users. All Salesforce user interface authentication methods, including username and password, delegated authentication, SAML single sign-on, and social sign-on through a third-party authentication provider, are supported. You can apply the two-factor authentication requirement to users in
Salesforce orgs and Communities.
Set Two-Factor Authentication Login Requirements for API Access
Salesforce admins can set the “Two-Factor Authentication for API Logins” permission to allow using a second authentication challenge for API access to Salesforce. API access includes the use of applications like the Data Loader and developer tools for customizing an organization or building client applications.
Connect Salesforce Authenticator (Version 2 or Later) to Your Account for Identity Verification
The Salesforce Authenticator (version 2 or later) app on your mobile device is the second factor of authentication. Use the app to add an extra level of security to your account.
Verify Your Identity with a One-Time Password Generator App or Device
Connect a one-time password generator app, such as Salesforce Authenticator or Google Authenticator, to verify your identity. The app generates a verification code, sometimes called a “time-based one-time password”.
Enable U2F Security Keys for Identity Verification
As a Salesforce admin, you can allow users to use a U2F security key anytime they’re challenged to verify their identity, including two-factor authentication and activations. Instead of using Salesforce Authenticator or one-time passwords sent by email or SMS, users insert their U2F security key into a USB port to complete verification.
Register a U2F Security Key for Identity Verification
Register a U2F security key to connect it to your Salesforce account. It’s a secure, convenient alternative to using Salesforce Authenticator or one-time passwords sent by email or SMS. Anytime you’re challenged to verify your identity, including two-factor authentication and activations, you can insert your security key into a USB port to complete verification.
Disconnect Salesforce Authenticator (Version 2 or Later) from a User’s Account
Only one Salesforce Authenticator (version 2 or later) mobile app can be connected to a user’s account at a time. If your user loses access to the app by replacing or losing the mobile device, disconnect the app from the user’s account. The next time the user logs in with two-factor authentication, if no other authenticator app is connected, Salesforce prompts the user to connect a new authenticator app.
Disconnect a User’s One-Time Password Generator App
Besides Salesforce Authenticator, one other mobile authenticator app that generates verification codes (one-time passwords) can be connected to a user’s account at a time. If your user loses access to the app by replacing or losing the mobile device, disconnect the app from your user’s account. The next time your user logs in with two-factor authentication, if no other identity verification method is connected, Salesforce prompts the user to connect a new authenticator app.
Remove a User’s U2F Security Key Registration
One U2F security key can be registered with a user’s Salesforce account at a time. If your user replaces or loses a registered security key, remove the registration from your user’s account.
Generate a Temporary Identity Verification Code
Generate a temporary verification code for users who can’t access the device they usually use for two-factor authentication. You set when the code expires, from 1 to 24 hours after you generate it. The code can be used multiple times until it expires.
Expire a Temporary Verification Code
Expire a user’s temporary verification code when the user no longer needs it for two-factor authentication
See How Your Users Are Verifying Their Identity
Customize a list view of users or check the Identity Verification Methods report to find out who’s using which methods to verify identity. Create custom reports to spot patterns in identity verification behavior for your org or community.
620
Set Up and Maintain Your Salesforce Organization Authenticate Users
Delegate Two-Factor Authentication Management Tasks
Let users who aren’t Salesforce admins provide support for two-factor authentication in your org. For example, suppose you want your company’s Help Desk staff to generate temporary verification codes for users who lost or forgot the device they usually use for two-factor authentication. Assign Help Desk staff members the “Manage Two-Factor Authentication in User Interface” permission so that they can generate codes and support end users with other two-factor authentication tasks.
Set Two-Factor Authentication Login Requirements
As a Salesforce admin, you can require your users to use a second factor of authentication when they log in.
You can require two-factor authentication each time a user logs in with a username and password to Salesforce, including orgs with custom domains created using My Domain. To set the requirement, select the “Two-Factor Authentication for User Interface Logins” permission in the user profile (for cloned profiles only) or permission set.
See how to set up a two-factor authentication requirement for your org and how your users can use the Salesforce Authenticator app. Salesforce Authenticator: Set Up a Two-Factor
Authentication Requirement (Salesforce Classic)
Users with the “Two-Factor Authentication for User Interface Logins” permission have to provide a second factor, such as a mobile authenticator app or U2F security key, each time they log in to
Salesforce.
You can also use a profile-based policy to set a two-factor authentication requirement for users assigned to a particular profile. Use the profile policy when you want to require two-factor authentication for users of the following authentication methods:
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To edit profiles and permission sets:
•
Manage Profiles and
Permission Sets
•
SAML for single sign-on
•
Social sign-on in to Salesforce orgs or Communities
•
Username and password authentication into Communities
All Salesforce user interface authentication methods, including username and password, delegated authentication, SAML single sign-on, and social sign-on through an authentication provider, are supported. In the user profile, set the
Session security level required at login
field to High Assurance. Then set session security levels in your org’s session settings to apply the policy for particular login methods. Also in your org’s session settings, check the session security levels to make sure that Two-Factor
Authentication is in the High Assurance column.
621
Set Up and Maintain Your Salesforce Organization Authenticate Users
Warning: If Two-Factor Authentication is in the Standard column, users get an error when they log in with a method that grants standard-level security.
SEE ALSO:
Connect Salesforce Authenticator (Version 2 or Later) to Your Account for Identity Verification
Verify Your Identity with a One-Time Password Generator App or Device
Disconnect Salesforce Authenticator (Version 2 or Later) from a User’s Account
Disconnect a User’s One-Time Password Generator App
Generate a Temporary Identity Verification Code
Expire a Temporary Verification Code
Delegate Two-Factor Authentication Management Tasks
Set Two-Factor Authentication Login Requirements and Custom Policies for Single Sign-On, Social Sign-On, and Communities
Use profile policies and session settings to set two-factor authentication login requirements for users. All Salesforce user interface authentication methods, including username and password, delegated authentication, SAML single sign-on, and social sign-on through a third-party authentication provider, are supported. You can apply the two-factor authentication requirement to users in Salesforce orgs and Communities.
To require two-factor authentication for users assigned to a particular profile, edit the Session security level required at login profile setting. Then set session security levels in your org’s session settings to apply the policy for particular login methods.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
By default, the session security requirement at login for all profiles is None. You can edit a profile’s
Session Settings to change the requirement to High Assurance. When profile users with this requirement use a login method that grants standard-level security instead of high assurance, such as username and password, they’re prompted to verify their identity with two-factor authentication.
After users authenticate successfully, they’re logged in to Salesforce.
You can edit the security level assigned to a login method in your org’s Session Settings.
Users with mobile devices can use the Salesforce Authenticator mobile app or another authenticator app for two-factor authentication. Internal users can connect the app to their account in the
Advanced User Details page of their personal settings. If you set the High Assurance requirement on a profile, any profile user who doesn’t already have Salesforce Authenticator or another authenticator app connected to their account is prompted to connect the app before they can log in. After they connect the app, they’re prompted to use the app to verify their identity.
USER PERMISSIONS
To edit profiles and permission sets:
•
Manage Profiles and
Permission Sets
To generate a temporary verification code
•
Manage Two-Factor
Authentication in User
Interface
Users with registered U2F security keys can use them for two-factor authentication.
Community members with the High Assurance profile requirement are prompted to connect an authenticator app during login.
1. From Setup, enter
Profiles
in the Quick Find box, then select Profiles.
2. Select a profile.
622
Set Up and Maintain Your Salesforce Organization Authenticate Users
3. Scroll to Session Settings and find the
Session security level required at login
setting.
4. Click Edit.
5. For Session security level required at login, select High Assurance.
6. Click Save.
7. From Setup, enter
Session Settings
in the Quick Find box, then select Session Settings.
8. In Session Security Levels, make sure that Two-Factor Authentication is in the High Assurance column.
If Two-Factor Authentication is in the Standard column, users get an error when they log in with a method that grants standard-level security.
9.
Note: Consider moving Activation to the High Assurance column. With this setting, users who verify their identity from an unrecognized browser or app establish a high-assurance session. When Activation is in the High Assurance column, profile users who verify their identity at login aren’t challenged to verify their identity again to satisfy the high-assurance session security requirement.
Save your changes.
Example: You’ve configured Facebook and LinkedIn as authentication providers in your community. Many of your community members use social sign-on to log in using the username and password from their Facebook or LinkedIn accounts. You want to increase security by requiring Customer Community users to use two-factor authentication when they log in with their Facebook account, but not with their LinkedIn account. You edit the Customer Community User profile and set the Session security level required at login to High Assurance. In your org’s Session Settings, you edit the Session Security Levels. You place Facebook in the Standard column. In the High Assurance column, you place Two-Factor Authentication. You also place LinkedIn in the High
Assurance column.
Note: You can also use login flows to change the user’s session security level to initiate identity verification under specific conditions. Login flows let you build a custom post-authentication process that meets your business requirements.
If users lose or forget the device they usually use for two-factor authentication, you can generate a temporary verification code for them.
You set when the code expires, from 1 to 24 hours after you generate it. Your user can use the code multiple times until it expires. A user can have only one temporary code at a time. If a user needs a new code while the old code is still valid, you can expire the old code, then generate a new one. Users can expire their own valid codes in their personal settings.
Note: The High Assurance profile requirement applies to user interface logins. OAuth token exchanges aren’t subject to the requirement. OAuth refresh tokens that were obtained before a High Assurance requirement is set for a profile can still be exchanged for access tokens that are valid for the API. Tokens are valid even if they were obtained with a standard-assurance session. To require users to establish a high-assurance session before accessing the API with an external application, first revoke existing OAuth
623
Set Up and Maintain Your Salesforce Organization Authenticate Users tokens for users with that profile. Then set a High Assurance requirement for the profile. Users have to log in with two-factor authentication and reauthorize the application.
SEE ALSO:
Connect Salesforce Authenticator (Version 2 or Later) to Your Account for Identity Verification
Verify Your Identity with a One-Time Password Generator App or Device
Disconnect Salesforce Authenticator (Version 2 or Later) from a User’s Account
Disconnect a User’s One-Time Password Generator App
Generate a Temporary Identity Verification Code
Expire a Temporary Verification Code
Delegate Two-Factor Authentication Management Tasks
Expire a Temporary Verification Code
Set Two-Factor Authentication Login Requirements for API Access
Salesforce admins can set the “Two-Factor Authentication for API Logins” permission to allow using a second authentication challenge for API access to Salesforce. API access includes the use of applications like the Data Loader and developer tools for customizing an organization or building client applications.
The “Two-Factor Authentication for User Interface Logins” permission is a prerequisite for the
“Two-Factor Authentication for API Logins” permission. Users who have these permissions enabled have to complete two-factor authentication when they log in to Salesforce through the user interface.
Users must download and install an authenticator app on their mobile device and connect the app to their Salesforce account. Then they can use verification codes (time-based one-time passwords, or TOTP) from the app for two-factor authentication.
SEE ALSO:
Verify Your Identity with a One-Time Password Generator App or Device
Set Two-Factor Authentication Login Requirements
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Database.com,
Developer, Enterprise,
Group, Performance,
Professional, and Unlimited
Editions
USER PERMISSIONS
To edit system permissions in profiles:
•
Manage Profiles and
Permission Sets
To enable this feature:
•
Two-Factor
Authentication for User
Interface Logins
624
Set Up and Maintain Your Salesforce Organization Authenticate Users
Connect Salesforce Authenticator (Version 2 or Later) to Your Account for Identity Verification
The Salesforce Authenticator (version 2 or later) app on your mobile device is the second factor of authentication. Use the app to add an extra level of security to your account.
1. Download and install version 2 or later of the Salesforce Authenticator app for the type of mobile device you use. For iPhone, get the app from the App Store . For Android devices, get the app from Google Play .
If you previously installed version 1 of Salesforce Authenticator on your mobile device, you can update the app to version 2 through the App Store or Google Play. The update preserves any connected accounts you already have in the app. These accounts are code-only accounts that generate verification codes but don’t receive push notifications or allow location-based automated verifications. If you have a code-only account for the username you used for your current login to Salesforce, swipe left in the app to remove that username before proceeding.
In the following steps, you connect the account for that username again. The new connected account gives you full Salesforce Authenticator version 2 functionality: push notifications, location-based automated verifications, and verification codes.
EDITIONS
Salesforce Authenticator setup available in: both
Salesforce Classic and
Lightning Experience
Mobile app available in:
Group, Professional,
Enterprise, Performance,
Unlimited, Developer, and
Contact Manager Editions
2. From your personal settings, enter
Advanced User Details
in the
Quick Find
box, then select Advanced User Details.
No results? Enter
Personal Information
in the
Quick Find
box, then select Personal Information.
3. Find App Registration: Salesforce Authenticator and click Connect.
4. For security purposes, you’re prompted to log in to your account.
5. Open the Salesforce Authenticator app on your mobile device.
If you’re opening the app for the first time, you see a tour of the app’s features. Take the tour, or go straight to adding your Salesforce account to the app.
6. In the app, tap + to add your account.
The app generates a unique two-word phrase.
7. Back in your browser, enter the phrase in the
Two-Word Phrase
field.
8. Click Connect.
If you previously connected an authenticator app that generates verification codes to your account, you sometimes see an alert.
Connecting version 2 or later of the Salesforce Authenticator mobile app invalidates the codes from your old app. When you need a verification code, get it from Salesforce Authenticator from now on.
9. In the Salesforce Authenticator app on your mobile device, you see details about the account you’re connecting. To complete the account connection, tap Connect in the app.
To help keep your account secure, we send you an email notification whenever a new identity verification method is added to your
Salesforce account. You get the email whether you add the method or your Salesforce admin adds it on your behalf.
If your administrator requires two-factor authentication for increased security when you log in or access reports or dashboards, use the app to verify your account activity. If you’re required to use two-factor authentication before you have the app connected, you’re prompted to connect it the next time you log in to Salesforce. If you don’t yet have the two-factor authentication requirement, you can still connect the app to your account through your personal settings.
After you connect the app, you get a notification on your mobile device when you do something that requires identity verification. When you receive the notification, open the app on your mobile device, check the activity details, and respond on your mobile device to verify.
If you are notified about activity you don’t recognize, use the app to block the activity. You can flag the blocked activity for your Salesforce admin. The app also provides a verification code that you can use as an alternate method of identity verification.
625
Set Up and Maintain Your Salesforce Organization Authenticate Users
Verify Your Identity with a One-Time Password Generator App or Device
Connect a one-time password generator app, such as Salesforce Authenticator or Google
Authenticator, to verify your identity. The app generates a verification code, sometimes called a
“time-based one-time password”.
EDITIONS
If your company requires two-factor authentication for increased security when you log in, access connected apps, reports, or dashboards, use a code from the app. If you’re required to use two-factor authentication before you have an app connected, you’re prompted to connect one the next time you log in to Salesforce.
Available in: Both Salesforce
Classic and Lightning
Experience
Available in all editions
1. Download the supported authenticator app for your device type. You can use any authenticator app that supports the time-based one-time password (TOTP) algorithm ( IETF RFC 6238 ), such as Salesforce Authenticator for iOS ,
Salesforce Authenticator for Android , or Google Authenticator.
2. From your personal settings, enter
Advanced User Details
in the
Quick Find
box, then select Advanced User Details.
No results? Enter
Personal Information
in the
Quick Find
box, then select Personal Information.
3. Find
App Registration: One-Time Password Generator
and click Connect.
If you’re connecting an authenticator app other than Salesforce Authenticator, use this setting. If you’re connecting Salesforce
Authenticator, use this setting if you’re only using its one-time password generator feature (not the push notifications available in version 2 or later).
Note: If you’re connecting Salesforce Authenticator so that you can use push notifications, use the
App Registration:
Salesforce Authenticator
setting instead. That setting enables both push notifications and one-time password generation.
You can connect up to two authenticator apps to your Salesforce account for one-time password generation: Salesforce Authenticator and one other authenticator app.
4. For security purposes, you’re prompted to log in to your account.
5. Using the authenticator app on your mobile device, scan the QR code.
Alternatively, click I Can’t Scan the QR Code in your browser. The browser displays a security key. In the authenticator app, enter your username and the key displayed.
6. In Salesforce, enter the code generated by the authenticator app in the
Verification Code
field.
The authenticator app generates a new verification code periodically. Enter the current code.
7. Click Connect.
To help keep your account secure, we send you an email notification whenever a new identity verification method is added to your
Salesforce account. You get the email whether you add the method or your Salesforce admin adds it on your behalf.
626
Set Up and Maintain Your Salesforce Organization Authenticate Users
Enable U2F Security Keys for Identity Verification
As a Salesforce admin, you can allow users to use a U2F security key anytime they’re challenged to verify their identity, including two-factor authentication and activations. Instead of using Salesforce
Authenticator or one-time passwords sent by email or SMS, users insert their U2F security key into a USB port to complete verification.
The Universal Second Factor (U2F) authentication standard is part of the FIDO Alliance and features the security of public-key cryptography, which strongly resists phishing. U2F security keys, which commonly plug into a USB port, are easy to deploy and work well in environments where mobile devices aren’t allowed. Users can use the same security key with multiple service providers and multiple Salesforce orgs and accounts.
It’s worth mentioning a few things about how security keys work.
•
Users can self-provision their own security keys. These devices don’t require upfront registration by IT or admins.
•
Security keys can look similar to other USB authentication devices that users carry on a keychain.
Try to look for the FIDO U2F logo indicating that the device is compatible with the U2F protocol.
If you’re not sure, verify with your security hardware vendor that their keys are U2F compliant.
•
Security keys aren’t a biometric device, even though some have a button that requires the user’s touch to activate the device. After the user inserts and activates the security key, it generates the required credentials, and the browser passes them on to Salesforce to complete the login.
•
For now, this identity verification method is supported only in Chrome version 41 or later because it’s the only browser that natively supports U2F.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Database.com,
Developer, Enterprise,
Group, Performance,
Professional, and Unlimited
Editions
USER PERMISSIONS
To enable U2F security keys:
•
Customize Application
AND
Manage Users
After you enable U2F security keys in your org, any user can individually register a security key to connect the device to their Salesforce account. Then they can use it for identity verification.
1. From Setup, enter
Session Settings
in the
Quick Find
box, then select Session Settings.
2. Select
Let users use a security key
.
Important:
My Domain must be enabled before you enable U2F security keys. If your org has deployed My Domain, you have access to this setting.
3. Save your changes.
As with other identity verification methods, you can use standard tools in Salesforce to track users’ security key usage.
•
View users’ security key activity on the Identity Verification History page.
•
Monitor security key adoption using the Identity Verification Methods report (via the link on the Identity Verification History page).
•
Create user list views that include the
Has U2F Security Key
field to see who has registered this method.
Using the Mass Email Users tool, you can send targeted communications to users who have registered this method.
627
Set Up and Maintain Your Salesforce Organization Authenticate Users
Register a U2F Security Key for Identity Verification
Register a U2F security key to connect it to your Salesforce account. It’s a secure, convenient alternative to using Salesforce Authenticator or one-time passwords sent by email or SMS. Anytime you’re challenged to verify your identity, including two-factor authentication and activations, you can insert your security key into a USB port to complete verification.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
If your Salesforce admin has allowed the use of U2F security keys, register your own security key
(an admin can’t register for you). Keep in mind these considerations.
•
Make sure that your security key is compatible with the U2F protocol. Security keys can look similar to other USB authentication devices that fit on a keychain. Try to look for the FIDO U2F logo indicating that the device is U2F compliant. If you’re not sure, verify with your Salesforce admin.
Available in: Contact
Manager, Database.com,
Developer, Enterprise,
Group, Performance,
Professional, and Unlimited
Editions
•
Make sure that your browser is compatible. For now, Google Chrome version 41 or later is the only browser that natively supports U2F. All registration and identity verification activity is supported only in Chrome version 41 or later.
•
You can use the same security key with multiple service providers and multiple Salesforce orgs and accounts. You can register one key per account.
1. Have your U2F-compliant security key in hand so that you’re ready to insert it when prompted. If you wait too long, your registration attempt can time out.
2. From your personal settings, enter
Advanced User Details
in the
Quick Find
box, then select Advanced User Details.
No results? Enter
Personal Information
in the
Quick Find
box, then select Personal Information.
3. Click Register next to the
Security Key (U2F)
field.
If you don’t see this option, your Salesforce admin has disallowed the use of security keys.
4. For security purposes, you’re prompted to log in to your account.
5. At the prompt, insert your security key into your computer’s USB port. If it has a button, touch the button.
Security keys aren’t a biometric device, even though some have a button that requires your touch to activate the device.
6. After successful registration, click Continue to dismiss the confirmation message.
To help keep your account secure, we send you an email notification after successful registration.
Now you’re ready to use this identity verification method. When we prompt you for your U2F security key, insert it and touch the button if it has a button. The security key generates the required credentials, and the browser passes them on to Salesforce to complete the verification.
If you’re ever without your security key, you can still use other verification methods, such as Salesforce Authenticator or another method that generates a verification code. If you need a temporary alternate method for two-factor authentication, your admin can generate a temporary verification code (not available for activations).
You can cancel your security key registration at any time, and so can an admin.
628
Set Up and Maintain Your Salesforce Organization Authenticate Users
Disconnect Salesforce Authenticator (Version 2 or Later) from a User’s Account
Only one Salesforce Authenticator (version 2 or later) mobile app can be connected to a user’s account at a time. If your user loses access to the app by replacing or losing the mobile device, disconnect the app from the user’s account. The next time the user logs in with two-factor authentication, if no other authenticator app is connected, Salesforce prompts the user to connect a new authenticator app.
1. From Setup, enter
Users
in the
Quick Find
box, then select Users.
2. Click the user’s name.
3. On the user’s detail page, click Disconnect next to the
App Registration:
Salesforce Authenticator
field.
Users can disconnect the app from their own account on the Advanced User Details page. In personal settings, the user clicks Disconnect next to the
App Registration: Salesforce
Authenticator
field.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in all editions
USER PERMISSIONS
To disconnect a user’s
Salesforce Authenticator app:
•
Manage Two-Factor
Authentication in User
Interface
Disconnect a User’s One-Time Password Generator App
Besides Salesforce Authenticator, one other mobile authenticator app that generates verification codes (one-time passwords) can be connected to a user’s account at a time. If your user loses access to the app by replacing or losing the mobile device, disconnect the app from your user’s account.
The next time your user logs in with two-factor authentication, if no other identity verification method is connected, Salesforce prompts the user to connect a new authenticator app.
1. From Setup, enter
Users
in the
Quick Find
box, then select Users.
2. Click the user’s name.
3. On the user’s detail page, click Disconnect next to the
App Registration: One-Time
Password Generator
field.
Your users can disconnect the app from their own account. In personal settings, they go to the
Advanced User Details page and click Disconnect next to the
App Registration:
One-Time Password Generator
field.
SEE ALSO:
Delegate Two-Factor Authentication Management Tasks
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and Contact
Manager Editions
USER PERMISSIONS
To disconnect a user’s authenticator app:
•
Manage Two-Factor
Authentication in User
Interface
629
Set Up and Maintain Your Salesforce Organization Authenticate Users
Remove a User’s U2F Security Key Registration
One U2F security key can be registered with a user’s Salesforce account at a time. If your user replaces or loses a registered security key, remove the registration from your user’s account.
1. From Setup, enter
Users
in the
Quick Find
box, then select Users.
2. Click the user’s name.
3. On the user’s detail page, click Remove next to the
Security Key (U2F)
field.
Your users can remove a registered security key from their own account. In personal settings, they go to the Advanced User Details page and click Remove next to the
Security Key (U2F) field.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Group,
Professional, Enterprise,
Performance, Unlimited,
Developer, and Contact
Manager Editions
USER PERMISSIONS
To remove a user’s U2F security key registration:
•
Manage Two-Factor
Authentication in User
Interface
Generate a Temporary Identity Verification Code
Generate a temporary verification code for users who can’t access the device they usually use for two-factor authentication. You set when the code expires, from 1 to 24 hours after you generate it. The code can be used multiple times until it expires.
Temporary verification codes are valid for two-factor authentication only. They aren’t valid for device activations. That is, when users log in from an unrecognized browser or app and we require identity verification, they can’t use a temporary code.
1. From Setup, enter
Users
in the
Quick Find
box, then select Users.
2. Click the name of the user who needs a temporary verification code.
You can’t generate a code for an inactive user.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
3. Find
Temporary Verification Code
, then click Generate.
If you don’t already have a session with a high-assurance security level, Salesforce prompts you to verify your identity.
4. Set when the code expires, and click Generate Code.
5. Give the code to your user, then click Done.
After you click Done, you can’t return to view the code again, and the code isn’t displayed anywhere in the user interface.
USER PERMISSIONS
To generate a temporary verification code:
•
Manage Two-Factor
Authentication in User
Interface
Your user can use the temporary verification code multiple times until it expires. Each user can have only one temporary verification code at a time. If a user forgets or loses the code before it expires, you can manually expire the old code and generate a new one. You can generate up to six codes per hour for each user.
630
Set Up and Maintain Your Salesforce Organization Authenticate Users
Note: When you add an identity verification method to a user’s account, the user gets an email. To stop sending emails to users when new identity verification methods are added to their accounts, contact Salesforce.
SEE ALSO:
Delegate Two-Factor Authentication Management Tasks
Expire a Temporary Verification Code
Expire a Temporary Verification Code
Expire a user’s temporary verification code when the user no longer needs it for two-factor authentication
Each user can have only one temporary verification code at a time. If a user forgets or loses the code before it expires, you can manually expire the old code and generate a new one. You can generate up to six codes per hour for each user.
1. From Setup, enter
Users
in the
Quick Find
box, then select Users.
2. Click the name of the user whose temporary verification code you need to expire.
3. Find
Temporary Verification Code
, and click Expire Now.
SEE ALSO:
Delegate Two-Factor Authentication Management Tasks
Generate a Temporary Identity Verification Code
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To expire a user’s temporary verification code:
•
Manage Two-Factor
Authentication in User
Interface
See How Your Users Are Verifying Their Identity
Customize a list view of users or check the Identity Verification Methods report to find out who’s using which methods to verify identity. Create custom reports to spot patterns in identity verification behavior for your org or community.
To see registered identity verification methods in a Users list view, create or edit a view and add one or more of the following fields.
Has Verified Mobile Number
Indicates whether the user has verified a mobile phone number. Salesforce can text a verification code to the user at that number.
Has One-Time Password App
Indicates whether the user has connected an authenticator app that generates verification codes, also known as time-based one-time passwords. The user can verify identity by entering a code generated by the app.
Has Salesforce Authenticator
Indicates whether the user has connected the Salesforce Authenticator mobile app. The user can verify identity by approving a notification sent to the app.
EDITIONS
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To monitor user identity verification methods:
•
Manage Two-Factor
Authentication in User
Interface
631
Set Up and Maintain Your Salesforce Organization Authenticate Users
Has Temporary Code
Indicates whether the user has a temporary verification code. Admins or non-admin users with the “Manage Two-Factor Authentication in User Interface” permission generate temporary codes and set when the code expires.
Has U2F Security Key
Indicates whether the user has registered a U2F security key. The user can verify identity by inserting the security key into a USB port.
You can perform some two-factor authentication support tasks right in the list view. For example, you can generate or expire a temporary verification code or disconnect a mobile authenticator app when the user loses access to the mobile device.
To view and customize the Identity Verification Methods report, users with the “Manage Two-Factor Authentication in User Interface” permission can click the link on the Identity Verification History page in Setup.
Users with the “View Setup and Configuration” permission can also access the report from the Administrative Reports folder in Reports.
Users with the “Manage Two-Factor Authentication in API” permission can create custom reports and dashboards for even deeper insight into identity verification history in your org or community. For example, create a report that shows identity verification method registration by profile. Or create a dashboard with charts that show method registration and verification challenges by the org policy that triggered them.
SEE ALSO:
Delegate Two-Factor Authentication Management Tasks
Delegate Two-Factor Authentication Management Tasks
Let users who aren’t Salesforce admins provide support for two-factor authentication in your org.
For example, suppose you want your company’s Help Desk staff to generate temporary verification codes for users who lost or forgot the device they usually use for two-factor authentication. Assign
Help Desk staff members the “Manage Two-Factor Authentication in User Interface” permission so that they can generate codes and support end users with other two-factor authentication tasks.
To assign the permission, select “Manage Two-Factor Authentication in User Interface” in the user profile (for cloned profiles only) or permission set. Users with the permission can perform the following tasks.
•
Generate a temporary verification code for a user who can’t access the device normally used for two-factor authentication.
•
Disconnect identity verification methods from a user’s account when the user loses or replaces a device.
•
View user identity verification activity on the Identity Verification History page.
•
View the Identity Verification Methods report by clicking a link on the Identity Verification History page.
•
Create user list views that show which identity verification methods users have registered.
EDITIONS
Available in: Both Salesforce
Classic and Lightning
Experience
Available in: Contact
Manager, Group,
Professional, Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To edit profiles and permission sets:
•
Manage Profiles and
Permission Sets
632
Set Up and Maintain Your Salesforce Organization Transaction Security
Note: Although non-admin users with the permission can view the Identity Verification Methods report, they can’t create custom reports that include data restricted to users with the “Manage Users” permission.
SEE ALSO:
Protect Your Salesforce Organization
Disconnect Salesforce Authenticator (Version 2 or Later) from a User’s Account
Disconnect a User’s One-Time Password Generator App
Generate a Temporary Identity Verification Code
Expire a Temporary Verification Code
See How Your Users Are Verifying Their Identity
Transaction Security
Transaction Security is a framework that intercepts real-time Salesforce events and applies appropriate actions and notifications based on security policies you create. Transaction Security monitors events according to the policies that you set up. These policies are applied against events in your org and specify actions to take when certain event combinations occur. When a policy is triggered, you can have an action taken and receive an optional notification.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
IN THIS SECTION:
Policies evaluate activity using events that you specify. For each policy, you define real-time actions, such as notify, block, force two-factor authentication, freeze user, or end a session.
Transaction Security uses resource metering to help prevent malicious or unintentional monopolization of shared, multitenant platform resources. Metering prevents policy evaluations from using too many resources and impacting your org.
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
Activate and configure transaction security on your org before creating your own custom policies. Only an active user assigned the
System Administrator profile can use this feature.
Create Custom Transaction Security Policies
Create your own custom policies, triggered by specific events. Only an active user assigned the System Administrator profile can use this feature.
Create Transaction Security Policies with Salesforce Classic
Create a policy in Salesforce Classic using a single form, including a basic Apex event class.
Create Transaction Security Policies with Lightning Experience
Let the Transaction Security wizard walk you through the steps to create a policy.
Apex Policies for Transaction Security Notifications
Every Transaction Security policy must implement the Apex
TxnSecurity.PolicyCondition
interface. Here are several examples.
633
Set Up and Maintain Your Salesforce Organization Transaction Security
Manage Transaction Security Policies
Use Transaction Security policies to define, enable, and generate Apex code to implement your policies. Specify how to be notified when a policy is triggered, and then select the policies to enable. Only an active user assigned the System Administrator profile can use this feature.
Receiving Transaction Security Notifications
You receive the notifications you’ve selected when an enabled policy is triggered. The notifications are formatted for easy recognition.
Transaction Security Policies
Policies evaluate activity using events that you specify. For each policy, you define real-time actions, such as notify, block, force two-factor authentication, freeze user, or end a session.
When you enable Transaction Security for your org, two policies are created:
EDITIONS
•
Concurrent User Session Limit policy to limit concurrent login sessions
•
Lead Data Export policy to block excessive data downloads of leads
Available in: both Salesforce
Classic and Lightning
Experience
The policies’ corresponding Apex classes are also created in the org. An administrator can enable the policies immediately or edit their Apex classes to customize them.
For example, suppose that you activate the Concurrent User Session Limit policy to limit the number of concurrent sessions per user. In addition, you change the policy to notify you via email when the policy is triggered. You also update the policy’s Apex implementation to limit users to three sessions instead of the default five sessions. (That’s easier than it sounds.) Later, someone with three login sessions tries to create a fourth. The policy prevents that and requires ending one of the existing sessions before proceeding with the new session. At the same time, you are notified that the policy was triggered.
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
The Transaction Security architecture uses the Security Policy Engine to analyze events and determine the necessary actions.
A transaction security policy consists of events, notifications, and actions.
•
Available event types are:
–
Data Export for Account, Case, Contact, Lead, and Opportunity objects
–
Entity for authentication providers and sessions, client browsers, login IP, and Chatter resources
634
Set Up and Maintain Your Salesforce Organization Transaction Security
–
Logins
–
Resource Access for connected apps and reports and dashboards
•
You can be notified via email, by an in-app notification, or both.
•
Actions to take if the policy is triggered:
–
Block the operation
–
Require a higher level of assurance using two-factor authentication
–
Freeze the user
–
End a current session
You can also take no action and only receive a notification. The actions available depend on the event type and resource selected.
Transaction Security Metering
Transaction Security uses resource metering to help prevent malicious or unintentional monopolization of shared, multitenant platform resources. Metering prevents policy evaluations from using too many resources and impacting your org.
Policies are metered for uniform resource use. If a policy request can’t be handled quickly enough, a fail-close behavior occurs, and access is blocked. Transaction Security implements metering by limiting policy execution. If the elapsed execution time exceeds three seconds, the user is denied access to the resource or entity.
Here’s an example of how metering works for login policies. Your org has a login policy with a notification action. A user makes four login requests concurrently, but they can’t all be executed in sufficient time. Transaction Security stops processing the policies and fails closed, blocking all four login requests. Because the policy evaluations didn’t finish, a notification isn’t sent.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
635
Set Up and Maintain Your Salesforce Organization Transaction Security
Set Up Transaction Security
Activate and configure transaction security on your org before creating your own custom policies.
Only an active user assigned the System Administrator profile can use this feature.
1. Enable transaction security policies to make them available for use.
EDITIONS
a. From Setup, enter
Transaction Security
in the
Quick Find
box, then select
Transaction Security.
b. Select Enable custom transaction security policies at the top of the page.
The ConcurrentSessionsLimitingPolicy limits concurrent sessions and is triggered in two ways:
•
When a user with five current sessions tries to log in for a sixth session
•
When an administrator that’s already logged in tries to log in a second time
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
You can adjust the number of sessions allowed by changing the Apex policy implementation
ConcurrentSessionsPolicyCondition
.
The Lead Data Export policy blocks excessive data downloads of leads. It’s triggered when a download either:
•
Retrieves more than 2,000 lead records
•
Takes more than one second to complete
You can change these values by modifying the policy implementation.
DataLoaderLeadExportCondition
2. After Transaction Security is enabled, set the preferences for your org.
a. Click Default Preferences on the Transaction Security Policies page.
USER PERMISSIONS
User Permissions Needed
To create, edit, and manage transaction security policies:
•
Author Apex
AND
Customize Application
b. Select the preference When users exceed the maximum number of Salesforce sessions
allowed, close the oldest session.
Login policies affect programmatic access and access from Salesforce Classic and Lightning Experience. When you create a policy that limits the number of concurrent user sessions, all sessions count toward that limit. Regular logins with a username and password, logins by web applications, logins using Authentication Providers, and all other login types are considered.
The session limit isn’t a problem in Salesforce Classic or Lightning Experience because you’re prompted to select which session or sessions to end. That choice isn’t available from within a program, so the program receives a Transaction Security exception that the session limit has been reached.
To prevent this problem, select When users exceed the maximum number of Salesforce sessions allowed, close the oldest
session.. Then when a programmatic request is made that exceeds the number of sessions allowed, older sessions are ended until the session count is below the limit. The setting also works for logins from the UI. Instead of being asked to select a session to end, the oldest session is automatically ended, and the new login proceeds for the new session. Here’s how the OAuth flows handle login policies with and without the preference being set.
Flow Type
OAuth 2.0 web server
Action If Preference Is Selected Action If Preference Is Not Selected
Authorization Code and Access Token granted
Older sessions are ended until you’re within policy compliance.
Authorization Code granted, but Access Token not granted
Older sessions are ended until you’re within policy compliance.
636
Set Up and Maintain Your Salesforce Organization Transaction Security
Flow Type
OAuth 2.0 user-agent
OAuth 2.0 refresh token flow
Action If Preference Is Selected Action If Preference Is Not Selected
Access Token granted
Older sessions are ended until you’re within policy compliance.
Access Token granted
Older sessions are ended until you’re within policy compliance.
Access Token granted
Older sessions are ended until you’re within policy compliance.
TXN_SECURITY_END_SESSION exception
OAuth 2.0 JWT bearer token Access Token granted
Older sessions are ended until you’re within policy compliance.
TXN_SECURITY_END_SESSION exception
OAuth 2.0 SAML bearer assertion
Access granted
Older sessions are ended until you’re within policy compliance.
TXN_SECURITY_END_SESSION exception
OAuth 2.0 username and password
Access granted
Older sessions are ended until you’re within policy compliance.
Access denied due to more than the number of sessions allowed by the policy
SAML assertion Not applicable Not applicable
For more information on authentication flows, see Authenticate Apps with OAuth in the Salesforce help.
637
Set Up and Maintain Your Salesforce Organization Transaction Security
Create Custom Transaction Security Policies
Create your own custom policies, triggered by specific events. Only an active user assigned the
System Administrator profile can use this feature.
The way you create a policy depends on which UI you’re using.
•
If you’re using Salesforce Classic, refer to
Create Transaction Security Policies with Salesforce
.
•
If you’re using Lightning Experience, refer to Create Transaction Security Policies with Lightning
You can create multiple policies for the same type of event, but we recommend that your policies and their actions don’t overlap. All the policies for a given event execute when the event occurs, but their order of execution is indeterminate. For example, if you have two policies enabled for an exported contact, you can’t be sure which policy is triggered first. If one policy copies the contact and the other policy deletes the contact, the copy operation fails if the deletion is done first.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
USER PERMISSIONS
User Permissions Needed
To create, edit, and manage transaction security policies:
•
Author Apex
AND
Customize Application
638
Set Up and Maintain Your Salesforce Organization Transaction Security
Create Transaction Security Policies with Salesforce Classic
Create a policy in Salesforce Classic using a single form, including a basic Apex event class.
1. From Setup, enter
Transaction Security
in the
Quick Find
box, select
Transaction Security, and then click New in Transaction Security Policies.
2. Enter the basic information fields for your new policy.
•
For clarity and easier maintenance, use similar names for the API and the policy. This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
•
Event Type
—Determines the available actions. It can be one of the following:
–
Login—A user login. Login lets you set any combination of notifications, plus these actions:
•
Block access completely
•
Continue, but require two-factor authentication
•
Continue, but require the end of a current login session
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
USER PERMISSIONS
–
Entity—An object type. Select a specific resource and the type of notifications desired.
The Freeze User action is available for Chatter resources.
–
Data Export—Notifies you when the selected object type has been exported. Available object types are Account, Case, Contact, Lead, and Opportunity. To trigger a policy, the export must be done using a default report type from the Report tab or with an API client like Data Loader or Workbench.
Note:
You can’t create a Data Export event policy for joined reports, historical reports, or custom report types.
User Permissions Needed
To create, edit, and manage transaction security policies:
•
Author Apex
AND
Customize Application
–
AccessResource—Notifies you when the selected resource has been accessed. You can block access or require two-factor authentication before access is allowed.
•
Notifications
—You can select all, some, or no notification methods for each policy.
•
Recipient
—Must be an active user assigned the System Administrator profile.
•
Real-time Actions
—Specifies what to do when the policy is triggered. The actions available vary depending on the event type. For login and resource events, you can also block the action or require a higher level of access control with two-factor authentication. For Chatter events, you can freeze the user or block the post. For Login events, you can require ending an existing session before continuing with the current session. You can set the default action for ending a session to always close the oldest session.
Important: If you create a policy requiring the two-factor authentication action, provide your users a way to get a time-based, one-time password. This password is their second authentication factor. Otherwise, if your users encounter a situation that requires a second authentication factor, they can’t finish their task, such as logging in or running a report.
•
You can use an existing class for
Apex Policy
or select Generate Apex to have a default policy class created that implements the
TxnSecurity.PolicyCondition
interface. You can also write your own policy to take advantage of any customizations you’ve made to your org.
•
The user selected for
Execute Policy As
must have the System Administrator profile.
3. You can optionally create a condition for a specific property as part of the policy. For example, you can create a policy that’s triggered when a report or dashboard is accessed from a specific source IP. The source IP is the property you’re checking.
639
Set Up and Maintain Your Salesforce Organization Transaction Security
•
The available properties depend on the event type selected.
•
For example, with Login events, property changes that occurred within a given number of days or an exact match to a property value are available.
4. To enable a policy, select the policy’s checkbox. You can enable and disable policies according to your requirements.
5. Click Save.
After saving your selection, you’re shown the editing page for your new policy. You can modify your policy here and review its Apex class.
If you didn’t specify a condition value before you generated the Apex interface for a policy, you can add the condition later. If you want to change the condition, you can edit it. Edit the Apex code to include a condition before you activate your policy. If you never include
for examples.
Create Transaction Security Policies with Lightning Experience
Let the Transaction Security wizard walk you through the steps to create a policy.
1. From Setup, enter
Transaction
in the
Quick Find
box, select Transaction Security, and then click Create Policy in Transaction Security Policies.
2. First select what your policy monitors. Choose a category and then select an event or entity in that category.
The categories are:
•
Data Export—Notifies you when the selected object type has been exported. To trigger a policy, the export must be done using a default report type from the Report tab or with an API client like Data Loader or Workbench.
Note:
You can’t create a Data Export event policy for joined reports, historical reports, or custom report types.
•
Login—A user login. You can trigger your policy on many types of login events.
•
Resource Access—Notifies you when the selected resource has been accessed. You can block access or require two-factor authentication before access is allowed.
•
Entity—An object type.
Note:
Lightning Experience supports only the Feed Comment and Feed Item resources, while Salesforce Classic supports all Chatter resources.
3. Select Generate Apex unless you have an existing policy condition to use.
Transaction Security creates a stub, or placeholder, Apex policy condition. You’ll expand it after creating the policy.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
USER PERMISSIONS
User Permissions Needed
To create, edit, and manage transaction security policies:
•
Author Apex
AND
Customize Application
4. Next select what the policy is to do when triggered, who is to be notified and how, and the user that the policy executes as. The user selected for
Execute Policy As
must have the System Administrator profile.
The actions available vary depending on the event type. For login and resource events, you can also block the action or require a higher level of access control with two-factor authentication. For Chatter events, you can freeze the user or block the post. For Login events, you can require ending an existing session before continuing with the current session. You can set the default action for ending a session to always close the oldest session.
Note:
Two-factor authentication is not available in Salesforce1 or Lightning Experience for the Resource Access event type.
The Block action is used instead.
640
Set Up and Maintain Your Salesforce Organization Transaction Security
Important: If you create a policy requiring the two-factor authentication action, provide your users a way to get a time-based, one-time password. This password is their second authentication factor. Otherwise, if your users encounter a situation that requires a second authentication factor, they can’t finish their task, such as logging in or running a report.
5. Choose a descriptive name for your policy. The name and policy description help you identify and organize policies as they are created.
6. Click Save and then click Finish to confirm. The new policy appears at the bottom of the policy list.
If you didn’t select an existing Apex class for your new policy, modify the generated Apex class now, before activating your policy. Click the Apex class name to get started and add the condition that triggers the policy. See
Apex Policies for Transaction Security Notifications
for examples.
Apex Policies for Transaction Security Notifications
Every Transaction Security policy must implement the Apex
TxnSecurity.PolicyCondition
interface. Here are several examples.
If you didn’t specify a condition value before you generated the Apex interface for a policy, you can add the condition later. If you want to change the condition, you can edit it. Edit the Apex code to include a condition before you activate your policy. If you never include a condition, your policy is never triggered. See the following examples for how to write up the condition.
Don’t include Data Manipulation Language (DML) statements in your custom policies. DML operations are rolled back after a transaction security policy is evaluated, regardless if the policy evaluates to true
or false
.
When you delete a transaction security policy, your
TxnSecurity.PolicyCondition
implementation isn’t deleted. You can reuse your Apex code in other policies.
This Apex policy example implements a policy that is triggered when someone logs in from multiple
IP addresses in the past 24 hours.
Example: global class LoginPolicyCondition implements
TxnSecurity.PolicyCondition { public boolean evaluate(TxnSecurity.Event e) {
AggregateResult[] results = [SELECT SourceIp
FROM LoginHistory
WHERE UserId = :e.userId
AND LoginTime =
LAST_N_DAYS:1
GROUP BY SourceIp]; if(!results.isEmpty() && results.size() > 1) { return true;
} return false;
}
}
This Apex policy example implements a policy that is triggered when a session is created from a specific IP address.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
641
Set Up and Maintain Your Salesforce Organization Transaction Security
Example: global class SessionPolicyCondition implements TxnSecurity.PolicyCondition { public boolean evaluate(TxnSecurity.Event e) {
AuthSession eObj = [SELECT SourceIp FROM AuthSession WHERE Id = :e.entityId]; if(eObj.SourceIp == '1.1.1.1' ){ return true;
} return false;
}
}
This DataExport policy implements a policy that is triggered when someone exports data via the Data Loader.
Example: global class DataExportPolicyCondition implements TxnSecurity.PolicyCondition { public boolean evaluate(TxnSecurity.Event e) { if(e.data.get('SourceIp') == '1.1.1.1' ){ return true;
} return false;
}
}
This Apex policy is triggered when someone accesses reports.
Example: global class ReportsPolicyCondition implements TxnSecurity.PolicyCondition { public boolean evaluate(TxnSecurity.Event e) { if(e.data.get('SessionLevel') == 'STANDARD' ){ return true;
} return false;
}
}
This Apex policy is triggered when someone accesses a Connected App.
Example: global class ConnectedAppsPolicyCondition implements TxnSecurity.PolicyCondition { public boolean evaluate(TxnSecurity.Event e) { if(e.data.get('SessionLevel') == 'STANDARD' && (e.entityId == '0CiD00000004Cce')){ return true;
} return false;
642
Set Up and Maintain Your Salesforce Organization Transaction Security
}
}
SEE ALSO:
Additional PolicyCondition Example Implementations
Apex DML Operations
Manage Transaction Security Policies
Use Transaction Security policies to define, enable, and generate Apex code to implement your policies. Specify how to be notified when a policy is triggered, and then select the policies to enable.
Only an active user assigned the System Administrator profile can use this feature.
1. From Setup, enter
Transaction Security
in the
Quick Find
box, then select
Transaction Security.
2. From the Transaction Security Policies page, you can
•
Edit a view
•
Create a view
•
Edit a policy
•
Create a policy
•
Edit the
TxnSecurity.PolicyCondition
Apex class for a policy
•
Delete a policy
•
Set the transaction security default preferences
You can change the transaction security default preferences at any time.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
USER PERMISSIONS
User Permissions Needed
To create, edit, and manage transaction security policies:
•
Author Apex
AND
Customize Application
643
Set Up and Maintain Your Salesforce Organization Transaction Security
Receiving Transaction Security Notifications
You receive the notifications you’ve selected when an enabled policy is triggered. The notifications are formatted for easy recognition.
Email Notifications
Email notifications are sent from Transaction Security with subject “Transaction Security Alert!” The body of the message contains the policy that was triggered and the event or events that occurred to trigger the policy. The times listed are when the policy was triggered in the recipient’s locale and time zone. For example, a policy is triggered at 6:46 PM in the Eastern Standard Time zone. The administrator receiving the notification is in the Pacific Standard Time zone, so the times are shown as PST. Here’s an example.
Example:
From: Transaction Security <[email protected]>
Sent: Friday, November 12, 2014, 5:35 PM
Subject: Transaction Security Alert!
This is a transaction security policy alert.
Policy: An administrator created a new user.
Event(s) responsible for triggering this policy:
1. Created new user Lisa Johnson at 11/12/2014 5:35:09 PM PST
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions.
Requires purchasing
Salesforce Shield or
Salesforce Shield Event
Monitoring add-on subscriptions.
In-App Notifications
In-app notifications are available only if you’re a Salesforce1 user. The notification lists the policy that was triggered. Here’s an example.
Example:
Transaction Security Alert:
Policy New Encrypted Custom Field was triggered.
644
Set Up and Maintain Your Salesforce Organization Single Sign-On
Single Sign-On
Single sign-on (SSO) lets users access authorized network resources with one login. You validate usernames and passwords against your corporate user database or other client app rather than
Salesforce managing separate passwords for each resource.
Salesforce offers the following ways to use SSO.
•
Federated authentication using Security Assertion Markup Language (SAML) lets you send authentication and authorization data between affiliated but unrelated web services. You can log in to Salesforce from a client app. Salesforce enables federated authentication for your org automatically.
•
Delegated authentication SSO integrates Salesforce with an authentication method that you choose. You can integrate authentication with your LDAP (Lightweight Directory Access Protocol) server or use a token instead of a password for authentication. You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their
Salesforce-managed password.
Delegated authentication offers the following benefits.
–
Uses a stronger form of user authentication, such as integration with a secure identity provider
–
Makes your login page private and accessible only behind a corporate firewall
–
Differentiates your org from all other companies that use Salesforce to reduce phishing attacks
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
You must contact Salesforce to enable delegated authentication before you can configure it on your org.
•
Authentication providers let your users log in to your Salesforce org using their login credentials from an external service provider. Salesforce supports the OpenID Connect protocol, which lets users log in from any OpenID Connect provider, such as Google, PayPal, and LinkedIn. When an authentication provider is enabled, Salesforce doesn’t validate a user’s password. Instead,
Salesforce uses the user’s login credentials from the external service provider to establish authentication credentials.
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
When you have an external identity provider and configure SSO for your Salesforce org, Salesforce is then acting as a service provider.
You can also enable Salesforce as an
and use SSO to connect to a different service provider. Only the service provider needs to configure SSO.
The Single Sign-On Settings page displays which version of SSO is available for your org. To learn more about SSO settings, see
SAML Settings for Single Sign-On
. For more information about SAML and Salesforce security, see the
Security Implementation Guide
.
Benefits of SSO
Implementing SSO brings several advantages to your org.
•
Reduced administrative costs—With SSO, users memorize a single password to access network resources and external apps and
Salesforce. When accessing Salesforce from inside the corporate network, users log in seamlessly and aren’t prompted for a username or password. When accessing Salesforce from outside the corporate network, the users’ corporate network login works to log them in. With fewer passwords to manage, system admins receive fewer requests to reset forgotten passwords.
645
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Leverage existing investment—Many companies use a central LDAP database to manage user identities. You can delegate
Salesforce authentication to this system. Then when users are removed from the LDAP system, they can no longer access Salesforce.
Users who leave the company automatically lose access to company data after their departure.
•
Time savings—On average, users take 5–20 seconds to log in to an online app. It can take longer if they mistype their username or password and are prompted to reenter them. With SSO in place, manually logging in to Salesforce is avoided. These saved seconds reduce frustration and add up to increased productivity.
•
Increased user adoption—Due to the convenience of not having to log in, users are more likely to use Salesforce regularly. For example, users can send email messages that contain links to information in Salesforce, such as records and reports. When the recipient of the email message clicks the links, the corresponding Salesforce page opens.
•
Increased security—All password policies that you’ve established for your corporate network are in effect for Salesforce. Sending an authentication credential that’s only valid for a single time also increases security for users who have access to sensitive data.
IN THIS SECTION:
Best Practices for Implementing Single Sign-On
Salesforce offers a set of best practices that you can follow when implementing delegated authentication, federated authentication using SAML, single sign-on (SSO) for portals, and SSO for Sites.
Delegated Authentication Single Sign-On
You can integrate Salesforce with the authentication method of your choice using delegated authentication single sign-on (SSO).
You can integrate with your LDAP (Lightweight Directory Access Protocol) server or authenticate with a token instead of a password.
You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their Salesforce-managed password.
Configure Salesforce for Delegated Authentication
You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their Salesforce-managed password. You must contact Salesforce to enable the delegated authentication feature before you can configure it in your org.
Control Individual API Client Access to Your Salesforce Org
You can restrict access to API client apps, such as Data Loader, Salesforce1, and third-party apps. To restrict access, request the API client whitelisting feature from Salesforce. When whitelisting is enabled, you restrict access to all connected apps until you explicitly approve each app. Approved apps are often called whitelisted apps.
Viewing Single Sign-On Login Errors
Salesforce Identity uses the XML-based Security Assertion Markup Language (SAML) protocol for single sign-on into Salesforce from a corporate portal or identity provider. With SAML, you can transfer user information between services, such as from Salesforce to
Microsoft 365.
About Just-in-Time Provisioning for SAML
External Authentication Providers
Authentication providers let your users log in to your Salesforce org using their login credentials from an external service provider.
Salesforce provides authentication providers for apps that support the OpenID Connect protocol, such as Google, Facebook, Twitter, and LinkedIn. For apps that don’t support OpenID Connect, Salesforce provides an Apex
Auth.AuthProviderPluginClass
abstract class to create a custom authentication provider.
Using Frontdoor.jsp to Log Into Salesforce
You can use frontdoor.jsp to give users access to Salesforce from a custom Web interface, such as a remote access Force.com site, using their existing session ID and the server URL.
646
Set Up and Maintain Your Salesforce Organization Single Sign-On
Use Request Parameters with Client Configuration URLs
Add functionality to your authentication provider with request parameters. For example, you can use these parameters to direct users to log in to specific sites, get customized permissions from the third party, or go to a specific location after authenticating.
Identity Providers and Service Providers
An identity provider is a trusted provider that lets you use single sign-on (SSO) to access other websites. A service provider is a website that hosts apps. You can enable Salesforce as an identity provider and define one or more service providers. Your users can then access other apps directly from Salesforce using SSO. SSO can be a great help to your users—instead of having to remember many passwords, they only have to remember one.
Configure Remote Site Settings
A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. To simplify the setup of authenticated callouts, specify a named credential as the callout endpoint. If you instead specify a URL as the callout endpoint, you must register that URL in your org’s remote site settings and handle the authentication yourself. For example, for an
Apex callout, your code would need to handle authentication, which can be less secure and especially complicated for OAuth implementations.
Identity Connect integrates Microsoft Active Directory (AD) with Salesforce. User information entered in AD is shared with Salesforce seamlessly and instantaneously. Companies that use AD for user management can use Identity Connect to manage Salesforce accounts.
647
Set Up and Maintain Your Salesforce Organization Single Sign-On
Best Practices for Implementing Single Sign-On
Salesforce offers a set of best practices that you can follow when implementing delegated authentication, federated authentication using SAML, single sign-on (SSO) for portals, and SSO for
Sites.
Salesforce offers the following ways to use SSO.
•
Federated authentication using Security Assertion Markup Language (SAML) lets you send authentication and authorization data between affiliated but unrelated web services. You can log in to Salesforce from a client app. Salesforce enables federated authentication for your org automatically.
•
Delegated authentication SSO integrates Salesforce with an authentication method that you choose. You can integrate authentication with your LDAP (Lightweight Directory Access Protocol) server or use a token instead of a password for authentication. You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their
Salesforce-managed password.
Delegated authentication offers the following benefits.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Customer Portals and partner portals are not available in Database.com
–
Uses a stronger form of user authentication, such as integration with a secure identity provider
USER PERMISSIONS
–
Makes your login page private and accessible only behind a corporate firewall
–
Differentiates your org from all other companies that use Salesforce to reduce phishing attacks
To view the settings:
•
View Setup and
Configuration
You must contact Salesforce to enable delegated authentication before you can configure it on your org.
To edit the settings:
•
Customize Application
•
Authentication providers let your users log in to your Salesforce org using their login credentials from an external service provider. Salesforce supports the OpenID Connect protocol, which lets users log in from any OpenID Connect provider, such as Google, PayPal, and LinkedIn. When
AND
Modify All Data an authentication provider is enabled, Salesforce doesn’t validate a user’s password. Instead,
Salesforce uses the user’s login credentials from the external service provider to establish authentication credentials.
In addition, you can also configure SAML for use with portals as well as for Sites.
Delegated Authentication Best Practices
Consider these best practices when implementing delegated authentication SSO for your org.
•
Your org’s implementation of the web service must be accessible by Salesforce servers, so you must deploy the web service on a server in your DMZ. Remember to use your server’s external DNS name when entering the delegated gateway URL in the Delegated authentication section in Salesforce. From Setup, enter
Single Sign-On Settings
in the
Quick Find
box, then select
Single Sign-On Settings.
•
If Salesforce and your system can’t connect, or if the request takes longer than 10 seconds to process, the login attempt fails. The user gets an error message indicating that the corporate authentication service is down.
•
Namespaces, element names, and capitalization must be exact in SOAP requests. Wherever possible, generate your server stub from the WSDL file to ensure accuracy.
•
For security reasons, make your web service available by TLS. A certificate from a trusted provider, such as Verisign or Thawte, is required. For a list of trusted providers, contact Salesforce.
648
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
The IP address that originated the login request is sourceIp. Use this information to restrict access based on the user’s location. Also, the Salesforce feature that validates login IP ranges applies to SSO users. For more information, see
on page 597.
•
You might need to map your org’s internal usernames to your Salesforce usernames. If your org doesn’t follow a standard mapping, try extending your user database schema (for example, Active Directory) to include the Salesforce username as an attribute of a user account. Your authentication service can then use this attribute to map back to a user account.
•
We recommend that you don’t enable SSO for Salesforce admins. If your Salesforce admins are SSO users and your SSO server has an outage, they have no way to log in to Salesforce. Make sure that Salesforceadmins can log in to Salesforce so that they can disable
SSO if problems occur.
•
We recommend that you use a Developer Edition account or a sandbox when developing a SSO solution before implementing it in your org. To sign up for a free Developer Edition account, go to developer.salesforce.com
.
•
Make sure to test your implementation with Salesforce clients, such as Salesforce for Outlook, Connect for Office, and Connect Offline.
For more information, see Single Sign-On for Salesforce clients .
Federated Authentication Using SAML Best Practices
Consider these best practices when implementing federated SSO with SAML for your org.
•
Get the Salesforce login URL from the Single Sign On Settings configuration page and enter it in the corresponding configuration parameter of your identity provider. Sometimes, the setting is called the recipient URL.
•
Salesforce allows a maximum of 3 minutes for clock skew with your IDP server. Make sure that your server’s clock is up to date.
•
If you can’t log in with SAML assertion, check the login history and note the error message. Use the SAML Assertion Validator on the
Single Sign On Settings configuration page to troubleshoot.
•
Map your orgs internal usernames and Salesforce usernames. To map the names, you can add a unique identifier to the
FederationIdentifier
field of each Salesforce user. Or you can extend your user database schema (for example, Active
Directory) to include the Salesforce username as an attribute of a user account. Choose the corresponding option for the
SAML
Identity Type
field, and configure your authentication service to send the identifier in SAML assertions.
•
Before allowing users to log in with SAML assertions, enable the SAML org preference and provide the necessary configurations.
•
Use the My Domain feature to prevent users from logging in to Salesforce directly, and give admins more control over login policies.
You can use the URL parameters provided in the
Salesforce Login URL
value from the Single Sign-On Settings configuration page with your custom domain.
For example, if the
Salesforce Login URL
is https://login.salesforce.com/?saml=02HKiP...
you can use https://yourDomain.my.salesforce.com/?saml=02HKiP...
•
We recommend that you use a Developer Edition account or a sandbox when testing a SAML SSO solution. To sign up for a free
Developer Edition account, go to developer.salesforce.com
.
•
Sandbox copies are made with federated authentication with SAML disabled. Any configuration information is preserved, except the value for
Salesforce Login URL
. The
Salesforce Login URL
is updated to match your sandbox URL, for example https://yourInstance.salesforce.com/
, after you re-enable SAML. To enable SAML in the sandbox, from
Setup, enter
Single Sign-On Settings
in the
Quick Find
box, then select Single Sign-On Settings; then click Edit, and select
SAML Enabled
.
•
Your identity provider must allow you to set the service provider’s audience URL. The value must match the
Entity ID
value in the SSO configuration. The default is https://saml.salesforce.com
.
649
Set Up and Maintain Your Salesforce Organization Single Sign-On
SSO for Portals Best Practices
Customer Portals and partner portals are not available for new orgs as of the Summer ’13 release. Use Communities instead. For more information about SSO and SAML for Communities, see “Configuring SAML for Communities” in the Salesforce Help. If you continue to use portals, be aware of these requirements.
•
Only SAML version 2.0 can be used with portals.
•
Only Customer Portals and partner portals are supported.
•
Service provider initiated login is not supported.
•
Both the portal_id
and organization_id
attributes are required. If only one is specified, the user receives an error.
•
If both the portal_id
and organization_id
attributes are populated in the SAML assertion, the user is directed to that portal login. If neither is populated, the user is directed to the regular SAML Salesforce login.
•
More than one portal can be used with a single org.
SSO for Sites Best Practices
•
Only SAML version 2.0 can be used with Sites.
•
Only Customer Portals and partner portals are supported.
•
Service provider initiated login is not supported.
•
The portal_id
, organization_id
, and siteUrl
attributes are required. If only one is specified, the user receives an error.
•
If all the portal_id
, organization_id
and siteUrl
attributes are populated in the SAML assertion, the user is directed to that Sites login. If the siteUrl
isn’t populated and the other two are, the user is directed to the portal login.
•
More than one portal can be used with a single org.
SEE ALSO:
Single Sign-On Implementation Guide
650
Set Up and Maintain Your Salesforce Organization Single Sign-On
Delegated Authentication Single Sign-On
You can integrate Salesforce with the authentication method of your choice using delegated authentication single sign-on (SSO). You can integrate with your LDAP (Lightweight Directory
Access Protocol) server or authenticate with a token instead of a password. You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their
Salesforce-managed password.
Here’s the process that Salesforce uses to authenticate users with delegated authentication SSO.
1. When a user tries to log in—either online or using the API—Salesforce validates the username and checks the user’s permissions and access settings.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
2. If the user has the “Is Single Sign-On Enabled” user permission, Salesforce doesn’t validate the username and password. Instead, a web services call is made to the user’s org asking it to validate the username and password.
Note: Salesforce doesn’t store, log, or view the password. It’s disposed of immediately after the process completes.
3. The web services call passes the username, password, and sourceIp to your web service. Source
Ip is the IP address where the login request originated. You must create and deploy an implementation of the web service that Salesforce servers can access.
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
4. Your web service implementation validates the passed information and returns either true or false
.
5. If the response is true
, the login process continues, a new session is generated, and the user proceeds to the app. If false
, the user gets an error message that the username and password combination is invalid.
Note: With delegated authentication, a user can experience a slight delay when logging in while the user account becomes available in the org.
SEE ALSO:
Administrator setup guide: Single Sign-On Implementation Guide
651
Set Up and Maintain Your Salesforce Organization Single Sign-On
Configure Salesforce for Delegated Authentication
You manage delegated authentication at the permission level, not at the org level, giving you more flexibility. With permissions, you can require some to use delegated authentication while others use their Salesforce-managed password. You must contact Salesforce to enable the delegated authentication feature before you can configure it in your org.
1. Build your SSO web service.
a. In Salesforce, download the Web Services Description Language (WSDL) file
AuthenticationService.wsdl
. From Setup, enter
API
in the
Quick Find box, then select API, then select Download Delegated Authentication WSDL.
The WSDL file describes the delegated authentication SSO service. Use the WSDL file to generate a server-side stub to which you add your SSO implementation. For example, in the WSDL2Java tool from Apache Axis, use the
--server-side
switch. With the .NET
wsdl.exe tool, use the
/server
switch.
For a sample request and response, see Sample SOAP Message for Delegated Authentication
on page 675.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
USER PERMISSIONS
b. Add a link to your corporate intranet or other internal site that takes the authenticated user’s credentials and passes them through an HTTP POST to the Salesforce login page.
Because Salesforce doesn’t use the password field other than to pass it back to you, don’t pass in a password. Instead, pass another authentication token, such as a Kerberos Ticket, so that your corporate passwords aren’t passed to or from Salesforce.
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
You can configure the Salesforce delegated authentication authority to accept only a token or either a tokenor password. If the authority accepts only a token, Salesforce users can’t log in to Salesforce directly because they can’t create a valid token. However, many authorities support both tokens and passwords In this case, users can log in to
Salesforce through the login page.
When the Salesforce server passes the credentials back to you in the
Authenticate
message, verify them. Then the user can access the app.
2. In Salesforce, specify your org’s SSO gateway URL. From Setup, enter
Single Sign-On
in the
Quick Find
box, select Single
Sign-On Settings, and then click Edit. Enter the URL in the Delegated Gateway URL text box. For security reasons, Salesforce restricts outbound ports to one of the following.
•
80, which accepts only HTTP connections
•
443, which accepts only HTTPS connections
•
1024–66535, which accept HTTP or HTTPS connections
3. Optionally, select Force Delegated Authentication Callout.
Note: Select this option if you must record every login attempt. This option forces a callout to the SSO endpoint regardless of login restriction failures. If you don’t select this option, a call isn’t made to the SSO endpoint if the first login attempt fails due to login restrictions within the Salesforce org.
4. Enable the “Is Single Sign-On Enabled” permission.
Important:
If single sign-on (SSO) is enabled for your org, API and desktop client users can log in to Salesforce unless their profile has IP address restrictions set and they try to log in from outside of the range defined. Also the SSO authority usually handles login lockout policies for users with the “Is Single Sign-On Enabled” permission. However, if the security token is enabled for your org,
652
Set Up and Maintain Your Salesforce Organization Single Sign-On your org’s login lockout settings determine how many times users can attempt to log in with an invalid security token before being locked out of Salesforce.
SEE ALSO:
Delegated Authentication Single Sign-On
Control Individual API Client Access to Your Salesforce Org
You can restrict access to API client apps, such as Data Loader, Salesforce1, and third-party apps.
To restrict access, request the API client whitelisting feature from Salesforce. When whitelisting is enabled, you restrict access to all connected apps until you explicitly approve each app. Approved apps are often called whitelisted apps.
Client apps are external apps that access your org through the API. Salesforce requires you to create a connected app for each client app to provide authentication capabilities. Authentication ensures that users access Salesforce data without revealing username and password credentials. All client applications that aren’t configured as connected apps are denied access to your Salesforce org.
Note:
Contact Salesforce to get the API client whitelisting feature. After it’s enabled, all client access to a connected app is restricted until the Salesforce admin explicitly allows (whitelists) it. This restriction can block access to some apps that your users are using. To avoid unintentional blocks, you can give the users the Use Any API Client permission. Be careful when using this permission. As the name implies, you’re giving up a lot of control.
Step 1: Set Up App Access in Your Org
1. Contact Salesforce to get the API client whitelisting feature enabled for your org.
2. From Setup, enter
Connected Apps
in the Quick Find box, then select Connected Apps.
3. Under the App Access Settings, click Edit.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
4. Select the option, Limit API access to connected apps to those with the policy, Admin
approved users are pre-authorized.
5. Select Allow Visualforce pages to bypass this restriction so that Visualforce pages behave as expected. If unselected, client applications that call getSessionId()
are denied access. Also, apps that make API calls to Salesforce using a session obtained in a Visualforce context are denied access.
6. Click Save.
Step 2: Restrict OAuth Connected App Access (Whitelist Apps)
1. From Setup, enter
Connected Apps
in the Quick Find box and select Connected Apps.
2. Select the name of the connected app.
3. Click Edit Policies, then Under OAuth policies, select Admin approved users are pre-authorized.
4. Click Save.
Step 3: Grant Users Access to OAuth Connected Apps
You give users access to connected apps through permissions. Typically, a list of available connected apps appears under permissions.
Then you select which apps to authorize. If a connected app doesn’t appear on the list, no one has tried to access the org with it yet.
Determine Whether an OAuth Connected App Is Whitelisted
1. From Setup, enter
Connected Apps
in the Quick Find box and select Connected Apps OAuth Usage.
653
Set Up and Maintain Your Salesforce Organization Single Sign-On
2. Under Actions, if Unblock is disabled, the connected app was blocked because API Client Whitelisting is enabled for the org and the connected app isn’t whitelisted.
3. To whitelist the connected app, install the app, and set the app’s OAuth policy Permitted Users option to Admin approved users
are pre-authorized.
4. Grant users access to the connected app.
Note: Salesforce creates connected apps for common Salesforce apps, such as Salesforce1, Data Loader, and Workbench, and installs them in your org automatically. It’s your responsibility to whitelist the connected apps and assign which users can access them.
If users have the Use Any API Client permission, they can access any app, including connected apps having the OAuth policy,
Admin approved users are pre-authorized. The User Any API Client permission is intended for a limited number of admins.
Viewing Single Sign-On Login Errors
If your organization is enabled for Single Sign-On using delegated authentication and has built a
Single Sign-On solution, you can view the most recent Single Sign-On login errors for your organization.
1. From Setup, enter
Delegated Authentication Error History
in the
Quick
Find
box, then select Delegated Authentication Error History.
2. For the twenty-one most recent login errors, you can view the user's username, login time, and the error.
Note: Contact Salesforce to learn more about enabling Single Sign-On for your organization.
USER PERMISSIONS
To view Single Sign-On login errors:
•
Modify All Data
SEE ALSO:
654
Set Up and Maintain Your Salesforce Organization Single Sign-On
SAML
Salesforce Identity uses the XML-based Security Assertion Markup Language (SAML) protocol for single sign-on into Salesforce from a corporate portal or identity provider. With SAML, you can transfer user information between services, such as from Salesforce to Microsoft 365.
The identity provider performs most of the work to set up single sign-on (SSO).
1. Establish a SAML identity provider and gather information about how they connect to Salesforce.
The identity provider sends SSO requests to Salesforce.
2. Provide information to your identity provider, such as the URLs for the start and logout pages
3. Configure Salesforce using the instructions in
Configure SAML Settings for Single Sign-On . Only
this step takes place in Salesforce.
Your identity provider sends SAML assertions to Salesforce using the SAML Web Single Sign-on
Browser POST profile. Salesforce sends SAML responses to the identity provider login URL specified under Setup by entering
Single Sign-On
in the
Quick Find
box, then selecting Single
Sign-On Settings. Salesforce receives the assertion, verifies it against your Salesforce configuration, and, if the assertion is true, allows SSO.
If you have problems with the SAML assertion after you configure Salesforce for SAML, use the
SAML Assertion Validator to validate the SAML assertion
. You can obtain a SAML assertion from your identity provider.
If your users can’t log in using SAML, review the SAML login history to determine why. Sharing the
login history with your identity provider helps resolve problems quickly.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
Click Download Metadata to download an XML file of your SAML configuration settings to send to your identity provider. The identity provider can then upload these configuration settings to connect to your Salesforce orgcommunity.
IN THIS SECTION:
Working With Your Identity Provider
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
Configure SAML Settings for Single Sign-On
When you configure single logout (SLO), users can log out from all connected apps by logging out of Salesforce. Salesforce supports only front-channel SAML SLO when Salesforce is the identity provider (IdP).
Configure SAML Settings for Single Logout (Beta)
You can configure SAML single logout (SLO) in Salesforce for your connected apps. Only front-channel SAML SLO is supported for logout requests from the identity provider (IdP).
View and Edit Single Sign-On Settings
After you’ve configured your Salesforce org to use SAML, you can manage the SAML configuration from the Single Sign-On Settings page.
Customize SAML Start, Error, Login, and Logout Pages
Reviewing the SAML Login History
Validating SAML Settings for Single Sign-On
655
Set Up and Maintain Your Salesforce Organization Single Sign-On
SAML Assertion Validation Errors
Working With Your Identity Provider
1. You must gather the following information from your identity provider before configuring
Salesforce for SAML.
•
The version of SAML the identity provider uses (1.1 or 2.0)
•
The entity ID of the identity provider (also known as the issuer)
•
An authentication certificate.
Tip: Be sure to store the certificate where you can access it from your browser. This will be uploaded to Salesforce in a later step.
•
The following SAML assertion parameters, as appropriate:
–
The SAML user ID type
–
The SAML user ID location
–
Attribute Name
–
Attribute URI
–
Name ID format
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
Note: Attribute Name, Attribute URI, and Name ID format are only necessary if the
is in an Attribute element, and not the name identifier
element of a Subject statement.
USER PERMISSIONS
Tip:
Tip: To set up single sign-on quickly, you can import SAML 2.0 settings from an XML file (or a URL pointing to the file) on the Single Sign-On Settings page. Obtain the
XML from your identity provider.
about these values with your identity provider.
Enable Salesforce for SAML and take a screenshot of the page for your identity provider. From Setup, enter
Single Sign-On Settings
box, then select Single Sign-On Settings, click Edit, then select
in the
Quick Find
SAML Enabled
.
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
2. Work with your identity provider to setup the start, login, and logout pages .
3. Share the
single sign-on.
SEE ALSO:
656
Set Up and Maintain Your Salesforce Organization Single Sign-On
Configure SAML Settings for Single Sign-On
From this page, you can configure your org to use single sign-on. You can also set up just-in-time provisioning. Work with your identity provider to properly configure these settings. For more information about single sign-on, see
Single Sign-On . For more information about just-in-time
provisioning, see About Just-In-Time Provisioning
.
To configure SAML settings for single sign-on from your corporate identity provider to Salesforce:
1.
Gather information from your identity provider.
2.
Provide information to your identity provider.
3.
4.
Set up an identity provider to encrypt SAML assertions (optional).
5.
Enable Just-in-Time user provisioning (optional) .
6.
if you selected
Custom SAML JIT with Apex Handler for Just-in-Time provisioning.
7.
Test the single sign-on connection.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
Set up single sign-on
1. In Salesforce, from Setup, enter
Single Sign-On Settings
in the
Quick Find box, then select Single Sign-On Settings, and click Edit.
2. Select
SAML Enabled
. You must enable SAML to view the SAML single sign-on settings.
3. Specify the SAML version used by your identity provider.
4. Click Save.
5. In SAML Single Sign-On Settings, click the appropriate button to create a configuration, as follows.
•
New - Specify all settings manually.
•
New from Metadata File - Import SAML 2.0 settings from an XML file from your identity provider. This option reads the XML file and uses it to complete as many of the settings as possible.
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
Note: If your XML file contains information for more than one configuration, the first configuration that occurs in the XML file is used.
•
New from Metadata URL - Import SAML 2.0 settings from a public URL. This option reads the XML file at a public URL and uses it to complete as many of the settings as possible. The URL must be added to Remote Site Settings to access it from your Salesforce org.
6. Give this setting a Name for reference within your org.
Salesforce inserts the corresponding API Name value, which you can customize if necessary.
7. Enter the
Issuer
. Often referred to as the entity ID for the identity provider.
8. If your Salesforce org has domains deployed, specify whether you want to use the base domain
( https://saml.salesforce.com
) or the custom domain for the Entity ID. You must share this information with your identity provider.
657
Set Up and Maintain Your Salesforce Organization Single Sign-On
Tip: Generally, use the custom domain as the entity ID. If you already have single sign-on configured before deploying a domain, the base domain is the entity ID. If you are providing Salesforce to Salesforce services, you must specify the custom domain.
9. For the
Identity Provider Certificate
, use the Browse button to locate and upload the authentication certificate issued by your identity provider.
10. For the
Request Signing Certificate
, select the certificate you want from the ones saved in your Certificate and Key
Management settings.
11. For the
Request Signature Method
, select the hashing algorithm for encrypted requests, either
RSA-SHA1
or
RSA-SHA256
.
12. Optionally, if the identity provider encrypts SAML assertions, select the
Assertion Decryption Certificate
they’re using from the ones saved in your Certificate and Key Management settings. This field is available only if your org supports
13. For the
SAML Identity Type
,
SAML Identity Location
, and other fields described in Identity Provider Values
, specify the values provided by your identity provider as appropriate.
14. For the
Service Provider Initiated Request Binding
, select the appropriate value based on the information provided by your identity provider.
15. For SAML 2.0, if your identity provider has specific login or logout pages, specify them in Identity Provider Login URL and Identity
Provider Logout URL, respectively.
Note: These fields appear in Developer Edition and sandbox organizations by default and in production organizations only if My Domain is enabled. The fields do not appear in trial organizations or sandboxes linked to trial organizations.
16. For the
Custom Error URL
, specify the URL of the page that the users are directed to if there's an error during SAML login. It must be a publicly accessible page, such as a public site Visualforce page. The URL can be absolute or relative.
Just-in-Time Provisioning for SAML
.
18. Click Save.
Click Download Metadata to download an XML file of your SAML configuration settings to send to your identity provider. The identity provider can then upload these configuration settings to connect to your Salesforce orgcommunity.
Set up an identity provider to encrypt SAML assertions
When Salesforce is the service provider for inbound SAML assertions, you can pick a saved certificate to decrypt inbound assertions from third party identity providers. You need to provide a copy of this certificate to the identity provider.
1. In the Single Sign-On Settings page in Setup, add a new SAML configuration.
2. In the
Assertion Decryption Certificate
field, specify the certificate for encryption from the ones saved in your
Certificate and Key Management settings.
Note:
If you don’t see the
Assertion Decryption Certificate
field you need to enable multiple single sign-on for your organization.(Applies to orgs created before the Summer ’13 release that aren’t using SAML 1.1).To enable multiple single sign-on configurations, select Enable Multiple Configs on the Single Sign-On Settings page. If this setting has already been enabled, the field appears, and you won’t see the Enable Multiple Configs button.
3. Set the
SAML Identity Location
to the element where your identifier is located.
658
Set Up and Maintain Your Salesforce Organization Single Sign-On
4. When you save the new SAML configuration, your org’s SAML settings value for the
Salesforce Login URL
(also known as the “Salesforce ACS URL”) changes. Get the new value (from the Single Sign-On Settings page in Setup), and click the name of the new SAML configuration. The value is in the
Salesforce Login URL
field.
5. The identity provider must use the
Salesforce Login URL
value.
6. You also need to provide the identity provider with a copy of the certificate selected in the
Assertion Decryption
Certificate
field to use for encrypting assertions.
Enable Just-in-Time user provisioning
1. In SAML Single Sign-On Settings, select
User Provisioning Enabled
.
•
Standard
- This option allows you to provision users automatically using attributes in the assertion.
•
Custom SAML JIT with Apex handler
- This option provisions users based on logic in an Apex class.
2. If you selected
Standard
, click Save and test the single sign-on connection.
. If you selected
Custom SAML JIT with
Apex handler
, proceed to the next step.
3. In the
SAML JIT Handler
field, select an existing Apex class as the SAML JIT handler class. This class must implement the
SamlJitHandler interface . If you do not have an Apex class, you can generate one by clicking
Automatically create a
SAML JIT handler template
. You must edit this class and modify the default content before using it. For more information,
see Edit the SAML JIT handler .
4. In the
Execute Handler As
field, select the user that runs the Apex class. The user must have “Manage Users” permission.
5. Just-in-time provisioning requires a Federation ID in the user type. In
SAML Identity Type
, select
Assertion contains the Federation ID from the User object
. If your identity provider previously used the Salesforce username, communicate to them that they must use the Federation ID.
6. Click Save.
Edit the SAML JIT handler
1. From Setup, enter
Apex Classes
in the
Quick Find
box, then select Apex Classes.
2. Edit the generated Apex SAML JIT handler to map fields between SAML and Salesforce. In addition, you can modify the generated code to support the following:
•
Custom fields
•
Fuzzy profile matching
•
Fuzzy role matching
•
Contact lookup by email
•
Account lookup by account number
•
Standard user provisioning into a community
•
Standard user login into a community
•
Default profile ID usage for portal Just-in-Time provisioning
•
Default portal role usage for portal Just-in-Time provisioning
•
Username generation for portal Just-in-Time provisioning
For example, to support custom fields in the generated handler code, find the “Handle custom fields here” comment in the generated code. After that code comment, insert your custom field code. For more information and examples, see the SamlJitHandler Interface documentation .
659
Set Up and Maintain Your Salesforce Organization Single Sign-On
Note: If your identity provider sends JIT attributes for the Contact or Account object with the User object in the same assertion, the generated handler might not be able to make updates. For a list of User fields that cannot be updated at the same time as the
Contact or Account fields, see sObjects That Cannot Be Used Together in DML Operations .
Test the single sign-on connection
After you have configured and saved your SAML settings, test them by trying to access the identity provider's application. Your identity provider directs the user's browser to POST a form containing SAML assertions to the Salesforce login page. Each assertion is verified, and if successful, single sign-on is allowed.
Validator . You might have to obtain a SAML assertion from your identity provider first.
log in and share that information with your identity provider.
If you are using SAML version 2.0, after you've finished configuring SAML, the OAuth 2.0 Token Endpoint field is populated. Use the tokenwith the web single sign-on authentication flow for OAuth 2.0.
SEE ALSO:
Best Practices for Implementing Single Sign-On
Validating SAML Settings for Single Sign-On
Administrator setup guide: Single Sign-On Implementation Guide
Single Logout (Beta)
When you configure single logout (SLO), users can log out from all connected apps by logging out of Salesforce. Salesforce supports only front-channel SAML SLO when Salesforce is the identity provider (IdP).
Note:
This release contains a beta version of SLO, which means it’s a high-quality feature with known limitations. For information on enabling this feature in your org, contact Salesforce.
SLO isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for SLO in the Salesforce Identity group in the Success Community.
When a user logs out of Salesforce, we send a SAML LogoutRequest to all connected apps for which
SLO is configured. The owners of the connected app acts as service providers. The service providers log out the user and send a SAML LogoutResponse to Salesforce. Users can also initiate SLO from the service providers. When a user logs out of a service provider, a SAML LogoutRequest is sent to
Salesforce. Salesforce then logs out the user and sends SAML LogoutRequests to all the other connected apps for which SLO is configured.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
Implementing SLO brings several advantages to your org.
•
Time savings—With SLO in place, users avoid manually logging out of connected apps. Fewer steps and no toggling through various apps saves time and reduces frustration.
660
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Increased security—Users don’t have to remember to log out of any connected apps. When they log out of Salesforce, they are also logged out of the other apps. Even if a user leaves a desktop unattended, nobody can access these apps
SEE ALSO:
Configure SAML Settings for Single Logout (Beta)
Configure SAML Settings for Single Logout (Beta)
You can configure SAML single logout (SLO) in Salesforce for your connected apps. Only front-channel SAML SLO is supported for logout requests from the identity provider (IdP).
Note:
This release contains a beta version of SLO, which means it’s a high-quality feature with known limitations. For information on enabling this feature in your org, contact Salesforce.
SLO isn’t generally available unless or until Salesforce announces its general availability in documentation or in press releases or public statements. We can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features. You can provide feedback and suggestions for SLO in the Salesforce Identity group in the Success Community.
You can configure SAML IdP SLO from the development side or from the admin side. In the org where the app is created, changes made on the development side reflect on the admin side, but not the other way around. If you change the admin side, change it for the development side so they don’t get out of sync. These steps configure the admin side.
1. Make sure that you have enabled My Domain and IdP.
2. In Setup, enter
apps
in the Quick Find box, then select Manage Connected Apps.
3. Next to the connected app that you want to configure for SLO, click Edit.
4. Under SAML Service Provider Settings, select Enable Single Logout.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
5. For Single Logout URL, enter the SAML SLO endpoint of the connected app service provider (SP). This endpoint is where SAML
LogoutRequests and LogoutResponses are sent when users log out of Salesforce. The SP provides you with this endpoint.
6. Provide your SP with the Salesforce IdP SLO endpoint. It is found in your SAML Login Information as the Single Logout Endpoint and is also found in the SAML Metadata file as the Discovery Endpoint. The format for the endpoint is
https://<domain>.my.salesforce.com/services/auth/idp/saml2/logout
, where
<domain>
is your org’s My Domain name.
661
Set Up and Maintain Your Salesforce Organization Single Sign-On
7. Select the HTTP binding type for SLO. Your SP provides this information.
View and Edit Single Sign-On Settings
After you’ve configured your Salesforce org to use SAML, you can manage the SAML configuration from the Single Sign-On Settings page.
From Setup, enter
Single Sign-On Settings
in the
Quick Find
box, then select
Single Sign-On Settings.
After the SAML configuration completes, the Single Sign-On Settings page displays the generated
URLs and OAuth 2.0 token endpoint.
Field
Salesforce
Login URL
Description
For SAML 2.0. The URL associated with the login for the Web SSO OAuth assertion flow. This URL appears if you configured SAML with “Assertion contains the User's Salesforce username” for
SAML Identity Type and “Identity is in the NameIdentifier element of the Subject statement” for
SAML Identity Location
.
Salesforce
Logout URL
For SAML 2.0. The Salesforce logout URL that users are directed to after they log off. This URL appears if you didn’t specify a value for
Identity
Provider Logout URL
.
OAuth 2.0
Token Endpoint
For SAML 2.0. The ACS URL used when enabling Salesforce as an identity provider in the Web SSO OAuth assertion flow.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
From this page you can do any of the following:
•
Click Edit to change the existing SAML configuration.
•
Click SAML Assertion Validator to validate the SAML settings for your org using a SAML assertion provided by your identity provider.
•
Click Download Metadata to download an XML file of your SAML configuration settings to send to your identity provider. The identity provider can then upload these configuration settings to connect to your Salesforce orgcommunity. Enabled only if your identity provider supports metadata and if you are using SAML 2.0.
SEE ALSO:
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
662
Set Up and Maintain Your Salesforce Organization Single Sign-On
Identity Provider Values
Before you can configure Salesforce for SAML, you must receive information from your identity
provider. This information must be used on the single sign-on page .
The following information might be useful for your identity provider.
Field
SAML Version
Description
The version of SAML your identity provider uses. Salesforce currently supports version 1.1 and 2.0. The SAML specifications for the various versions are linked below:
•
SAML 1.1
•
SAML 2.0
Issuer
Entity ID
The Entity ID—a URL that uniquely identifies your SAML identity provider.
SAML assertions sent to Salesforce must match this value exactly in the
<saml:Issuer>
attribute of SAML assertions.
The issuer in SAML requests generated by Salesforce, and is also the expected audience of any inbound SAML Responses. If you don’t have
domains deployed, this value is always
https://saml.salesforce.com
. If you have domains deployed,
Salesforce recommends that you use your custom domain name. You can find the value on the Single Sign-On Settings page. From Setup, enter
Single Sign-On Settings
in the
Quick Find
box, then select Single Sign-On Settings.
The authentication certificate issued by your identity provider.
Identity
Provider
Certificate
Request
Signing
Certificate
Request
Signature
Method
SAML Identity
Type
The certificate (saved in the Certificate and Key Management page in
Setup) used to generate the signature on a SAML request to the identity provider when Salesforce is the service provider for a service provider-initiated SAML login. If a certificate has not been saved in the
Certificate and Key Management page in Setup, Salesforce uses the global proxy certificate by default. Using a saved signing certificate provides more control over events, such as certificate expiration, than using the global proxy certificate.
The hashing algorithm for encrypted requests, either
RSA-SHA1
or
RSA-SHA256
.
The element in a SAML assertion that contains the string that identifies a Salesforce user. Values are:
Assertion contains User’s Salesforce username
Use this option if your identity provider passes the Salesforce username in SAML assertions.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
663
Set Up and Maintain Your Salesforce Organization Single Sign-On
Field
SAML Identity
Location
Attribute Name
Attribute URI
Name ID Format
Service Provider
Initiated Request
Binding
Identity Provider
Login URL
Description
Assertion contains the Federation ID from the User object
Use this option if your identity provider passes an external user identifier, for example an employee
ID, in the SAML assertion to identify the user.
Assertion contains the User ID from the User object
Use this option if your identity provider passes an internal user identifier, for example a user ID from your Salesforce organization, in the SAML assertion to identify the user.
The location in the assertion where a user should be identified. Values are:
Identity is in the NameIdentifier element of the Subject statement
The Salesforce
Username
or
FederationIdentifier
is located in the
<Subject> statement of the assertion.
Identity is in an Attribute element
The Salesforce
Username
or
FederationIdentifier
is specified in an
<AttributeValue>
, located in the
<Attribute>
of the assertion.
If “
Identity is in an Attribute element
” is selected, this contains the value of the
AttributeName
that is specified in
<Attribute>
that contains the User ID.
If SAML 1.1 is the specified SAML version and “
Identity is in an Attribute element
” is selected, this contains the value of the
AttributeNamespace
that is specified in
<Attribute>
.
If SAML 2.0 is the specified SAML version and “
Identity is in an Attribute element
” is selected, this contains the value for the nameid-format
. Possible values include unspecified
, emailAddress
or persistent
. All legal values can be found in the “Name
Identifier Format Identifiers” section of the Assertions and Protocols SAML 2.0 specification .
If you’re using My Domain, chose the binding mechanism your identity provider requests for your
SAML messages. Values are:
HTTP POST
HTTP POST binding sends SAML messages using base64-encoded HTML forms.
HTTP Redirect
HTTP Redirect binding sends base64-encoded and URL-encoded SAML messages within URL parameters.
No matter what request binding is selected, the SAML Response will always use HTTP POST binding.
For SAML 2.0 only: The URL where Salesforce sends a SAML request to start the login sequence.
the address specified by this field. However, if you need to bypass this value (for example, your identity provider is down) add the login
parameter to the query string for the login page. For example: http://mydomain.my.salesforce.com?login
.
Note: This field appears in Developer Edition production and sandbox organizations by default and in production organizations only if My Domain is enabled. This field does not appear in trial organizations or sandboxes linked to trial organizations.
664
Set Up and Maintain Your Salesforce Organization Single Sign-On
Field
Identity Provider
Logout URL
Description
For SAML 2.0 only: The URL to direct the user to when they click the Logout link in Salesforce. The default is http://www.salesforce.com
.
Note: This field appears in Developer Edition production and sandbox organizations by default and in production organizations only if My Domain is enabled. This field does not appear in trial organizations or sandboxes linked to trial organizations.
Salesforce Login URL
The URL associated with logging in for the Web browser single sign-on flow.
OAuth 2.0 Token
Endpoint
For SAML 2.0 only: The ACS URL used with the API when enabling Salesforce as an identity provider in the Web single sign-on OAuth assertion flow.
Custom Error URL
The URL of the page users should be directed to if there’s an error during SAML login. It must be a publicly accessible page, such as a public site Visualforce page. The URL can be absolute or relative.
Start, Login, and Logout URL Values
In addition to the information used during the single sign-on, your identity provider can also set the start, login, and logout pages. You
can also specify these pages yourself when you configure single sign-on
.
The following information might be useful to your identity provider if they are setting these pages.
•
The SAML specification supports an HTML form that is used to pass the SAML assertion via HTTPS POST.
•
For SAML 1.1, the SAML identity provider can embed name-value pairs in the
TARGET
field to pass this additional information to
Salesforce prepended with a specially formatted URL that contains URL-encoded parameters.
•
The URL for SAML 1.1 to include in the
TARGET
field is as follows: https://saml.salesforce.com/?
•
For SAML 2.0, instead of using the
TARGET
field, the identity providers uses the
<AttributeStatement>
in the SAML assertion to specify the additional information.
•
Salesforce supports the following parameters:
Note: For SAML 1.1 these parameters must be URL-encoded. This allows the URLs, passed as values that include their own parameters, to be handled correctly. For SAML 2.0, these parameters are part of the
<AttributeStatement>
.
–
ssoStartPage
is the page to which the user should be redirected when trying to log in with SAML. The user is directed to this page when requesting a protected resource in Salesforce, without an active session. The ssoStartPage
should be the
SAML identity provider’s login page.
–
startURL
is the URL where you want the user to be directed when sign-on completes successfully. This URL can be absolute, such as
https://yourInstance.salesforce.com/001/o
or it can be relative, such as
/001/o
. This parameter is only used in SAML 1.1. In SAML 2.0, the start URL is the page the user attempted to access before they were authenticated.
–
logoutURL
is the URL where you want the user to be directed when they click the Logout link in Salesforce. The default is http://www.salesforce.com
.
The following sample
TARGET
field is for SAML 1.1, and includes properly-encoded parameters. It passes a customized start page, as well as start and logout URLs embedded as parameter values in the query string.
https://saml.salesforce.com/?ssoStartPage=https%3A%2F
%2Fwww.customer.org%2Flogin%2F&startURL=%2F001%2Fo&logoutURL=http%3A%2F%2Fwww.salesforce.com
665
Set Up and Maintain Your Salesforce Organization Single Sign-On
The following is an example of an
<AttributeStatement>
for SAML 2.0 that contains both ssoStartPage
and logoutURL
:
<saml:AttributeStatement>
<saml:Attribute Name="ssoStartPage"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType"> http://www.customer.org
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="logoutURL"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> https://www.salesforce.com
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
SEE ALSO:
666
Set Up and Maintain Your Salesforce Organization Single Sign-On
Customize SAML Start, Error, Login, and Logout Pages
You can customize the start, error, login, and logout pages for single sign-on users using SAML 1.1
or 2.0. As part of your configuration, decide the following:
•
If your identity provider uses SAML 1.1, the URL to direct the user to when single sign-on successfully completes (known as the start page). This URL can be absolute, such as
https://yourInstance.salesforce.com/001/o
or it can be relative, such as
/001/o
. This URL must be an endpoint that accepts SAML authentication requests.
In SAML 2.0, the start page is the page the user attempted to access before they were authenticated. The SAML 2.0 start page must support Sp-init single sign-on.
If you are using SAML 2.0, you can also use the
RelayState
parameter to control where users get redirected after a successful login.
•
The single sign-on start page where Salesforce sends a SAML request to start the login sequence.
We recommend that if you specify a single sign-on start page that you also specify a logout page. When you specify a logout page, when a user clicks logout or if a user’s session expires, the user is redirected to that page. If you don’t specify a logout page, the user is redirected to the general Salesforce login page.
•
The URL to direct the user to when they click the Logout link in Salesforce (known as the logout page). The default is https://login.salesforce.com
, unless MyDomain is enabled.
If My Domain is enabled, the default is https://customdomain.my.salesforce.com
.
For SAML 2.0, these values can be set either during the single sign-on configuration, or by your identity provider in the login URL or SAML assertion. The order of precedence is:
1. Session cookie—if you’ve already logged in to Salesforce and a cookie still exists, the login and logout pages specified by the session cookie are used.
2. Values passed in from the identity provider.
3. Values from the single sign-on configuration page.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
If you decide not to add these values to the single sign-on configuration, share them with your
You can also decide if you want users to be directed to a custom error page if there’s an error during SAML login: It must be a publicly accessible page, such as a public site Visualforce page. The URL can be absolute or relative. Use this value when you
SEE ALSO:
667
Set Up and Maintain Your Salesforce Organization Single Sign-On
Example SAML Assertions
Share the example SAML assertions with your identity provider so they can determine the format of the information Salesforce requires for successful single-sign on. The assertion must be signed according to the XML Signature specification , using RSA and either SHA-1 or SHA-256.
In addition to the general single sign-on examples for both SAML 1.1 and SAML 2.0, use the following samples for the specific feature:
•
•
•
SOAP message for delegated authentication
•
assertion for just-in-time provisioning
SAML User ID type is the Salesforce username, and SAML User ID location is the
<NameIdentifier>
element in the
<Subject>
element
SAML 1.1:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
<Subject>
<NameIdentifier>[email protected]</NameIdentifier>
</Subject>
SAML 2.0:
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[email protected]</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2008-06-26T02:44:24.173Z"
Recipient="http://localhost:9000"/>
</saml:SubjectConfirmation>
</saml:Subject>
668
Set Up and Maintain Your Salesforce Organization Single Sign-On
SAML User ID type is the Salesforce username, and SAML User ID location is the
<Attribute>
element
SAML 1.1:
<AttributeStatement>
<Subject>
<NameIdentifier>this value doesn't matter</NameIdentifier>
<SubjectConfirmation>
<ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</ConfirmationMethod>
</SubjectConfirmation>
</Subject>
<Attribute AttributeName="MySfdcName" AttributeNamespace="MySfdcURI">
<AttributeValue>[email protected]</AttributeValue>
</Attribute>
</AttributeStatement>
SAML 2.0:
<saml:AttributeStatement>
<saml:Attribute FriendlyName="fooAttrib" Name="SFDC_USERNAME"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> [email protected]
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
SAML User ID type is the Salesforce User object's
FederationIdentifier
field, and SAML User ID location is the
<NameIdentifier>
element in the
<Subject>
element
SAML 1.1:
<AttributeStatement>
<saml:Subject>
<saml:NameIdentifier Format="urn:oasis:names:tc:SAML:1.0:assertion"
NameQualifier="www.saml_assertions.com">
MyName
</saml:NameIdentifier>
</saml:Subject>
</AttributeStatement>
SAML 2.0:
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">MyName</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2008-06-26T02:48:25.730Z"
Recipient="http://localhost:9000/"/>
</saml:SubjectConfirmation>
</saml:Subject>
Note:
The name identifier can be any arbitrary string, including email addresses or numeric ID strings.
669
Set Up and Maintain Your Salesforce Organization Single Sign-On
SAML User ID type is theSalesforce User object's
FederationIdentifier
field, and SAML User ID location is the
<Attribute>
element
SAML 1.1:
<AttributeStatement>
<Subject>
<NameIdentifier>who cares</NameIdentifier>
<SubjectConfirmation>
<ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:bearer</ConfirmationMethod>
</SubjectConfirmation>
</Subject>
<Attribute AttributeName="MyName" AttributeNamespace="MyURI">
<AttributeValue>user101</AttributeValue>
</Attribute>
</AttributeStatement>
SAML 2.0:
<saml:AttributeStatement>
<saml:Attribute FriendlyName="fooAttrib" Name="SFDC_ATTR"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string"> user101
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
SAML User ID type is the Salesforce username, and SAML User ID location is the
<NameIdentifier>
element in the
<Subject>
element
The following is a complete SAML response for SAML 2.0:
<samlp:Response ID="_257f9d9e9fa14962c0803903a6ccad931245264310738"
IssueInstant="2009-06-17T18:45:10.738Z" Version="2.0">
<saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"> https://www.salesforce.com
</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion ID="_3c39bc0fe7b13769cab2f6f45eba801b1245264310738"
IssueInstant="2009-06-17T18:45:10.738Z" Version="2.0">
<saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"> https://www.salesforce.com
</saml:Issuer>
<saml:Signature>
<saml:SignedInfo>
<saml:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<saml:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
670
Set Up and Maintain Your Salesforce Organization Single Sign-On
<saml:Reference URI="#_3c39bc0fe7b13769cab2f6f45eba801b1245264310738">
<saml:Transforms>
<saml:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<saml:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
<ec:InclusiveNamespaces PrefixList="ds saml xs"/>
</saml:Transform>
</saml:Transforms>
<saml:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<saml:DigestValue>vzR9Hfp8d16576tEDeq/zhpmLoo=
</saml:DigestValue>
</saml:Reference>
</saml:SignedInfo>
<saml:SignatureValue>
AzID5hhJeJlG2llUDvZswNUrlrPtR7S37QYH2W+Un1n8c6kTC
Xr/lihEKPcA2PZt86eBntFBVDWTRlh/W3yUgGOqQBJMFOVbhK
M/CbLHbBUVT5TcxIqvsNvIFdjIGNkf1W0SBqRKZOJ6tzxCcLo
9dXqAyAUkqDpX5+AyltwrdCPNmncUM4dtRPjI05CL1rRaGeyX
3kkqOL8p0vjm0fazU5tCAJLbYuYgU1LivPSahWNcpvRSlCI4e
Pn2oiVDyrcc4et12inPMTc2lGIWWWWJyHOPSiXRSkEAIwQVjf
Qm5cpli44Pv8FCrdGWpEE0yXsPBvDkM9jIzwCYGG2fKaLBag==
</saml:SignatureValue>
<saml:KeyInfo>
<saml:X509Data>
<saml:X509Certificate>
MIIEATCCAumgAwIBAgIBBTANBgkqhkiG9w0BAQ0FADCBgzELM
[Certificate truncated for readability...]
</saml:X509Certificate>
</saml:X509Data>
</saml:KeyInfo>
</saml:Signature>
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"> [email protected]
</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2009-06-17T18:50:10.738Z"
Recipient="https://login.salesforce.com"/>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotBefore="2009-06-17T18:45:10.738Z"
NotOnOrAfter="2009-06-17T18:50:10.738Z">
<saml:AudienceRestriction>
<saml:Audience>https://saml.salesforce.com</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="2009-06-17T18:45:10.738Z">
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
671
Set Up and Maintain Your Salesforce Organization Single Sign-On
</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
<saml:AttributeStatement>
<saml:Attribute Name="portal_id">
<saml:AttributeValue xsi:type="xs:anyType">060D00000000SHZ
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="organization_id">
<saml:AttributeValue xsi:type="xs:anyType">00DD0000000F7L5
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="ssostartpage"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType"> http://www.salesforce.com/security/saml/saml20-gen.jsp
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="logouturl"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string"> http://www.salesforce.com/security/del_auth/SsoLogoutPage.html
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
Sample SAML Assertions for Portals
The following shows the portal_id
and organization_id
attributes in a SAML assertion statement:
<saml:AttributeStatement>
<saml:Attribute Name="portal_id">
<saml:AttributeValue xsi:type="xs:anyType">060D00000000SHZ</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="organization_id">
<saml:AttributeValue xsi:type="xs:anyType">00DD0000000F7P5</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
672
Set Up and Maintain Your Salesforce Organization Single Sign-On
The following is a complete SAML assertion statement that can be used for single sign-on for portals. The organization is using federated sign-on, which is included in an attribute (see the
<saml:AttributeStatement>
in bold text in the assertion), not in the subject.
<samlp:Response ID="_f97faa927f54ab2c1fef230eee27cba21245264205456"
IssueInstant="2009-06-17T18:43:25.456Z" Version="2.0">
<saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"> https://www.salesforce.com</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion ID="_f690da2480a8df7fcc1cbee5dc67dbbb1245264205456"
IssueInstant="2009-06-17T18:45:10.738Z" Version="2.0">
<saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"> https://www.salesforce.com
</saml:Issuer>
<saml:Signature>
<saml:SignedInfo>
<saml:CanonicalizationMethod
Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<saml:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
<saml:Reference URI="#_f690da2480a8df7fcc1cbee5dc67dbbb1245264205456">
<saml:Transforms>
<saml:Transform
Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
<saml:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
<ec:InclusiveNamespaces PrefixList="ds saml xs"/>
</saml:Transform>
</saml:Transforms>
<saml:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<saml:DigestValue>vzR9Hfp8d16576tEDeq/zhpmLoo=
</saml:DigestValue>
</saml:Reference>
</saml:SignedInfo>
<saml:SignatureValue>
AzID5hhJeJlG2llUDvZswNUrlrPtR7S37QYH2W+Un1n8c6kTC
Xr/lihEKPcA2PZt86eBntFBVDWTRlh/W3yUgGOqQBJMFOVbhK
M/CbLHbBUVT5TcxIqvsNvIFdjIGNkf1W0SBqRKZOJ6tzxCcLo
9dXqAyAUkqDpX5+AyltwrdCPNmncUM4dtRPjI05CL1rRaGeyX
3kkqOL8p0vjm0fazU5tCAJLbYuYgU1LivPSahWNcpvRSlCI4e
Pn2oiVDyrcc4et12inPMTc2lGIWWWWJyHOPSiXRSkEAIwQVjf
Qm5cpli44Pv8FCrdGWpEE0yXsPBvDkM9jIzwCYGG2fKaLBag==
</saml:SignatureValue>
<saml:KeyInfo>
<saml:X509Data>
<saml:X509Certificate>
MIIEATCCAumgAwIBAgIBBTANBgkqhkiG9w0BAQ0FADCBgzELM
Certificate truncated for readability...
</saml:X509Certificate>
</saml:X509Data>
</saml:KeyInfo>
</saml:Signature>
673
Set Up and Maintain Your Salesforce Organization Single Sign-On
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">null
</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2009-06-17T18:48:25.456Z"
Recipient="https://login.salesforce.com/?saml=02HKiPoin4f49GRMsOdFmhTgi
_0nR7BBAflopdnD3gtixujECWpxr9klAw"/>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotBefore="2009-06-17T18:43:25.456Z"
NotOnOrAfter="2009-06-17T18:48:25.456Z">
<saml:AudienceRestriction>
<saml:Audience>https://saml.salesforce.com</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="2009-06-17T18:43:25.456Z">
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified
</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
<saml:AttributeStatement>
<saml:Attribute FriendlyName="Friendly Name" Name="federationId"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:string">saml_portal_user_federation_id
</saml:AttributeValue>
<saml:AttributeValue xsi:type="xs:string">SomeOtherValue
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="portal_id">
<saml:AttributeValue xsi:type="xs:anyType">060D00000000SHZ
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="organization_id">
<saml:AttributeValue xsi:type="xs:anyType">00DD0000000F7Z5
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="ssostartpage"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">
674
Set Up and Maintain Your Salesforce Organization Single Sign-On http://www.salesforce.com/qa/security/saml/saml20-gen.jsp
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="logouturl"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
<saml:AttributeValue xsi:type="xs:string"> http://www.salesforce.com/qa/security/del_auth/SsoLogoutPage.html
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
Sample SAML Assertion for Sites
The following shows the portal_id
, organization_id
, and siteurl
attributes in a SAML assertion statement:
<saml:AttributeStatement>
<saml:Attribute Name="portal_id">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">060900000004cDk
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="organization_id">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">00D900000008bX0
</saml:AttributeValue></saml:Attribute>
<saml:Attribute Name="siteurl">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">https://ap1.force.com/mySuffix</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
Sample SOAP Message for Delegated Authentication
As part of the delegated authentication single sign-on process, a Salesforce server makes a SOAP 1.1 request to authenticate the user who is passing in the credentials. Here is an example of this type of request. Your single sign-on Web service needs to accept this request, process it, and return a true
or false
response.
Sample Request
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<Authenticate xmlns="urn:authentication.soap.sforce.com">
<username>[email protected]</username>
<password>myPassword99</password>
<sourceIp>1.2.3.4</sourceIp>
675
Set Up and Maintain Your Salesforce Organization
</Authenticate>
</soapenv:Body>
</soapenv:Envelope>
Sample Response Message
<?xml version="1.0" encoding="UTF-8"?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
<AuthenticateResult xmlns="urn:authentication.soap.sforce.com">
<Authenticated>false</Authenticated>
</AuthenticateResult>
</soapenv:Body>
</soapenv:Envelope>
Sample SAML Assertion for Just-In-Time Provisioning
The following is a sample SAML assertion for just in time provisioning.
<saml:AttributeStatement>
<saml:Attribute Name="User.Username"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">[email protected]
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.Phone"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">415-123-1234
</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.LanguageLocaleKey"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">en_US
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.CompanyName"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">Salesforce.com
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.Alias"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">tlee2
676
Single Sign-On
Set Up and Maintain Your Salesforce Organization
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.CommunityNickname"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">tlee2
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.UserRoleId"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">000000000000000
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.Title"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">Mr.
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.LocaleSidKey"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">en_CA
</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">[email protected]
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name=" User.FederationIdentifier"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">tlee2
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.TimeZoneSidKey"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">America/Los_Angeles
</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.ProfileId"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">00ex0000001pBNL
677
Single Sign-On
Set Up and Maintain Your Salesforce Organization
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.IsActive"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">1
</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute Name="User.EmailEncodingKey"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">UTF-8
</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
SEE ALSO:
Single Sign-On
678
Set Up and Maintain Your Salesforce Organization Single Sign-On
Reviewing the SAML Login History
When a user logs in to Salesforce from another application using single sign-on, SAML assertions are sent to the Salesforce login page. The assertions are checked against assertions in the authentication certificate that are specified on the Single Sign-On Settings page in Setup. If a user fails to log in, a message is written to the login history log that indicates why the login failed. In addition, the
SAML Assertion Validator may be automatically populated with the invalid assertion.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
To view the login history, from Setup, enter select Login History. After viewing the login history, you may want to share the information with your identity provider.
The following are the possible failures:
Assertion Expired
Login History
An assertion’s
is more than five minutes old.
in the
Quick Find
box, then
Note: Salesforce does make an allowance of three minutes for clock skew. This means, in practice, that an assertion can be as much as eight minutes after the timestamp time, or three minutes before it. This amount of time may be less if the assertion’s validity period is less than five minutes.
Assertion Invalid
An assertion is not valid. For example, the
<Subject>
element of an assertion might be missing.
Audience Invalid
The value specified in
<Audience>
must be https://saml.salesforce.com
.
Configuration Error/Perm Disabled
Something is wrong with the SAML configuration in Salesforce. For example, the uploaded certificate might be corrupted, or the organization preference might have been turned off. To check your configuration, from Setup, enter
Single Sign-On Settings
in the
Quick
Find
box, then select Single Sign-On Settings. Next, get a sample SAML assertion from your identity provider, and then click
Issuer Mismatched
The issuer or entity ID specified in an assertion does not match the issuer specified in your
Salesforce configuration.
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
Recipient Mismatched
The recipient specified in an assertion does not match the recipient specified in your Salesforce configuration.
Replay Detected
The same assertion ID was used more than once. Assertion IDs must be unique within an organization.
Signature Invalid
The signature in an assertion cannot be validated by the certificate in your Salesforce configuration.
Subject Confirmation Error
The
<Subject>
specified in the assertion does not match the SAML configuration in Salesforce.
SEE ALSO:
679
Set Up and Maintain Your Salesforce Organization Single Sign-On
Validating SAML Settings for Single Sign-On
If your users have difficulty logging into Salesforce after you
configure Salesforce for single sign-on
,
use the SAML Assertion Validator and the login history
to validate the SAML assertions sent by your identity provider.
1. Obtain a SAML assertion from your identity provider. The assertion can be either in plain XML format or base64 encoded.
If a user tries to log in to Salesforce and fails, the invalid SAML assertion is used to automatically populate the SAML Assertion Validator if possible.
2. From Setup, enter
Single Sign-On Settings
in the
Quick Find
box, then select
Single Sign-On Settings, then click SAML Assertion Validator.
3. Enter the SAML assertion into the text box, and click Validate.
4. Share the results of the validation errors with your identity provider.
SEE ALSO:
Best Practices for Implementing Single Sign-On
Administrator setup guide: Single Sign-On Implementation Guide
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
680
Set Up and Maintain Your Salesforce Organization Single Sign-On
SAML Assertion Validation Errors
Salesforce imposes the following validity requirements on assertions:
Authentication Statement
The identity provider must include an
<AuthenticationStatement>
in the assertion.
Conditions Statement
If the assertion contains a
<Conditions>
statement, it must contain a valid timestamp.
Timestamps
The validity period specified in an assertion is honored. In addition, an assertion's timestamp must be less than five minutes old, plus or minus three minutes, regardless of the assertion's validity period setting. This allows for differences between machines. The
NotBefore
and
NotOnOrAfter
constraints must also be defined and valid.
Attribute
If your Salesforce configuration is set to
Identity is in an Attribute element
, the assertion from the identity provider must contain an
<AttributeStatement>
.
If you are using SAML 1.1, both
<AttributeName>
and
<AttributeNamespace> are required as part of the
<AttributeStatement>
.
If you are using SAML 2.0, only
<AttributeName>
is required.
Format
The
Format
attribute of an
<Issuer>
statement must be set to
"urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
or not set at all.
For example:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Federated Authentication is available in: All Editions
Delegated Authentication is available in: Professional,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
Authentication Providers are available in: Professional,
Enterprise, Performance,
Unlimited, and Developer
Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Modify All Data
<saml:Issuer
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">https://www.salesforce.com</saml:Issuer>
The following example is also valid:
<saml:Issuer >https://www.salesforce.com</saml:Issuer>
Issuer
The issuer specified in an assertion must match the issuer specified in Salesforce.
Subject
The subject of the assertion must be resolved to be either the Salesforce username or the Federation ID of the user.
Audience
The
<Audience>
value is required and must match the
Entity ID
from the single sign-on configuration. The default value is https://saml.salesforce.com
.
681
Set Up and Maintain Your Salesforce Organization Single Sign-On
Recipient
The recipient specified in an assertion must match either the Salesforce login URL specified in the Salesforce configuration or the
OAuth 2.0 token endpoint. This is a required portion of the assertion and is always verified.
Signature
A valid signature must be included in the assertion. The signature must be created using the private key associated with the certificate that was provided in the SAML configuration.
Recipient
Verifies that the recipient and organization ID received in the assertion matches the expected recipient and organization ID, as specified in the single sign-on configuration. This is an optional portion of the assertion and is only verified if it’s present. For example:
Recipient that we found in the assertion: http://aalbert-salesforce.com:8081/
?saml=02HKiPoin4zeKLPYxfj3twkPsNSJF3fxsH0Jnq4vVeQr3xNkIWmZC_IVk3
Recipient that we expected based on the Single Sign-On Settings page: http://asmith.salesforce.com:8081/
?saml=EK03Almz90Cik_ig0L97.0BRme6mT4o6nzi0t_JROL6HLbdR1WVP5aQO5w
Organization Id that we expected: 00Dx0000000BQlI
Organization Id that we found based on your assertion: 00D000000000062
Site URL Attribute
Verifies if a valid Sites URL is provided. Values are:
•
Not Provided
•
Checked
•
Site URL is invalid
•
HTTPS is required for Site URL
•
The specified Site is inactive or has exceeded its page limit
SEE ALSO:
About Just-in-Time Provisioning for SAML
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 recently added an employee to your organization, 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. Just-in-Time provisioning works with your SAML identity provider to pass the correct user information to Salesforce in a SAML 2.0 assertion. You can both create and modify accounts this way. Because Just-in-Time provisioning uses SAML to communicate, your organization must have SAML-based single sign-on enabled.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
Benefits of Just-in-Time Provisioning
Implementing Just-in-Time provisioning can offer the following advantages to your organization.
•
Reduced Administrative Costs: Provisioning over SAML allows customers to create accounts on-demand, as part of the single sign-on process. 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.
682
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Increased User Adoption: Users only need to memorize a single password to access both their main site and Salesforce. Users are more likely to use your Salesforce application on a regular basis.
•
Increased Security: Any password policies that you have established for your corporate network are also in effect for Salesforce. In addition, sending an authentication credential that is only valid for a single use can increase security for users who have access to sensitive data.
IN THIS SECTION:
Just-in-Time Provisioning Requirements and SAML Assertion Fields
Just-in-Time Provisioning and SAML Assertion Fields for Portals
Just-in-Time Provisioning for Communities
Just-in-Time Provisioning Errors
Following are the error codes and descriptions for Just-in-Time provisioning for SAML.
SEE ALSO:
Just-in-Time Provisioning Requirements and SAML Assertion Fields
Just-in-Time Provisioning and SAML Assertion Fields for Portals
Just-in-Time Provisioning for Communities
Just-in-Time Provisioning Errors
Just-in-Time Provisioning Requirements and SAML Assertion Fields
Just-in-Time provisioning requires the creation of a SAML assertion. Consider the following when creating your SAML assertion.
•
Provision Version
is supported as an optional attribute. If it isn't specified, the default is 1.0. For example:
<saml:Attribute Name="ProvisionVersion" NameFormat=
"urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">1.0</saml:AttributeValue>
</saml:Attribute>
•
ProfileIDs change per organization, even for standard profiles. To make it easier to find the profile name, Salesforce allows you to do a profile name lookup by passing the
ProfileName
into the
ProfileId
field.
Field Requirements for the SAML Assertion
To correctly identify which object to create in Salesforce, you must use the
User.
prefix for all fields passed in the SAML assertion. In this example, the
User.
prefix has been added to the
Username
field name.
<saml:Attribute
Name="User.Username"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">[email protected]</saml:AttributeValue>
</saml:Attribute>
The following standard fields are supported. Some fields are required.
683
Set Up and Maintain Your Salesforce Organization Single Sign-On
AboutMe
Alias
CallCenter
City
Fields
CommunityNickname
CompanyName
Country
DefaultCurrencyIsoCode
DelegatedApproverId
Department
Division
EmailEncodingKey
EmployeeNumber
Extension
Fax
FederationIdentifier
(insert only)
FirstName
ForecastEnabled
IsActive
LastName
LanguageLocaleKey
LocaleSidKey
Manager
MobilePhone
Phone
ProfileId
ReceivesAdminInfoEmails
ReceivesInfoEmails
State
Required
Y
Y
Y
Comments
If not present, a default is derived from FirstName and LastName.
If not present, a default is derived from the UserName.
Derived from organization settings.
For example,
If not present, a default is derived from the organization settings.
If present, it must match the SAML subject, or the SAML subject is taken instead. Can't be updated with SAML.
If not present, a default is derived from the organization settings.
For example,
User.ProfileId=Standard User
684
Set Up and Maintain Your Salesforce Organization
Fields
Street
TimeZoneSidKey
Title
Username
(insert only)
UserRoleId
Zip
Required
Y
Comments
If not present, a default is derived from the organization settings.
For example, using SAML.
Defaults to “no role” if blank.
Single Sign-On
. Can't update
Other field requirements:
•
Only text type custom fields are supported.
•
Only the insert
and update
functions are supported for custom fields.
•
When using the API for user creation, you can pass the new username into the
User.Username
field. You can also specify the
User.FederationIdentifier
if it is present. However, the
Username
and
FederationIdentifier
fields can't be updated with API.
SEE ALSO:
About Just-in-Time Provisioning for SAML
Just-in-Time Provisioning and SAML Assertion Fields for Portals
Just-in-Time Provisioning for Communities
Just-in-Time Provisioning and SAML Assertion Fields for Portals
With Just-in-Time (JIT) provisioning for portals, you can use a SAML assertion to create customer and partner portal users on the fly the first time they try to log in. This eliminates the need to create user accounts in advance. Because JIT uses SAML to communicate, your organization must have SAML-based single sign-on enabled.
Note: Starting with Summer ’13, Customer Portals and partner portals are no longer available for new organizations. Existing organizations continue to have access to these portals. If you don’t have a portal, but want to easily share information with your customers or partners, try Communities.
Existing organizations using Customer Portals and partner portals may continue to use their portals or transition to Communities.
Contact your Salesforce Account Executive for more information.
Creating Portal Users
The
Portal ID
and
Organization ID
must be specified as part of the SAML assertion. You can find both of these on the company information page for the organization or portal. Because you can also provision regular users, the
Portal ID
is used to distinguish between a regular and portal JIT provisioning request. If no
Portal ID
is specified, then the request is treated as a JIT request for regular platform user. Here are the requirements for a creating a portal user.
•
You must specify a
Federation ID
. If the ID belongs to an existing user account, the user account is updated. In case of an inactive user account, the user account is updated, but left inactive unless
User.IsActive
in the JIT assertion is set to true. If there is no user account with that
Federation ID
, the system creates a new user.
685
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
If the portal isn’t self-registration enabled and a default new user profile and role aren’t specified, the
User.ProfileId
field must contain a valid profile name or ID associated with the portal. In addition, the
User.PortalRole
field must contain a valid portal role name or ID.
Note:
The
User.Role
must be null.
Creating and Modifying Accounts
Create or modify an account by specifying a valid
Account ID
or both the
Account.AccountNumber
and
Account.Name
.
•
Matching is based on
Account.AccountNumber
. If multiple accounts are found, an error is displayed. Otherwise, the account is updated.
•
If no matching account is found, one is created.
•
You must specify the
Account.Owner
in the SAML assertion and ensure that the field level security for the
Account.AccountNumber
field is set to visible for this owner’s profile.
Creating and Modifying Contacts
Create or modify a contact by specifying the a valid Contact ID in
User.Contact
or both the
Contact.Email
and
Contact.LastName
.
•
Matching is based on
Contact.Email
. If multiple contacts are found, an error is displayed. Otherwise, the contact is updated.
•
If no matching contact is found, one is created.
Supported Fields for the Portal SAML Assertion
To correctly identify which object to create in Salesforce, you must use a prefix. In the SAML assertion, use the
Account
prefix for all fields in the Account schema (for example
Account.AccountId
) and
Contact
prefix for all fields in the Contact schema. In this example, the
Contact
prefix has been added to the
field name.
<saml:Attribute
Name="Contact.Email"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">[email protected]</saml:AttributeValue>
</saml:Attribute>
In addition to the standard fields supported for regular SAML JIT users, these fields are supported for accounts. Some fields are required.
Required Comments
Street|City|State|PostalCode|Country
Fields
Billing
AnnualRevenue
Description
Fax
FederationIdentifier
(insert only)
IsCustomerPortal
IsPartner
Y
If present, it must match the SAML subject or the SAML subject is taken instead. Can’t be updated using SAML.
686
Set Up and Maintain Your Salesforce Organization
Fields
NumberOfEmployees
Ownership
Phone
Portal Role
Rating
Street
TickerSymbol
UserRoleId
Website
Zip
Required
Y
Use
Worker
Defaults to “no role” if blank.
Comments
for all portal users.
In addition to the standard fields supported for regular SAML JIT users, these fields are supported for contacts.
Required Comments Fields
Birthdate
CanAllowPortalSelfReg
Department
Description
DoNotCall
Fax
HasOptedOutofEmail
HasOptedOutofFax
HomePhone
LeadSource
Mailing
MobilePhone
Owner
Other
OtherPhone
Phone
Salutation
Name|Phone
Street|City|State|PostalCode|Country
Street|City|State|PostalCode|Country
687
Single Sign-On
Set Up and Maintain Your Salesforce Organization Single Sign-On
Fields Required Comments
Title
SEE ALSO:
About Just-in-Time Provisioning for SAML
Just-in-Time Provisioning Requirements and SAML Assertion Fields
Just-in-Time Provisioning for Communities
Just-in-Time Provisioning for Communities
With Just-in-Time (JIT) provisioning for Communities, you can use a SAML assertion to create customer and partner community users on the fly the first time they try to log in from an identity provider. This eliminates the need to create user accounts in advance. Because
JIT uses SAML to communicate, your organization must have SAML-based single sign-on enabled. Then, you can work with the identity provider to generate the necessary SAML assertions for JIT.
SAML Single Sign-on Settings
Follow the instructions for
Configure SAML Settings for Single Sign-On
with
SAML Enabled
. Set the values for your configuration, as needed, and also include the following values specific to your community for JIT provisioning.
1. Check
User Provisioning Enabled
.
Note:
•
Just-in-time provisioning requires a Federation ID in the user type. In
SAML User ID Type
, select Assertion contains the Federation ID from the User object.
•
If your identity provider previously used the Salesforce username, communicate to them that they must use the Federation
ID.
2. The Entity ID should be unique across your organization and begin with https
. You can’t have two SAML configurations with the same Entity ID in one organization. Specify whether you want to use the base domain ( https://saml.salesforce.com
) or the community URL (such as https://acme.force.com/customers
) for the Entity ID. You must share this information with your identity provider.
Tip: Generally, use the community URL as the entity ID. If you are providing Salesforce to Salesforce services, you must specify the community URL.
3. In
SAML User ID Type
, select
Assertion contains the Federation ID from the User object
. If your identity provider previously used the Salesforce username, communicate to them that they must use the Federation ID.
Creating and Modifying Community Users
The SAML assertion needs the following.
•
A
Recipient
URL. This is the Community Login URL from the SAML Single Sign-On Settings detail page in your organization.
The URL is in the following form.
https://<community_URL>/login?so=<orgID>
For example,
Recipient="https://acme.force.com/customers/login?so=00DD0000000JsCM"
where acme.force.com/customers
is the community home page and
00DD0000000JsCM
is the
Organization ID
.
688
Set Up and Maintain Your Salesforce Organization Single Sign-On
If an Assertion Decryption Certificate has been uploaded to the organization’s SAML Single Sign-On Settings, include the certificate
ID in the URL using the sc
parameter, such as
Recipient="https://acme.force.com/customers/login?so=00DD0000000JsCM&sc=0LE000000Dp" where
0LE000000Dp
is the certificate ID.
•
Salesforce attempts to match the
Federation ID
in the subject of the SAML assertion (or in an attribute element, depending upon how the SAML Identity Location is defined in the SAML Single Sign-On Settings) to the
FederationIdentifier
field of an existing user record.
1. If a matching user record is found, Salesforce uses the attributes in the SAML assertion to update the specified fields.
2. If a user with a matching user record isn't found, then Salesforce searches the contacts for a match based on the
Contact
ID
(
User.Contact
) or email (
Contact.Email
).
Contact.Email
and
Contact.LastName
are both required properties when
User.Contact
is not specified, but matching is only based on
Contact.Email
when both properties exist.
i. If a matching contact record is found, Salesforce uses the attributes in the SAML assertion to update the specified contact fields, and then inserts a new user record.
ii. If a matching contact record isn't found, then Salesforce searches the accounts for a match based on the
Contact.Account
or
Account.AccountNumber
specified in the SAML assertion.
Account.AccountNumber
and
Account.Name
are both required properties when
Contact.Account
is not specified, but matching is only based on
Account.AccountNumber
when both properties exist.
i. If a matching account record is found, Salesforce inserts a new user record and updates the account records based the attributes provided in the SAML assertion.
ii. If a matching account record isn't found, Salesforce inserts new account, contact, and user records based on the attributes provided in the SAML assertion.
In the case of an inactive user account, the user account is updated, but left inactive unless
User.IsActive
in the JIT assertion is set to true. If there is no user account with that
Federation ID
, the system creates a new user.
•
If the community doesn’t have self-registration enabled, and a default new user profile and role aren’t specified, the
User.ProfileId
field must contain a valid profile name or ID associated with the community.
Salesforce attempts to match the
Federation ID
in the subject of the SAML assertion to the
FederationIdentifier
field of an existing user record.
Note: Salesforce also supports custom fields on the User object in the SAML assertion. Any attribute in the assertion that starts with
User
is parsed as a custom field. For example, the attribute
User.NumberOfProductsBought__c
in the assertion is placed into the field
NumberOfProductsBought
for the provisioned user. Custom fields are not supported for Accounts or Contacts.
Supported Fields for the Community SAML Assertion
To correctly identify which object to create in Salesforce, you must use a prefix. In the SAML assertion, use the
Account
prefix for all fields in the Account schema (for example
Account.AccountId
) and
Contact
prefix for all fields in the Contact schema. In this example, the
Contact
prefix has been added to the
field name.
<saml:Attribute
Name="Contact.Email"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">[email protected]</saml:AttributeValue>
</saml:Attribute>
In addition to the standard fields supported for regular SAML JIT users, these fields are supported for accounts.
689
Set Up and Maintain Your Salesforce Organization Single Sign-On
Fields
Billing
AnnualRevenue
Description
Fax
FederationIdentifier
(insert only)
IsCustomerPortal
IsPartner
NumberOfEmployees
Ownership
Phone
Portal Role
Rating
Street
TickerSymbol
UserRoleId
Website
Zip
Required Comments
Street|City|State|PostalCode|Country
Y If present, it must match the SAML subject or the SAML subject is taken instead. Can’t be updated using SAML.
Defaults to “no role” if blank.
In addition to the standard fields supported for regular SAML JIT users, these fields are supported for contacts.
Required Comments Fields
Birthdate
CanAllowPortalSelfReg
Department
Description
DoNotCall
Fax
HasOptedOutofEmail
HasOptedOutofFax
HomePhone
Name|Phone
690
Set Up and Maintain Your Salesforce Organization
LeadSource
Fields
Mailing
MobilePhone
Owner
Other
OtherPhone
Phone
Salutation
Title
Required Comments
Street|City|State|PostalCode|Country
Street|City|State|PostalCode|Country
SEE ALSO:
About Just-in-Time Provisioning for SAML
Just-in-Time Provisioning Requirements and SAML Assertion Fields
Just-in-Time Provisioning Errors
Following are the error codes and descriptions for Just-in-Time provisioning for SAML.
SAML errors are returned in the URL parameter, for example: http://login.salesforce.com/identity/jit/saml-error.jsp?
ErrorCode=5&ErrorDescription=Unable+to+create+user&ErrorDetails=
INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST+TimeZoneSidKey
Note: Salesforce redirects the user to a custom error URL if one is specified in your SAML configuration.
8
9
3
4
5
6
Code
1
2
Error Messages
Description
Missing Federation Identifier
Mis-matched Federation Identifier
Invalid organization ID
Unable to acquire lock
Unable to create user
Unable to establish admin context
Unrecognized custom field
Unrecognized standard field
Error Details
MISSING_FEDERATION_ID
MISMATCH_FEDERATION_ID
INVALID_ORG_ID
USER_CREATION_FAILED_ON_UROG
USER_CREATION_API_ERROR
ADMIN_CONTEXT_NOT_ESTABLISHED
UNRECOGNIZED_CUSTOM_FIELD
UNRECOGNIZED_STANDARD_FIELD
691
Single Sign-On
Set Up and Maintain Your Salesforce Organization
28
30
31
32
24
25
26
27
20
22
23
18
19
39
40
41
37
38
33
34
35
36
15
16
13
14
Code
11
12
17
Description
License limit exceeded
Federation ID and username do not match
Error Details
LICENSE_LIMIT_EXCEEDED
MISMATCH_FEDERATION_ID_AND_USERNAME_ATTRS
Unsupported provision API version
Username change isn't allowed
UNSUPPORTED_VERSION
USER_NAME_CHANGE_NOT_ALLOWED
Custom field type isn't supported UNSUPPORTED_CUSTOM_FIELD_TYPE
Unable to map a unique profile ID for the given profile name
PROFILE_NAME_LOOKUP_ERROR
ROLE_NAME_LOOKUP_ERROR Unable to map a unique role ID for the given role name
Invalid account
Missing account name
Missing account number
INVALID_ACCOUNT_ID
MISSING_ACCOUNT_NAME
MISSING_ACCOUNT_NUMBER
Unable to create account
Invalid contact
Missing contact email
Missing contact last name
Unable to create contact
Multiple matching contacts found
Multiple matching accounts found
Invalid account owner
Invalid portal profile
Account change is not allowed
ACCOUNT_CREATION_API_ERROR
INVALID_CONTACT
MISSING_CONTACT_EMAIL
MISSING_CONTACT_LAST_NAME
CONTACT_CREATION_API_ERROR
MULTIPLE_CONTACTS_FOUND
MULTIPLE_ACCOUNTS_FOUND
INVALID_ACCOUNT_OWNER
INVALID_PORTAL_PROFILE
ACCOUNT_CHANGE_NOT_ALLOWED
Unable to update account
Unable to update contact
Invalid standard account field value
Contact change not allowed
Invalid portal role
Unable to update portal role
Invalid SAML JIT Handler class
Invalid execution user
Execution error
ACCOUNT_UPDATE_FAILED
CONTACT_UPDATE_FAILED
INVALID_STANDARD_ACCOUNT_FIELD_VALUE
CONTACT_CHANGE_NOT_ALLOWED
INVALID_PORTAL_ROLE
CANNOT_UPDATE_PORTAL_ROLE
INVALID_JIT_HANDLER
INVALID_EXECUTION_USER
APEX_EXECUTION_ERROR
Single Sign-On
692
Set Up and Maintain Your Salesforce Organization Single Sign-On
Code
42
Description
Updating a contact with Person Account isn’t supported
Error Details
UNSUPPORTED_CONTACT_PERSONACCT_UPDATE
SEE ALSO:
About Just-in-Time Provisioning for SAML
Just-in-Time Provisioning and SAML Assertion Fields for Portals
External Authentication Providers
Authentication providers let your users log in to your Salesforce org using their login credentials from an external service provider. Salesforce provides authentication providers for apps that support the OpenID Connect protocol, such as Google, Facebook, Twitter, and LinkedIn. For apps that don’t support OpenID Connect, Salesforce provides an Apex
Auth.AuthProviderPluginClass
abstract class to create a custom authentication provider.
You can enable users to log in to your Salesforce org using their login credentials from an external service provider such as Facebook or Janrain.
Note:
Social Sign-On (Salesforce Classic) (11:33 minutes)
Learn how to configure single sign-on (SSO) and OAuth-based API access to Salesforce from other sources of user identity.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
Do the following to set up a custom authentication provider for SSO.
•
Configure the service provider website.
•
Create a registration handler using Apex.
•
Define the authentication provider in your org.
When set up is complete, the authentication provider flow is as follows.
1. The user tries to log in to Salesforce using a third-party (external) identity.
2. The login request is redirected to the external authentication provider.
3. The user follows the third-party login process and approves access.
4. The external authentication provider redirects the user to Salesforce with credentials.
5. The user is signed in to Salesforce.
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
Note: If users have an existing Salesforce session, after authentication with the third party, they’re redirected to the page where they can approve the link to their Salesforce account.
Define Your Authentication Provider
Salesforce supports the following authentication providers.
•
•
•
•
Microsoft Access Control Service
693
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Salesforce
•
•
Janrain
•
Any service provider who implements the OpenID Connect protocol
•
Any service provider who supports OAuth but not the OpenID Connect protocol
Add Functionality to Your Authentication Provider
You can add functionality to your authentication provider by using additional request parameters.
•
Scope —Customizes the permissions requested from the third party.
•
—Enables the provider to be used with a site.
•
StartURL —Sends the user to a specified location after authentication.
•
—Sends the user to a specific community after authentication.
•
on page 725—Sends the user to a specific endpoint for authentication (Salesforce authentication providers, only).
Create an Apex Registration Handler
You must implement a registration handler to use authentication providers for SSO. The Apex registration handler
class must implement the
Auth.RegistrationHandler
interface, which defines two methods. Salesforce invokes the appropriate method on callback, depending on whether the user has used this provider before or not. When you create the authentication provider, you can automatically create an Apex template class for testing purposes. For more information, see RegistrationHandler in the
Force.com
Apex Code Developer's Guide
.
IN THIS SECTION:
Configure a Facebook Authentication Provider
Configure a Facebook authentication provider to let your users log in to your Salesforce org using their Facebook credentials.
Configure a Google Authentication Provider
Configure Google as an authentication provider to let users log in to your Salesforce org using their Google credentials.
Configure a Janrain Authentication Provider
Configure Janrain as an authentication provider to let users log in to your Salesforce org using their Janrain credentials.
Configure a Salesforce Authentication Provider
To configure a Salesforce authentication provider, create a connected app that uses single sign-on (SSO).
Configure an OpenID Connect Authentication Provider
You can use any third-party web app that implements the server side of the OpenID Connect protocol, such as Amazon, Google, and PayPal, as an authentication provider.
Access Control Service Authentication Provider
You can use Microsoft Access Control Service as an authentication provider using the OAuth protocol. Authorization is typically done by a Microsoft Office 365 service like SharePoint
®
Online.
Configure a LinkedIn Authentication Provider
Configure LinkedIn as an authentication provider to let users log in to your Salesforce org using their LinkedIn credentials.
Configure a Twitter Authentication Provider
Configure Twitter as an authentication provider to let users log in to a Salesforce org from their Twitter account.
694
Set Up and Maintain Your Salesforce Organization Single Sign-On
Use Salesforce-Managed Values in the Auth. Provider Setup Page
You can choose to let Salesforce create key values when setting up a Facebook, Salesforce, LinkedIn, Twitter, or Google authentication provider. Having Salesforce generate the key values saves you the time and effort of creating your own third-party app.
Create a Custom External Authentication Provider
Create a custom single sign-on (SSO) authentication provider to let users log in to your Salesforce org using their non-Salesforce credentials. Implement a custom external authentication provider if your OAuth app doesn’t support OpenID Connect. If your app supports OpenID Connect, you can use one of the authentication providers that Salesforce provides.
Configure a Facebook Authentication Provider
Configure a Facebook authentication provider to let your users log in to your Salesforce org using their Facebook credentials.
Configuring Facebook as an authentication provider involves these high-level steps.
1.
Set up a Facebook app, making Salesforce the app domain.
2.
Define a Facebook authentication provider in your Salesforce org.
3.
your Facebook app to use the Callback URL generated by Salesforce as the Facebook website URL.
4.
the connection.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
Set Up a Facebook App
Before you can configure Facebook for your Salesforce org, you must set up an app in Facebook.
Note: You can skip this step by allowing Salesforce to use its own default app. For more information, see Use Salesforce-Managed Values in the Auth. Provider Setup Page .
1. Go to the Facebook website and create an app.
2. Modify the app settings and set the Application Domain to Salesforce.
3. Note the app ID and the app secret.
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
Define a Facebook Provider in Your Salesforce Org
You need the Facebook app ID and app secret to set up a Facebook provider in your Salesforce org.
Note: You can skip this step by allowing Salesforce to manage the values for you. For more information, see Use Salesforce-Managed
Values in the Auth. Provider Setup Page .
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select Facebook.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is MyFacebookProvider, your single sign-on (SSO) URL is similar to: https://login.salesforce.com/auth/sso/00Dx00000000001/MyFacebookProvider
.
6. Use the Facebook app ID for the
Consumer Key
field.
7. Use the Facebook app secret for the
Consumer Secret
field.
695
Set Up and Maintain Your Salesforce Organization Single Sign-On
8. Optionally, set the following fields.
a. Enter the base URL from Facebook for the Authorize Endpoint URL. For example, https://www.facebook.com/v2.2/dialog/oauth
. If you leave this field blank, Salesforce uses the version of the Facebook API that your app uses.
Tip:
You can add query string parameters to the base URL, if necessary. For example, to get a refresh token from Facebook for offline access, use https://accounts.facebook.com/o/oauth2/auth?access_type=offline&approval_prompt=force
.
You need the approval_prompt
parameter to ask the user to accept the refresh action so that Facebook continues to provide refresh tokens after the first one.
b. Enter the Token Endpoint URL from Facebook. For example, https://www.facebook.com/v2.2/dialog/oauth
.
If you leave this field blank, Salesforce uses the version of the Facebook API that your app uses.
c. Enter the User Info Endpoint URL to change the values requested from Facebook’s profile API. See https://developers.facebook.com/docs/facebook-login/permissions/v2.0#reference-public_profile for more information on fields. The requested fields must correspond to the requested scopes. If you leave this field blank, Salesforce uses the version of the Facebook API that your app uses.
d.
Default Scopes
to send along with the request to the authorization endpoint. Otherwise, the hardcoded defaults for the provider type are used (see Facebook’s developer documentation for these defaults).
For more information, see Use the Scope Parameter .
e.
Custom Error URL
for the provider to use to report any errors.
f.
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
g. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note: A
Registration Handler
class is required for Salesforce to generate the SSO initialization URL.
h. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
i. To use a portal with your provider, select the portal from the Portal dropdown list.
j. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
9. Click Save.
Note the generated Auth. Provider Id value. You use it with the
Auth.AuthToken
Apex class.
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Salesforce admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
696
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Single Sign-On Initialization URL—Use this URL to perform SSO into Salesforce from a third party using its third-party credentials.
The user opens this URL in a browser and logs in to the third party. The third party either creates a user or updates an existing user.
Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use this URL to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Oauth-Only Initialization URL—Use this URL to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token. This flow doesn’t provide for future SSO functionality.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider must redirect to the callback URL with information for each client configuration URL.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Update Your Facebook App
After defining the Facebook authentication provider in your Salesforce org, go back to Facebook and update your app to use the Callback
URL as the Facebook Website Site URL.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider detail page. It redirects you to Facebook and asks you to sign in. You’re then asked to authorize your app. After you authorize, you’re redirected back to Salesforce.
SEE ALSO:
Use Request Parameters with Client Configuration URLs
External Authentication Providers
Configure a Google Authentication Provider
Configure Google as an authentication provider to let users log in to your Salesforce org using their
Google credentials.
Complete these steps to configure Google as an authentication provider.
1.
Set up a Google app, making Salesforce the application domain.
2.
Define a Google authentication provider in your Salesforce org.
3.
your Google app to use the callback URL generated by Salesforce as the Google website site URL.
4.
the connection.
Set Up a Google App
Before you can configure Google for your Salesforce org, you must set up an app in Google.
Note:
You can skip this step by allowing Salesforce to use its own default app. For more information, see Use Salesforce-Managed Values in the Auth. Provider Setup Page .
1. Go to the Google website and create a new app.
2. Modify the app settings and set the application domain to Salesforce.
3. Note the app ID and the app secret.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
697
Set Up and Maintain Your Salesforce Organization Single Sign-On
Define a Google Provider in Your Salesforce Org
You need the Google app ID and app secret to set up a Google provider in your Salesforce org.
Note:
You can skip this step by allowing Salesforce to manage the values for you. For more information, see Use Salesforce-Managed
Values in the Auth. Provider Setup Page .
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select Google.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is MyGoogleProvider, your SSO URL is similar to: https://login.salesforce.com/auth/sso/00Dx00000000001/MyGoogleProvider
.
6. Use the Google app ID for the
Consumer Key
field.
7. Use the Google app secret for the
Consumer Secret
field.
8. Optionally, set the following fields.
a.
Authorize Endpoint URL
—Specify the base authorization URL from Google. For example, https://accounts.google.com/o/oauth2/authorize
. The URL must start with https://accounts.google.com/o/oauth2
.
Tip: You can add query string parameters to the base URL, if necessary. For example, to get a refresh token from Google for offline access, use https://accounts.google.com/o/oauth2/auth?access_type=offline&approval_prompt=force
.
You need the approval_prompt
parameter to ask the user to accept the refresh action so that Google continues to provide refresh tokens after the first one.
b.
Token Endpoint URL
—Specify the OAuth token URL from Google. For example, https://accounts.google.com/o/oauth2/accessToken
. The URL must start with https://accounts.google.com/o/oauth2
.
c.
User Info Endpoint URL
—Change the values requested from Google’s profile API. The URL must start with https://www.googleapis.com/oauth2/
.
d.
Default Scopes
—Send with the request to the authorization endpoint. Otherwise, the hardcoded defaults for the provider type are used. For the defaults, see Google’s developer documentation .
For more information, see Use the Scope Parameter
.
e.
Custom Error URL
—Specify a URL for the provider to report errors.
f.
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
g. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note: A
Registration Handler
class is required for Salesforce to generate the SSO initialization URL.
698
Set Up and Maintain Your Salesforce Organization Single Sign-On
h. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
i. To use a portal with your provider, select the portal from the Portal list.
j. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
9. Click Save.
Note the generated
Auth. Provider Id
value. You use it with the
Auth.AuthToken
Apex class.
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this
URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
Single Sign-On Initialization URL—Use this URL to perform single sign-on (SSO) into Salesforce from a third party (using third-party credentials). The user opens this URL in a browser and signs in to the third party. The third party either creates a user or updates an existing user. Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use this URL to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Oauth-Only Initialization URL—Use this URL to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token;. This flow doesn’t provide for future SSO functionality.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider redirects to the callback URL with information for each client configuration URL.
Client configuration URLs support other request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from a third party, or go to a location after authenticating.
Update Your Google App
After defining the Google authentication provider in your Salesforce org, go back to Google and update your app to use the callback
URL as the Google website site URL.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to Google and asks you to sign in.
You’re then asked to authorize your app. After you authorize, you’re redirected to Salesforce.
699
Set Up and Maintain Your Salesforce Organization Single Sign-On
Configure a Janrain Authentication Provider
Configure Janrain as an authentication provider to let users log in to your Salesforce org using their
Janrain credentials.
Setting up a Janrain authentication provider is slightly different from setting up other providers.
You don’t use the single sign-on initialization URL that you obtain after registering your provider with Salesforce to start the flow. Instead, you use Janrain’s login widget that’s deployed on your site.
To set up your Janrain provider:
1.
Register your app with Janrain and get an
apiKey
.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
2.
Define the Janrain authentication provider in your Salesforce org.
3.
the login widget code from Janrain.
4.
Set up a site that calls the login widget code in your Salesforce org.
Register Your App
USER PERMISSIONS
Sign up for a Janrain account from the need the apiKey
.
Janrain website . After you have your Janrain account, you
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
1. Select Deployment > Sign-in for Web > Handle Tokens.
2. Copy the apiKey
. You need the key later when creating the Janrain provider in your Salesforce org.
3. Add
Salesforce
to the Janrain domain whitelist in your Janrain account at Deployment > Application Settings > Domain
Whitelist.
Define the Janrain Provider in Your Salesforce Org
You need the Janrain API key to create a Janrain provider in your Salesforce org.
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select Janrain.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the callback URL. For example, if the URL suffix of your provider is MyJanrainProvider, your callback URL is similar to https://login.salesforce.com/services/authcallback/00D300000007CvvEAE/MyJanrainProvider
.
6. Use the Janrain apiKey
value for the
Consumer Secret
.
7. Optionally, enter a custom error URL for the provider to use to report errors.
8. Optionally, enter a custom logout URL to provide a destination for users after they log out if they authenticated using the single sign-on (SSO) flow. Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http or https prefix, such as https://acme.my.salesforce.com
.
9. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note: A
Registration Handler
class is required for Salesforce to generate the single sign-on initialization URL.
700
Set Up and Maintain Your Salesforce Organization Single Sign-On
10. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
11. To use a portal with your provider, select the portal from the Portal dropdown list.
12. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
13. Click Save.
Note the value of the generated callback URL. You need this URL to complete the Janrain setup.
Several client configuration parameters are available after configuring Janrain as the authentication provider. Use them for the flowtype value in the callback URL with your Janrain login widget.
•
test
—Make sure that the third-party provider is set up correctly. The admin configures a Janrain widget to use flowtype=test
, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
link
—Link existing Salesforce users to a third-party account . The user goes to a page with a Janrain widget configured to use flowtype=link
, signs in to the third party, signs in to Salesforce, and approves the link.
•
sso
—Perform SSO into Salesforce from a third party (using third-party credentials). The user goes to a page with a Janrain widget configured to use flowtype=sso
, and signs in to the third party. The third party either creates a user or updates an existing user.
Then the third party signs the user into Salesforce as that user.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Get the Login Widget Code from Janrain
You need to get the login widget code from Janrain for your Salesforce org.
1. From your Janrain account, select Application > Sign-in for Web > Get the Code.
2. Enter the callback URL value from your Janrain provider information in your Salesforce org along with the query parameter flowtype=sso
as the token URL. For example, https://login.salesforce.com/services/authcallback/00DD##############/JanrainApp?flowtype=sso
For a domain created with My Domain, replace login.salesforce.com
with your My Domain name.
For a community, add the community
parameter and pass it to the login widget as the token URL. For example, janrain.settings.tokenUrl='https://login.salesforce.com/services/authcallback/00DD##############/JanrainApp'
+'?flowtype=sso&community='+encodeURIComponent('https://acme.force.com/customers');
Create a Site to Call the Login Widget
1. Enable Sites.
2. Create a page and copy the login widget code to the page.
701
Set Up and Maintain Your Salesforce Organization Single Sign-On
3. Create a site and specify the page that you created as the home page for the site.
SEE ALSO:
Use Request Parameters with Client Configuration URLs
External Authentication Providers
Configure a Salesforce Authentication Provider
To configure a Salesforce authentication provider, create a connected app that uses single sign-on
(SSO).
Configuring a Salesforce authentication provider involves these high-level steps.
1.
2.
Define the Salesforce authentication provider in your org .
3.
.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
Create a Connected App
You can create a connected app from either Lightning Experience or Salesforce Classic.
In Lightning Experience, from Setup, enter
App
in the
Quick Find
box, select App Manager, then click New Connected App.
In Salesforce Classic, from Setup, enter
Apps
in the
Quick Find
box, select Apps. Then, under the Connected Apps section, click New.
After you finish creating a connected app, note the values from the
Consumer Key
and
Consumer Secret
fields.
Note: You can skip this step by allowing Salesforce to use its own default app. For more information, see Use Salesforce-Managed Values in the Auth. Provider Setup Page .
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
Define the Salesforce Authentication Provider in Your Org
To set up the authentication provider in your org, you need the values from the
Consumer Key
and
Consumer Secret
fields of the connected app definition.
Note: You can skip this step by allowing Salesforce to manage the values for you. For more information, see Use Salesforce-Managed
Values in the Auth. Provider Setup Page .
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select Salesforce.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is MySFDCProvider, your SSO URL is similar to https://login.salesforce.com/auth/sso/00Dx00000000001/MySFDCProvider
.
6. Paste the consumer key value from the connected app definition into the
Consumer Key
field.
7. Paste the consumer secret value from the connected app definition into the
Consumer Secret
field.
8. Optionally, set the following fields.
702
Set Up and Maintain Your Salesforce Organization Single Sign-On
a.
Authorize Endpoint URL
to specify an OAuth authorization URL.
For the
Authorize Endpoint URL
, the host name can include a sandbox or custom domain name (created using My
Domain), but the URL must end in
.salesforce.com
, and the path must end in
/services/oauth2/authorize
.
For example, https://login.salesforce.com/services/oauth2/authorize
.
b.
Token Endpoint URL
to specify an OAuth token URL.
For the
Token Endpoint URL
, the host name can include a sandbox or custom domain name (created using My Domain), but the URL must end in
.salesforce.com
, and the path must end in
/services/oauth2/token
. For example, https://login.salesforce.com/services/oauth2/token
.
c.
Default Scopes
to send along with the request to the authorization endpoint. Otherwise, the hardcoded default is used.
For more information, see Use the Scope Parameter
.
d.
Include identity organization's organization ID for third-party account linkage
.
This option doesn't appear if the authentication provider was created after the Winter ’15 release. Before Winter '15, the destination org couldn't differentiate between users with the same user ID on different orgs, for example, between a production and sandbox org. As of Winter ’15, user identities contain the org ID, so this option doesn’t appear. For older authentication providers, enable this option to keep the identities separate in the destination org. However, if you enable this option, your users must reapprove all their third-party links. The links are listed in the Third-Party Account Links section of a user’s detail page.
e.
Custom Error URL
for the provider to use to report any errors.
f.
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
9. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note: A
Registration Handler
class is required for Salesforce to generate the SSO initialization URL.
10. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
11. To use a portal with your provider, select the portal from the Portal dropdown list.
12. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
13. Click Save.
Note the value of the Client Configuration URLs. You need the callback URL to complete the last step. Use the Test-Only initialization
URL to check your configuration. Also note the
Auth. Provider Id
value because you use it with the
Auth.AuthToken
Apex class.
14. Return to the connected app definition that you created earlier from Setup. Paste the callback URL value from the authentication provider into the
Callback URL
field.
Several client configuration URLs are generated after defining the authentication provider.
703
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Test-Only Initialization URL—Salesforce admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
Single Sign-On Initialization URL—Use this URL to perform SSO into Salesforce from a third party using its third-party credentials.
The user opens this URL in a browser and logs in to the third party. The third party either creates a user or updates an existing user.
Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use this URL to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Oauth-Only Initialization URL—Use this URL to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token. This flow doesn’t provide for future SSO functionality.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider must redirect to the callback URL with information for each client configuration URL.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider detail page. It redirects you to the authentication provider and asks you to sign in. You’re then asked to authorize your app. After you authorize, you’re redirected to Salesforce.
SEE ALSO:
Use Request Parameters with Client Configuration URLs
External Authentication Providers
Configure an OpenID Connect Authentication Provider
You can use any third-party web app that implements the server side of the OpenID Connect protocol, such as Amazon, Google, and PayPal, as an authentication provider.
Complete these steps to configure an OpenID authentication provider.
1.
Register your app, making Salesforce the app domain.
2.
Define an OpenID Connect authentication provider in your Salesforce org.
3.
your app to use the callback URL generated by Salesforce.
4.
the connection.
Register an OpenID Connect App
Before you can configure a web app for your Salesforce org, you must register it with your service provider. The process varies depending on the service provider. For example, to register a Google app, Create an OAuth 2.0 Client ID .
1. Register your app on your service provider’s website.
2. Modify the app settings and set the app domain (or Home Page URL) to Salesforce.
3. From the provider’s documentation, get the client ID, client secret, authorize endpoint URL, token endpoint URL, and the user info endpoint URL. Here are some common OpenID Connect service providers.
•
Amazon
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
704
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
•
PayPal
Define an OpenID Connect Provider in Your Salesforce Org
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select OpenID Connect.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is
MyOpenIDConnectProvider, your single sign-on URL is similar to: https://login.salesforce.com/auth/sso/00Dx00000000001/MyOpenIDConnectProvider
.
6. Use the client ID from your provider for the
Consumer Key
field.
7. Use the client secret from your provider for the
Consumer Secret
field.
8. Enter the base URL from your provider for the
Authorize Endpoint URL
.
Tip:
You can add query string parameters to the base URL, if necessary. For example, to get a refresh token from Google for offline access, use https://accounts.google.com/o/oauth2/auth?access_type=offline&approval_prompt=force
.
You need the approval_prompt
parameter to ask the user to accept the refresh action so that Google continues to provide refresh tokens after the first one.
9. Enter the token endpoint URL from your provider.
10. Optionally, set the following fields.
a.
User Info Endpoint URL
from your provider.
b.
Token Issuer
. This value identifies the source of the authentication token in the form https: URL
. If this value is specified, the provider must include an id_token
value in the response to a token request. The id_token
value isn’t required for a refresh token flow (but will be validated by Salesforce if provided).
c.
Default Scopes
to send along with the request to the authorization endpoint. Otherwise, the hardcoded defaults for the provider type are used. See the OpenID Connect developer documentation for these defaults.
For more information, see Use the Scope Parameter
.
11. Optionally, select Send access token in header to have the token sent in a header instead of a query string.
12. Optionally, set the following fields.
a.
Custom Error URL
for the provider to use to report any errors.
b.
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
c. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note:
A
Registration Handler
class is required for Salesforce to generate the single sign-on initialization URL.
705
Set Up and Maintain Your Salesforce Organization Single Sign-On
d. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
e. To use a portal with your provider, select the portal from the Portal dropdown list.
f. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
13. Click Save.
Be sure to note the generated Auth. Provider Id value. You must use it with the
Auth.AuthToken
Apex class.
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Salesforce admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
Single Sign-On Initialization URL—Use this URL to perform SSO into Salesforce from a third party using its third-party credentials.
The user opens this URL in a browser and logs in to the third party. The third party either creates a user or updates an existing user.
Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use this URL to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Oauth-Only Initialization URL—Use this URL to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token. This flow doesn’t provide for future SSO functionality.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider must redirect to the callback URL with information for each client configuration URL.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Update Your OpenID Connect App
After defining the authentication provider in your Salesforce org, go back to your provider and update your app’s callback URL. For
Google apps, the callback URL is called the Authorized Redirect URI. For PayPal, it’s called the Return URL.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to your provider’s service and asks you to sign in. You’re then asked to authorize your app. After you authorize, you’re redirected back to Salesforce.
706
Set Up and Maintain Your Salesforce Organization Single Sign-On
Configure a Microsoft
®
Access Control Service Authentication Provider
You can use Microsoft Access Control Service as an authentication provider using the OAuth protocol.
Authorization is typically done by a Microsoft Office 365 service like SharePoint
®
Online.
Salesforce supports authentication from a Microsoft Access Control Service using only OAuth. Single sign-on (SSO) authentication from a Microsoft authentication provider is not supported.
Complete these steps to configure a Microsoft Access Control Service authentication provider.
1.
Define a Microsoft Access Control Service authentication provider in your Salesforce org.
2.
Register your app with Microsoft, making Salesforce the application domain.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
3.
Edit your Microsoft Access Control Service authentication provider details in Salesforce to use
the consumer key and consumer secret generated when you registered your app with Microsoft.
4.
the connection.
USER PERMISSIONS
Define a Microsoft Access Control Service Authentication Provider in Your
Salesforce Org
Before you can register an app in SharePoint Online or the Microsoft Seller Dashboard, you need the callback URL that redirects the authorized user to Salesforce.
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth.
Providers.
2. Click New.
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
3. For provider type, select Microsoft Access Control Service.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is
MyMicrosoftACSProvider, your callback URL is similar to: https://login.salesforce.com/services/authcallback/00Dx00000000001/MyMicrosoftACSProvider
6. Enter a placeholder value for the consumer key field. You edit this value after your app is registered with Microsoft.
7. Enter a placeholder value for the consumer secret field You edit this value after your app is registered with Microsoft.
8. Enter the base URL from your provider for the Authorize Endpoint URL. For example, SharePoint Online uses the following form.
https://<sharepoint online host name>/_layouts/15/OAuthAuthorize.aspx
9. Enter the Token Endpoint URL in the following form.
https://accounts.accesscontrol.windows.net/<tenant>/tokens/OAuth/2?resource=<sender ID>/<sharepoint online host name>@<tenant>
•
<tenant> is the Office 365 tenant name ending with
.onmicrosoft.com
or the corresponding tenant globally unique identifier (GUID).
•
<sender ID> is the identifier for the sender of the token. For example, SharePoint uses
00000003-0000-0ff1-ce00-000000000000
10. Optionally, set the following fields.
•
Default Scopes
to send along with the request to the authorization endpoint. See http://msdn.microsoft.com/en-us/library/jj687470.aspx#Scope for more information about scopes for SharePoint Online. Or
Use the Scope Parameter for more information about using scopes with Salesforce.
•
Custom Error URL
for the provider to use to report any errors.
707
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
•
To use a portal with your provider, select the portal from the Portal dropdown list. If you have a portal set up for your org, this option can redirect the login request to the portal login page. Otherwise, leave as None.
•
Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
11. Click Save.
Note the generated Auth. Provider Id value. You can use it with the
Auth.AuthToken
Apex class .
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this
URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
Oauth-Only Initialization URL—Use this URL to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token. This flow doesn’t provide for future SSO functionality.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider has to redirect to the callback URL with information for each client configuration URL.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Register Your App with Microsoft
Before you can configure an app for your Salesforce org, you must get an app identity using one of the options provided by Microsoft.
See Guidelines for registering apps for SharePoint 2013 for details about registering a remote app for SharePoint.
1. Register your app using one of the options provided by Microsoft.
2. Modify the app settings and set the redirect URI to the authentication provider’s callback URL.
3. Note the client ID and client secret.
4. Click Save.
Edit Your Microsoft Access Control Service Authentication Provider Details
After registering your app with Microsoft, go back to your Microsoft Access Control Service authentication provider details, and update the consumer key and consumer secret with the values provided by Microsoft.
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click Edit next to the name of your Microsoft Access Control Service authentication provider.
3. In the
Consumer Key
field, enter the Microsoft client ID.
4. In the
Consumer Secret
field, enter the Microsoft client secret.
Test the Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to Microsoft and asks you to sign in. You’re then asked to authorize your app. After you authorize, you’re redirected to Salesforce.
708
Set Up and Maintain Your Salesforce Organization Single Sign-On
Configure a LinkedIn Authentication Provider
Configure LinkedIn as an authentication provider to let users log in to your Salesforce org using their LinkedIn credentials.
Complete these steps to configure LinkedIn as an authentication provider.
1.
Decide which scopes (user details) to get from LinkedIn
.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
2.
3.
Define a LinkedIn provider in your Salesforce org
and establish a registration handler.
4.
.
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
5.
Update your LinkedIn app to use the callback URL generated by Salesforce as an entry in the
OAuth 2.0 Redirect URLs
.
USER PERMISSIONS
6.
Test the single sign-on (SSO) connection .
Decide Which Scopes (User Details) to Get from LinkedIn
Scopes determine the information you get from LinkedIn about a user during the authorization process. You can request basic information, such as username and a photo URL, or you can get more specific information, such as an address, phone number, and contact list. The user approves the exchange of information before it’s given.
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
When you set up LinkedIn as an authentication provider, you can set the scopes in three different places: in the LinkedIn app settings, in the Salesforce Auth. Provider settings, or in a query to
LinkedIn’s user info endpoint using field selectors. Consider the following as you decide where to specify the scopes and the values to use.
•
You can leave scope value blank in the LinkedIn and Salesforce settings. The default value is r_basicprofile, which provides only the most basic user information as defined by LinkedIn.
•
Salesforce requires the email address for users.
•
Refer to the LinkedIn Authentication documentation for a list of supported values and their meaning, or the LinkedIn Field Selectors page for information about requesting scopes using a URL.
•
If you set the default scopes in the Salesforce authentication provider settings, that value overrides the value in the LinkedIn app settings.
•
Separate multiple scope values in the LinkedIn app settings or the Salesforce authentication provider settings with a space, for example,
r_basicprofile r_emailaddress
.
•
If you use LinkedIn Field Selectors with a URL, separate multiple values with a comma, for example, https://api.linkedin.com/v1/people/~:(id,formatted-name,first-name,last-name,public-profile-url,email-address)
.
Set Up a LinkedIn App
Before you can configure LinkedIn for your Salesforce org, set up an app in LinkedIn.
Note:
You can skip this step by allowing Salesforce to use its own default app. For more information, see Use Salesforce-Managed
Values in the Auth. Provider Setup Page .
1. Sign in to your developer account for the LinkedIn website .
2. Click the username at the top and select API Keys.
3. Click Add New Application.
4. Enter the app settings.
709
Set Up and Maintain Your Salesforce Organization Single Sign-On
5. Note the API key and secret key. You need them later to create a LinkedIn provider in your Salesforce org.
6. Optionally, enter a LinkedIn supported scope value or several space-separated values.
.
Define a LinkedIn Provider in Your Salesforce Org
You need the LinkedIn API key and secret key to set up a LinkedIn provider in your Salesforce org.
Note: You can skip this step by allowing Salesforce to manage the values for you. For more information, see Use Salesforce-Managed
Values in the Auth. Provider Setup Page .
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select LinkedIn.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is MyLinkedInProvider, your SSO URL is similar to: https://login.salesforce.com/services/sso/00Dx00000000001/MyLinkedInProvider
6. Use the LinkedIN API key for the
Consumer Key
field.
7. Use the LinkedIn secret key for the
Consumer Secret
field.
8. Optionally, set the following fields.
a.
Authorize Endpoint URL
to enter the base authorization URL from LinkedIn. For example, https://www.linkedin.com/uas/oauth2/authorization/auth
. The URL must start with
https://www.linkedin.com/uas/oauth2/authorization
.
Tip: You can add query string parameters to the base URL, if necessary. For example, to get a refresh token from LinkedIn for offline access, use https://accounts.linkedin.com/o/oauth2/auth?access_type=offline&approval_prompt=force
.
You need the approval_prompt
parameter to ask the user to accept the refresh action so that LinkedIn continues to provide refresh tokens after the first one.
b.
Token Endpoint URL
to enter the OAuth token URL from LinkedIn. For example, https://www.linked.com/uas/oauth2/accessToken/token
. The URL must start with
https://www.linkedin.com/uas/oauth2/accessToken
.
c.
User Info Endpoint URL
to change the values requested from LinkedIn’s profile API. For more information, see https://developer.linkedin.com/documents/profile-fields . The URL must start with
https://api.linkedin.com/v1/people/~
, and the requested fields must correspond to requested scopes.
d.
Default Scopes
to enter a supported value or several space-separated values that represent the information you get from
LinkedIn. For more information, see Decide Which Scopes (User Details) to Get from LinkedIn
.
e.
Custom Error URL
for the provider to use to report any errors.
f.
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
710
Set Up and Maintain Your Salesforce Organization Single Sign-On
g. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note:
A
Registration Handler
class is required for Salesforce to generate the single sign-on initialization URL.
h. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
i. To use a portal for LinkedIn users, select the portal from the Portal dropdown list.
9. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
10. Click Save.
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this
URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
Single Sign-On Initialization URL—Use this URL to perform SSO into Salesforce from a third party (using third-party credentials). The user opens this URL in a browser and signs in to the third party. The third party either creates a user or updates an existing user. Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use this URL to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Oauth-Only Initialization URL—Use this URL to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token. This flow does not provide for future SSO functionality.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider has to redirect to the callback URL with information for each client configuration URL.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Edit the Registration Handler
1. From Setup, enter
Apex Classes
in the
Quick Find
box, then select Apex Classes.
2. Edit the auto-created Apex registration handler (or the existing registration handler if you had one) to map fields between LinkedIn and Salesforce
Note: The default profile query for LinkedIn only retrieves the following fields: first-name, last-name, headline, profile URL.
The default registration handler requires email. Either remove the email requirement from the registration handler or change
fields you want in the registration handler.
Here’s an example Apex registration handler specifically for a LinkedIn app as the authentication provider. This registration handler assumes that the requested scopes include r_basicprofile and r_emailaddress. It also assumes that the users are logging in to a customer portal.
//TODO:This auto-generated class includes the basics for a Registration
//Handler class. You will need to customize it to ensure it meets your needs and
711
Set Up and Maintain Your Salesforce Organization Single Sign-On
//the data provided by the third party.
global class LinkedInRegHandler implements Auth.RegistrationHandler {
//Creates a Standard salesforce or a community user global User createUser(Id portalId, Auth.UserData data) { if (data.attributeMap.containsKey('sfdc_networkid')) {
//We have a community id, so create a user with community access
//TODO: Get an actual account
Account a =[SELECT Id FROM account WHERE name = 'LinkedIn Account'];
Contact c = new Contact(); c.accountId = a.Id; c.email = data.email; c.firstName = data.firstName; c.lastName = data.lastName; insert(c);
//TODO: Customize the username and profile. Also check that the username
//doesn't already exist and possibly ensure there are enough org licenses
//to create a user. Must be 80 characters or less.
User u = new User();
Profile p =[SELECT Id FROM profile WHERE name = 'Customer Portal Manager']; u.username = data.firstName + '@sfdc.linkedin.com'; u.email = data.email; u.lastName = data.lastName; u.firstName = data.firstName;
String alias = data.firstName;
//Alias must be 8 characters or less if (alias.length() > 8) { alias = alias.substring(0, 8);
} u.alias = alias; u.languagelocalekey = UserInfo.getLocale(); u.localesidkey = UserInfo.getLocale(); u.emailEncodingKey = 'UTF-8'; u.timeZoneSidKey = 'America/Los_Angeles'; u.profileId = p.Id; u.contactId = c.Id; return u;
} else {
//This is not a community, so create a regular standard user
User u = new User();
Profile p =[SELECT Id FROM profile WHERE name = 'Standard User'];
//TODO: Customize the username. Also check that the username doesn't
//already exist and possibly ensure there are enough org licenses
//to create a user. Must be 80 characters or less u.username = data.firstName + '@salesforce.com'; u.email = data.email; u.lastName = data.lastName; u.firstName = data.firstName;
String alias = data.firstName;
//Alias must be 8 characters or less if (alias.length() > 8) { alias = alias.substring(0, 8);
} u.alias = alias;
712
Set Up and Maintain Your Salesforce Organization Single Sign-On u.languagelocalekey = UserInfo.getLocale(); u.localesidkey = UserInfo.getLocale(); u.emailEncodingKey = 'UTF-8'; u.timeZoneSidKey = 'America/Los_Angeles'; u.profileId = p.Id; return u;
}
}
//Updates the user's first and last name global void updateUser(Id userId, Id portalId, Auth.UserData data) {
User u = new User(id = userId); u.lastName = data.lastName; u.firstName = data.firstName; update(u);
}
}
See the RegistrationHandler Interface documentation for more information and examples.
Update Your LinkedIn App
After you define the LinkedIn authentication provider in your Salesforce org, go back to LinkedIn. Update your app to use the
Salesforce-generated callback URL as the LinkedIn
OAuth 2.0 Redirect URLs
value.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to LinkedIn and asks you to sign in.
You’re then asked to authorize your app. After you authorize, you’re redirected to Salesforce.
Configure a Twitter Authentication Provider
Configure Twitter as an authentication provider to let users log in to a Salesforce org from their
Twitter account.
Complete these steps to configure Twitter as an authentication provider.
1.
2.
Define a Twitter provider in your Salesforce org
, and establish a registration handler.
3.
.
4.
Update your Twitter app to use the callback URL generated by Salesforce as an entry in the
Twitter app settings.
5.
Test the single sign-on (SSO) connection .
Set Up a Twitter App
Before you can configure Twitter for your Salesforce org, set up an app in Twitter.
Note: You can skip this step by allowing Salesforce to use its own default app. For more information, see Use Salesforce-Managed Values in the Auth. Provider Setup Page .
1. Sign in to your developer account for the Twitter website .
2. Click the user icon at the top and select My Applications (or go to apps.twitter.com
).
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
713
Set Up and Maintain Your Salesforce Organization Single Sign-On
3. Click Create New App.
4. Enter the app settings.
5. In the API Keys, note the API key and API secret. You need them later to create a Twitter provider in your Salesforce org.
Define a Twitter Provider in Your Salesforce Org
You need the Twitter API key and API secret from your Twitter app to set up a Twitter provider in your Salesforce org.
Note:
You can skip this step by allowing Salesforce to manage the values for you. For more information, see Use Salesforce-Managed
Values in the Auth. Provider Setup Page .
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For provider type, select Twitter.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URLs. For example, if the URL suffix of your provider is MyTwitterProvider, your SSO URL is similar to: https://login.salesforce.com/services/sso/00Dx00000000001/MyTwitterProvider
6. Use the API key from Twitter for the
Consumer Key
field.
7. Use the API secret from Twitter for the
Consumer Secret
field.
8. Optionally, set the following fields.
a.
Custom Error URL
for the provider to use to report any errors.
b.
Custom Logout URL
to provide a specific destination for users after they log out, if they authenticated using the SSO flow.
Use this field to direct users to a branded logout page or destination other than the default Salesforce logout page. The URL must be fully qualified with an http
or https
prefix, such as https://acme.my.salesforce.com
.
c. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note: A
Registration Handler
class is required for Salesforce to generate the SSO initialization URL.
d. For
Execute Registration As
, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template.
e. To use a portal for Twitter users, select the portal from the Portal dropdown list.
f. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
9. Click Save.
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Admins use this URL to ensure that the third-party provider is set up correctly. The admin opens this
URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
714
Set Up and Maintain Your Salesforce Organization Single Sign-On
•
Single Sign-On Initialization URL—Use this URL to perform SSO into Salesforce from a third party (using third-party credentials). The user opens this URL in a browser and signs in to the third party. The third party either creates a user or updates an existing user. Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use this URL to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Callback URL—Use the callback URL for the endpoint that the authentication provider calls back to for configuration. The authentication provider has to redirect to the Callback URL with information for each client configuration URL.
Client configuration URLs support additional request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from the third party, or go to a specific location after authenticating.
Edit the Registration Handler
1. From Setup, enter
Apex Classes
in the
Quick Find
box, then select Apex Classes.
2. Edit the auto-created Apex registration handler (or the existing registration handler if you had one) to map fields between Twitter and Salesforce.
Here’s an example Apex registration handler that specifies the Twitter app as the authentication provider.
global class MyTwitterRegHandler implements Auth.RegistrationHandler{ global User createUser(Id portalId, Auth.UserData data)
{ if(data.attributeMap.containsKey('sfdc_networkid'))
{
// Create communities user
Account a = [SELECT Id FROM account WHERE name='Twitter Account']; // Make sure this account exists
Contact c = new Contact(); c.accountId = a.Id; c.email = '[email protected]'; c.firstName = data.fullname.split(' ')[0]; c.lastName
= data.fullname.split(' ')[1]; insert(c);
User u = new User();
Profile p = [SELECT Id FROM profile WHERE name='Customer Portal Manager']; u.username = data.username + '@sfdc-portal-twitter.com'; u.email = '[email protected]'; u.firstName = data.fullname.split(' ')[0]; u.lastName = data.fullname.split(' ')[1];
String alias = data.fullname;
//Alias must be 8 characters or less if(alias.length() > 8) { alias = alias.substring(0, 8);
} u.alias = alias; u.languagelocalekey = 'en_US'; u.localesidkey = 'en_US'; u.emailEncodingKey = 'UTF-8'; u.timeZoneSidKey = 'America/Los_Angeles';
715
Set Up and Maintain Your Salesforce Organization Single Sign-On u.profileId = p.Id; u.contactId = c.Id; return u;
} else {
// Create Standard SFDC user
User u = new User();
Profile p = [SELECT Id FROM profile WHERE name='Standard User']; u.username = data.username + '@sfdc-twitter.com'; u.email = '[email protected]'; u.firstName = data.fullname.split(' ')[0]; u.lastName = data.fullname.split(' ')[1];
String alias = data.fullname; if(alias.length() > 8) alias = alias.substring(0, 8); u.alias = alias; u.languagelocalekey = 'en_US'; u.localesidkey = 'en_US'; u.emailEncodingKey = 'UTF-8'; u.timeZoneSidKey = 'America/Los_Angeles'; u.profileId = p.Id; return u;
}
} global void updateUser(Id userId, Id portalId, Auth.UserData data)
{
User u = new User(id=userId); u.firstName = data.fullname.split(' ')[0]; u.lastName = data.fullname.split(' ')[1];
String alias = data.fullname; if(alias.length() > 8) alias = alias.substring(0, 8); u.alias = alias; update(u);
}
}
See the RegistrationHandler Interface documentation for more information and examples.
Update Your Twitter App
After you define the Twitter authentication provider in your Salesforce org, go back to Twitter and update your app to use the
Salesforce-generated callback URL as the callback URL value in your Twitter app settings.
Note: In your Twitter app, make sure that you select Allow this app to be used to Sign In with Twitter.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider detail page. It redirects you to Twitter and asks you to sign in.
You’re then asked to authorize your app. After you authorize, you’re redirected to Salesforce.
716
Set Up and Maintain Your Salesforce Organization Single Sign-On
Use Salesforce-Managed Values in the Auth. Provider Setup Page
You can choose to let Salesforce create key values when setting up a Facebook, Salesforce, LinkedIn,
Twitter, or Google authentication provider. Having Salesforce generate the key values saves you the time and effort of creating your own third-party app.
To use Salesforce-managed values, leave the following fields blank if they show up in your Auth.
Provider Setup page.
•
Consumer Key
•
Consumer Secret
•
Authorize Endpoint URL
•
Token Endpoint URL
•
User Info Endpoint URL
•
Default Scopes
Note: Specifying a value for any of the above fields implies that you’re using your own connected app. In this case, you must specify values for the consumer key and consumer secret.
Example: Suppose that you want to set up single sign-on (SSO) using a LinkedIn authentication provider to enable login to Salesforce with LinkedIn credentials. You can skip creating a LinkedIn app if you use Salesforce-created values in the Auth. Provider Setup page.
Next, you define the LinkedIn authentication provider in your org and test the connection using the procedure in Configure a LinkedIn Authentication Provider .
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
Create a Custom External Authentication Provider
Create a custom single sign-on (SSO) authentication provider to let users log in to your Salesforce org using their non-Salesforce credentials. Implement a custom external authentication provider if your OAuth app doesn’t support OpenID Connect. If your app supports OpenID Connect, you can use one of the authentication providers that Salesforce provides.
1.
Set up an account with your chosen authentication provider.
2.
your custom metadata types, and select the custom fields that you want your admins to populate during setup.
EDITIONS
Available in: Available in
Enterprise, Performance,
Unlimited, and Developer
Editions
3.
authentication provider by extending the abstract class
Auth.AuthProviderPluginClass
.
4.
Configure your new metadata on the Auth. Provider Setup page.
5.
your app to use the Callback URL generated by Salesforce.
6.
the connection.
Set Up Your Account
Before you can configure the external authentication provider plug-in for your Salesforce org, set up an account with your chosen external authentication provider.
1. Go to your authentication provider’s site and create an app.
2. Modify the app settings and set the Application Domain to Salesforce.
3. Note the app ID and app secret, if required by your external authentication provider.
717
Set Up and Maintain Your Salesforce Organization Single Sign-On
Create Your Custom Metadata Types
When you have an account, create the custom metadata types for your Salesforce org required by your external authentication provider.
1. From Setup, enter
metadata
in the
Quick Find
box, then select Custom Metadata Types.
2. Click New Custom Metadata Type.
3. Enter a label name and plural label name for your custom metadata, and click Save.
4. Under the Custom Fields section, click New and select the custom fields you that your authentication provider requires. For example, if the authentication provider requires an app ID or app secret, create fields with labels like “Consumer Key” or “Consumer Secret.”
Note: You’re prompted to enter details for each field type, such as label, description, and Help text. You can choose to make these fields required.
Build Your Apex Classes and Methods
To create a custom authentication provider for SSO, create a class that extends the
Auth.AuthProviderPluginClass
abstract class. This class allows you to store the custom configuration for your authentication provider and handle its authentication protocols.
It also creates the name for your external authentication provider and displays this name in the list of available authentication providers.
1. From Setup, enter
apex classes
in the search field, and select Apex Classes.
2. Click New.
3. In the field provided, create an Apex class and method.
a. Extend the
Auth.AuthProviderPluginClass
class.
b. For the return
string on the getCustomMetadataType
method, enter the API name listed on your newly created custom metadata.
Note: For information about the classes and methods that this plug-in requires, see the Auth Namespace section of the Force.com
Apex Code Developer’s Guide .
Configure Your Authentication Provider
You need your authentication provider’s app ID and app secret to set up your custom provider in your Salesforce org.
1. From Setup, enter
Auth. Providers
in the
Quick Find
box, then select Auth. Providers.
2. Click New.
3. For the provider type, select your custom authentication provider.
4. Enter a name for the provider.
5. Enter the URL suffix, which is used in the client configuration URL. For example, if your provider’s URL is MyAwesomeProvider, your
SSO URL is similar to https://login.salesforce.com/auth/sso/00Dx00000000001/MyAwesomeProvider
.
6. Enter your information in the custom fields you created.
7. Select an existing Apex class as the
Registration Handler
class. Or click Automatically create a registration handler
template to create an Apex class template for the registration handler. Edit this class later, and modify the default content before using it.
Note: A
Registration Handler
class is required for Salesforce to generate the SSO initialization URL.
718
Set Up and Maintain Your Salesforce Organization Single Sign-On
8. For Execute Registration As, select the user that runs the Apex handler class. The user must have the “Manage Users” permission. A user is required regardless of whether you’re specifying an existing registration handler class or creating one from the template. This field is required for all custom authentication providers.
9. Use the
Icon URL
field to add a path to an icon to display as a button on the login page for a community. This icon applies to a community only. It doesn’t appear on the login page for your Salesforce org or domain created with My Domain. Users click the button to log in with the associated authentication provider for the community.
Specify a path to your own image, or copy the URL for one of our sample icons into the field.
10. Click Save.
Note the generated authentication provider ID. You use it with the
Auth.AuthToken
Apex class.
Several client configuration URLs are generated after defining the authentication provider.
•
Test-Only Initialization URL—Use to ensure that the third-party provider is set up correctly. The admin opens this URL in a browser, signs in to the third party, and is redirected back to Salesforce with a map of attributes.
•
Single Sign-On Initialization URL—Use to initialize SSO into Salesforce from a third party (using third-party credentials). The user opens this URL in a browser and signs in to the third party. The third party either creates a user or updates an existing user. Then the third party signs the user into Salesforce as that user.
•
Existing User Linking URL—Use to link existing Salesforce users to a third-party account. The user opens this URL in a browser, signs in to the third party, signs in to Salesforce, and approves the link.
•
Oauth-Only Initialization URL—Use to obtain OAuth access tokens for a third party. Users must authenticate with Salesforce for the third-party service to get a token. This flow doesn’t provide for future SSO functionality.
•
Callback URL—Use as the endpoint that the authentication provider calls back to for configuration. The authentication provider redirects to the callback URL with information for each client configuration URL.
Client configuration URLs support other request parameters that enable you to direct users to log in to specific sites, obtain customized permissions from a third party, or go to a location after authenticating.
Update Your External Authentication Provider
After defining your authentication provider in your Salesforce org, go back to your external authentication provider’s site and update your app to use the callback URL as your custom authentication provider’s website URL.
Test the SSO Connection
In a browser, open the Test-Only Initialization URL on the Auth. Provider Setup page. It redirects you to your provider’s site and asks you to sign in. You’re then asked to authorize your app. After you authorize, you’re redirected back to Salesforce.
Using Frontdoor.jsp to Log Into Salesforce
You can use frontdoor.jsp to give users access to Salesforce from a custom Web interface, such as a remote access Force.com site, using their existing session ID and the server URL.
To authenticate users with frontdoor.jsp, you must parse the session ID (not just the 15-character or 18-character ID) and the instance or domain from the serverUrl of the LoginResult returned from the SOAP API login() call. We recommend passing these values to frontdoor.jsp through a form that uses a
POST
request.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
719
Set Up and Maintain Your Salesforce Organization Single Sign-On
For example, the following form posts the current session ID to frontdoor.jsp.
<form method="POST" action="https://
domain name
/secur/frontdoor.jsp">
<input type="hidden" name="sid" value="
full_sessionID_value
"
/>
<input type="submit" name="login" value="Log In" /></form>
In this example,
domain_name
is the domain of the serverURL (that is,
yourInstance
.salesforce.com or
myDomain
.my.salesforce.com, depending on whether My Domain is enabled).
You can also send the values as URL parameters, but this approach is not as secure as a
POST
request because it exposes the session
ID in the URL.
https://
domain_name/secur/frontdoor.jsp?sid=full_sessionID_value
&retURL=
optional_relative_url_to_open
Full Session ID
You can obtain the full session ID from:
•
The access_token
from an OAuth authentication
Tip: One of the scopes specified when you create a connected app must be web or full.
•
The Apex
UserInfo.getSessionId()
The session ID returned using the Visualforce
{!GETSESSIONID()}
can’t be used on frontdoor.jsp.
Note:
Not all session types are supported with frontdoor.jsp, such as community API sessions. For these sessions, consider using
SAML for single sign-on, instead.
Relative URL to Open
You can optionally include a URL-encoded relative path to redirect users to the Salesforce user interface or a particular record, object, report, or Visualforce page (for example,
/apex/MyVisualforcePage
).
720
Set Up and Maintain Your Salesforce Organization Single Sign-On
Use Request Parameters with Client Configuration URLs
Add functionality to your authentication provider with request parameters. For example, you can use these parameters to direct users to log in to specific sites, get customized permissions from the third party, or go to a specific location after authenticating.
Add the request parameters to client configuration URLs. These parameters are generated after you defined your authentication provider.
•
Test-Only Initialization URL
•
Single Sign-On Initialization URL
•
Existing User Linking URL
•
Callback URL
Append any of these parameters to your URL as needed. For Janrain providers, append them to the appropriate callback URL.
•
Scope —Customizes the permissions requested from the third party.
•
—Enables the provider to be used with a site.
•
StartURL —Sends the user to a specified location after authentication.
•
—Sends the user to a specific community after authentication.
•
Authorization Endpoint on page 725—Sends the user to a specific endpoint for authentication
(Salesforce authentication providers, only).
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
IN THIS SECTION:
Customize the permissions requested from a third party, like Facebook or Janrain, so that the returned access token has additional permissions.
Use your authentication provider to log into a site or link to a sites user.
Send your user to a specific location after authenticating or linking.
Using the Community URL Parameter
Send your user to a specific Community after authenticating.
Using the Authorization Endpoint Parameter
Send your user to a specific authorization endpoint.
721
Set Up and Maintain Your Salesforce Organization Single Sign-On
Use the Scope Parameter
Customize the permissions requested from a third party, like Facebook or Janrain, so that the returned access token has additional permissions.
You can customize requests to a third party to receive access tokens with additional permissions.
Then you use
Auth.AuthToken
methods to retrieve the access token that was granted so you can use those permissions with the third party.
The default scopes vary depending on the third party, but usually do not allow access to much more than basic user information. Every provider type (Open ID Connect, Facebook, Salesforce, and others), has a set of default scopes it sends along with the request to the authorization endpoint.
For example, Salesforce’s default scope is id
.
You can send scopes in a space-delimited string. The space-delimited string of requested scopes is sent as-is to the third party, and overrides the default permissions requested by authentication providers.
Janrain does not use this parameter; additional permissions must be configured within Janrain.
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
Example: The following is an example of a scope
parameter requesting the Salesforce scopes api
and web
, added to the
Single Sign-On Initialization URL
, where:
•
orgID
is your Auth. Provider ID
•
URLsuffix
is the value you specified when you defined the authentication provider
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers https://login.salesforce.com/services/auth/sso/orgID/URLsuffix?scope=id%20api%20web
Valid scopes vary depending on the third party; refer to your individual third-party documentation. For example, Salesforce scopes are:
Value
api chatter_api custom_permissions full id openid refresh_token visualforce
Description
Allows access to the current, logged-in user’s account using APIs, such as REST API and Bulk API. This value also includes chatter_api
, which allows access to Chatter REST API resources.
Allows access to Chatter REST API resources only.
Allows access to the custom permissions in an organization associated with the connected app, and shows whether the current user has each permission enabled.
Allows access to all data accessible by the logged-in user, and encompasses all other scopes. full does not return a refresh token. You must explicitly request the refresh_token
scope to get a refresh token.
Allows access to the identity URL service. You can request profile
, address
, or phone
, individually to get the same result as using id
; they are all synonymous.
Allows access to the current, logged in user’s unique identifier for OpenID Connect apps.
The openid
scope can be used in the OAuth 2.0 user-agent flow and the OAuth 2.0 Web server authentication flow to get back a signed ID token conforming to the OpenID Connect specifications in addition to the access token.
Allows a refresh token to be returned if you are eligible to receive one. This lets the app interact with the user’s data while the user is offline, and is synonymous with requesting offline_access
.
Allows access to Visualforce pages.
722
Set Up and Maintain Your Salesforce Organization Single Sign-On
Value
web
Description
Allows the ability to use the access_token
on the Web. This also includes visualforce
, allowing access to Visualforce pages.
SEE ALSO:
Use Request Parameters with Client Configuration URLs
Using the Site Parameter
Use your authentication provider to log into a site or link to a sites user.
To use your provider with a site, you need to do the following:
•
Enable the provider to be used with a site
•
Ensure the site is configured to use the same portal
•
Add the site-specific login URL information to the appropriate client configuration URL, such as the
Single Sign-On Initialization URL
, using the site
parameter
Example: You create the site login Visualforce page, or specify the default page, when you create the site. An example site login URL is: https%3A%2F%2Fmysite.force.com%2FSiteLogin
.
The following is an example of a site-login URL added to the
Single Sign-On
Initialization URL
, using the site
parameter, where:
•
orgID
is your Auth. Provider ID
•
URLsuffix
is the value you specified when you defined the authentication provider https://login.salesforce.com/services/auth/sso/orgID/URLsuffix?site=https%3A%2F%2Fmysite.force.com%2FSiteLogin
If you don’t specify a site
parameter, the user proceeds either to a standard portal (if set up for a portal) or the standard application (if not).
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
SEE ALSO:
Use Request Parameters with Client Configuration URLs
723
Set Up and Maintain Your Salesforce Organization Single Sign-On
Using the StartURL Parameter
Send your user to a specific location after authenticating or linking.
To direct your users to a specific location after authenticating, you need to specify a URL with the startURL
request parameter. This URL must be a relative URL; passing an absolute URL results in an error. If you don’t add startURL
, the user is sent to either
/home/home.jsp
(for a portal or standard application) or to the default sites page (for a site) after authentication completes.
Example:
For example, with a
Single Sign-On Initialization URL
, the user is sent to this location after being logged in. For an
Existing User Linking URL
, the “Continue to Salesforce” link on the confirmation page leads to this page.
The following is an example of a startURL
parameter added to the
Single Sign-On
Initialization URL
, where:
•
orgID
is your Auth. Provider ID
•
URLsuffix
is the value you specified when you defined the authentication provider https://login.salesforce.com/services/auth/sso/orgID/URLsuffix?startURL=%2F005x00000000001%3Fnoredirect%3D1
SEE ALSO:
Use Request Parameters with Client Configuration URLs
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
Using the Community URL Parameter
Send your user to a specific Community after authenticating.
To direct your users to a specific community after authenticating, you need to specify a URL with the community
request parameter. If you don’t add the parameter, the user is sent to either
/home/home.jsp
(for a portal or standard application) or to the default sites page (for a site) after authentication completes.
Example:
For example, with a
Single Sign-On Initialization URL
, the user is sent to this location after being logged in. For an
Existing User Linking URL
, the “Continue to Salesforce” link on the confirmation page leads to this page.
The following is an example of a community
parameter added to the
Single Sign-On
Initialization URL
, where:
•
orgID
is your Auth. Provider ID
•
URLsuffix
is the value you specified when you defined the authentication provider https://login.salesforce.com/services/auth/sso/orgID/URLsuffix?community=https://acme.force.com/support
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
724
Set Up and Maintain Your Salesforce Organization Single Sign-On
Using the Authorization Endpoint Parameter
Send your user to a specific authorization endpoint.
You can add a provAuthorizeEndpointHost
parameter to a Salesforce authentication provider URL to direct users to an authorization endpoint for a provided domain, such as a custom domain created using My Domain. Providing an authorization endpoint lets you take advantage of features like session discovery during authorization. This parameter is only available for Salesforce authentication providers, and cannot be used to send users to an authorization page outside of a
Salesforce domain.
To direct your users to a specific Salesforce authorization endpoint, you need to specify a URL with the provAuthorizeEndpointHost
request parameter and a valid https
host. Query strings appended to the host URL are ignored. However, you can specify a community path.
Example: The following is an example of a provAuthorizeEndpointHost
parameter added to the authentication provider URL:
•
orgID
is your Auth. Provider ID
•
URLsuffix
is the value you specified when you defined the authentication provider https://login.salesforce.com/services/auth/sso/
orgID
/
URLsuffix
?provAuthorizeEndpointHost=https%3A%2F%2Fmydomain.my.salesforce.com
The following is an example of a provAuthorizeEndpointHost
directed to a community URL https://login.salesforce.com/services/auth/sso/
orgID
/
URLsuffix
?provAuthorizeEndpointHost=https%3A%2F%2Fmycommunity.force.com%2Fbilling
EDITIONS
Available in: Lightning
Experience and Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
USER PERMISSIONS
To view the settings:
•
View Setup and
Configuration
To edit the settings:
•
Customize Application
AND
Manage Auth. Providers
If an authorization endpoint is not provided, Salesforce uses the default authorization endpoint for the authorization provider. If no default is set for the authorization provider, Salesforce uses the endpoint for login.salesforce.com.
The authorization endpoint does not change the token endpoint, which continues to be the configured or default host. For example,
if the authorization endpoint is a sandbox instance, and your provider is set to use a production token endpoint, the flow fails, because authorization was granted by the sandbox instance, only.
725
Set Up and Maintain Your Salesforce Organization Single Sign-On
Identity Providers and Service Providers
An identity provider is a trusted provider that lets you use single sign-on (SSO) to access other websites. A service provider is a website that hosts apps. You can enable Salesforce as an identity provider and define one or more service providers. Your users can then access other apps directly from Salesforce using SSO. SSO can be a great help to your users—instead of having to remember many passwords, they only have to remember one.
Before you can enable Salesforce as an identity provider, you must set up a subdomain
with My
Domain.
Enabling Salesforce as an identity provider requires a
. If you haven’t generated a Salesforce certificate and key pair, one is created for you when you enable Salesforce as an identity provider.
Optionally, you can pick an existing generated certificate or create one yourself.
Salesforce uses the SAML 2.0 standard for SSO and generates SAML assertions when configured as an identity provider.
Use the
identity provider event log if your users have errors when trying to log in to your service
provider’s apps.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
Using Identity Providers and Service Providers
Salesforce supports the following:
•
Identity-provider-initiated login—when Salesforce logs in to a service provider at the initiation of the end user
•
Service-provider-initiated login—when the service provider requests Salesforce to authenticate a user, at the initiation of the user
Here’s the general flow when Salesforce is an identity provider and logs in to a service provider.
726
Set Up and Maintain Your Salesforce Organization Single Sign-On
1. The user tries to access a service provider already defined in Salesforce.
2. Salesforce sends a
to the service provider.
3. The service provider identifies the user and authenticates the certificate.
4. If the user is identified, the user’s logged in to the service provider.
Here’s the general flow when a service provider initiates the login process and uses Salesforce to identify the user.
727
Set Up and Maintain Your Salesforce Organization Single Sign-On
1. The service provider sends a valid SAML request. The SP-Initiated POST endpoint is generated when the service provider is defined.
2. Salesforce identifies the user specified in the SAML request.
<samlp:AuthnRequest ID="bndkmeemcaamihajeloilkagfdliilbhjjnmlmfo" Version="2.0"
IssueInstant="2010-05-24T22:57:19Z"
ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
ProviderName="google.com" IsPassive="false"
AssertionConsumerServiceURL="https://www.google.com/a/resp.info/acs">
<saml:Issuer>google.com</saml:Issuer>
<samlp:NameIDPolicy AllowCreate="true"
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"/>
</samlp:AuthnRequest>
If a certificate is part of the definition, Salesforce authenticates the certificate.
Note:
If the service provider definition includes a certificate but the SAML request doesn’t contain a certificate, the request fails and the user isn’t logged in to Salesforce. If the definition doesn’t include a certificate and the request includes a signature, the request succeeds if the user is identified correctly.
3. The user is prompted to log in to Salesforce if not logged in yet.
4. Salesforce sends a
to the service provider.
728
Set Up and Maintain Your Salesforce Organization Single Sign-On
5. The service provider authenticates the SAML response sent by Salesforce. If the user is authenticated, the user is logged in to the service provider and logged in to Salesforce.
Important: Salesforce doesn’t provide a mechanism for logging users out of Salesforce when they log out of the service provider.
The following is an example of the SAML response from Salesforce. Share this information with your service provider.
<samlp:Response Destination="https://login-blitz03.soma.salesforce.com/
?saml=MgoTx78aEPa2r1BHKCHmlfUKhH2mkDrXOjmYcjHG_qNDbsRM_6ZAo.wvGk"
ID="_0f551f9288c8b76f21c3d4d15c9cd1df1290476801091"
InResponseTo="_2INwHuINDJTvjo8ohcM.Fpw_uLukYi0WArVx2IJD569kZYL
osBwuiaSbzzxOPQjDtfw52tJB10VfgPW2p5g7Nlv5k1QDzR0EJYGgn0d0z8
CIiUOY31YBdk7gwEkTygiK_lb46IO1fzBFoaRTzwvf1JN4qnkGttw3J6L4b opRI8hSQmCumM_Cvn3DHZVN.KtrzzOAflcMFSCY.bj1wvruSGQCooTRSSQ"
IssueInstant="2010-11-23T01:46:41.091Z" Version="2.0">
<saml:Issuer Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity"
>identityorg.blitz03.blitz.salesforce.com</saml:Issuer>
−
<ds:Signature>
−
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
<ds:SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
−
<ds:Reference URI="#_0f551f9288c8b76f21c3d4d15c9cd1df1290476801091">
−
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
−
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#">
<ec:InclusiveNamespaces PrefixList="ds saml samlp xs"/>
</ds:Transform>
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
<ds:DigestValue>4NVTbQ2WavD+ZBiyQ7ufc8EhtZw=</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
−
<ds:SignatureValue> eqrkFxNlJRCT4VQ7tt7wKZGK7oLCCCa4gV/HNcL03RoKbSXIcwU2CAqW0qTSj25FqhRe2fOwAYa5 xFWat7Fw2bbncU+/nnuVNZut8HEEQoHiQA/Jrh7XB4CNlOpM1QRvgB5Dtdkj/0lI4h3X3TFix57B sgZJGbb5PWEqSH3ZAl+NPvW9nNtYQIFyCTe9+cw2BhCxFgSWfP3/kIYHSM2gbIy27CrRrFS1lAqP hKSLaH+ntH1E09gp78RSyJ2WKFGJU22sE9RJSZwdVw3VGG06Z6RpSjPJtaREELhhIBWTHNoF+VvJ
2Hbexjew6CO08lXRDe8dbrrPIRK/qzHZYf1H0g==
</ds:SignatureValue>
−
<ds:KeyInfo>
−
<ds:X509Data>
−
<ds:X509Certificate>
MIIEbjCCA1agAwIBAgIOASh04QulAAAAAClXs7MwDQYJKoZIhvcNAQEFBQAwfTEVMBMGA1UEAwwM
729
Set Up and Maintain Your Salesforce Organization Single Sign-On
SWRlbnRpdHkgT3JnMRgwFgYDVQQLDA8wMEREMDAwMDAwMEZIOGwxFzAVBgNVBAoMDlNhbGVzZm9y
Y2UuY29tMRYwFAYDVQQHDA1TYW4gRnJhbmNpc2NvMQswCQYDVQQIDAJDQTEMMAoGA1UEBhMDVVNB
MB4XDTEwMDUwNzIyMjcwNVoXDTEyMDUwNjIyMjcwNVowfTEVMBMGA1UEAwwMSWRlbnRpdHkgT3Jn
MRgwFgYDVQQLDA8wMEREMDAwMDAwMEZIOGwxFzAVBgNVBAoMDlNhbGVzZm9yY2UuY29tMRYwFAYD
VQQHDA1TYW4gRnJhbmNpc2NvMQswCQYDVQQIDAJDQTEMMAoGA1UEBhMDVVNBMIIBIjANBgkqhkiG
9w0BAQEFAAOCAQ8AMIIBCgKCAQEAyM4/sjoaizbnWTDjt9mGht2fDGxnLCWGMJ+D+9NWXD5wM15N
SFEcflpI9W4makcCGvoac+CVbPTmOUzOsCQzu7iGkLeMMpngf2XqllnJgl4ejuH8socNrDtltaMk hC08KAmli3Wm/okllqSjVOl8H52jtbvm6HkvLVj2NDLRY6kUejVZMGjGwV5E0FJliwgIip4sCchl dkahbNjbikiiv1MAs8xHbtBt3wnKZWJq3JtS0va1sazUVmEwGDlVW43QPF0S7eV3IJFFhyCPV8yF
N3k0wCkCVBWoknwkMA8CbD+p6qNBVmvh3F3IaW2oym/1eSvtMLNtrPJeZzssqDYqgQIDAQABo4Hr
MIHoMB0GA1UdDgQWBBTYSVEZ9r8Q8T2rbZxPFfPYPZKWITCBtQYDVR0jBIGtMIGqgBTYSVEZ9r8Q
8T2rbZxPFfPYPZKWIaGBgaR/MH0xFTATBgNVBAMMDElkZW50aXR5IE9yZzEYMBYGA1UECwwPMDBE
RDAwMDAwMDBGSDhsMRcwFQYDVQQKDA5TYWxlc2ZvcmNlLmNvbTEWMBQGA1UEBwwNU2FuIEZyYW5j aXNjbzELMAkGA1UECAwCQ0ExDDAKBgNVBAYTA1VTQYIOASh04QupAAAAAClXs7MwDwYDVR0TAQH/
BAUwAwEB/zANBgkqhkiG9w0BAQUFAAOCAQEANaO5Tqcc56E6Jv8itwjtbPvR+WHEMnZgQ9cCPF5Q
VACd5v7I/srx4ZJt/ZO4RZkmX1FXla0M7JGOu63eELHYG1DxT1SpGmpOL7xfBn7QUoh8Rmpp3BZC
WCPIcVQHLs1LushsrpbWu+85tgzlVN4sFVBl8F9rohhbM1dMOUAksoQgM3avcZ2vkugKhX40vIuf
Gw4wXZe4TBCfQay+eDONYhYnmlxVV+dJyHheENOYfVqlau8RMNhRNmhXlGxXNQyU3kpMaTxOux8F
DyOjc5YPoe6PYQ0C/mC77ipnjJAjwm+Gw+heK/9NQ7fIonDObbfu2rOmudtcKG74IDwkZL8HjA==
</ds:X509Certificate>
</ds:X509Data>
</ds:KeyInfo>
</ds:Signature>
−
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
−
<saml:Assertion ID="_e700bf9b25a5aebdb9495fe40332ef081290476801092"
IssueInstant="2010-11-23T01:46:41.092Z" Version="2.0">
<saml:Issuer
Format="urn:oasis:names:tc:SAML:2.0:nameid-format:entity">identityorg.blitz03.blitz.salesforce.com</saml:Issuer>
−
<saml:Subject>
<saml:NameID
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">[email protected]</saml:NameID>
−
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="2010-11-23T01:51:41.093Z"
Recipient="https://login-blitz03.soma.salesforce.com/?saml=MgoTx78aEPa2r1BHKCHmlfUKhH2mkDrXOjmYcjHG_qNDbsRM_6ZAo.wvGk"/>
</saml:SubjectConfirmation>
</saml:Subject>
−
<saml:Conditions NotBefore="2010-11-23T01:46:41.093Z"
NotOnOrAfter="2010-11-23T01:51:41.093Z">
−
<saml:AudienceRestriction>
<saml:Audience>https://childorgb.blitz03.blitz.salesforce.com</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
−
<saml:AuthnStatement AuthnInstant="2010-11-23T01:46:41.092Z">
−
730
Set Up and Maintain Your Salesforce Organization Single Sign-On
<saml:AuthnContext>
<saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
−
<saml:AttributeStatement>
−
<saml:Attribute Name="userId"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">005D0000001Ayzh</saml:AttributeValue>
</saml:Attribute>
−
<saml:Attribute Name="username"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">[email protected]</saml:AttributeValue>
</saml:Attribute>
−
<saml:Attribute Name="email"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">[email protected]</saml:AttributeValue>
</saml:Attribute>
−
<saml:Attribute Name="is_portal_user"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xsi:type="xs:anyType">false</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>
IN THIS SECTION:
Enable Salesforce as an Identity Provider
View Your Identity Provider Details
Prerequisites for Defining Service Providers
Before you define a service provider in Salesforce, follow these steps to define an identity provider and exchange configuration information with your provider.
Defining Service Providers as SAML-Enabled Connected Apps
Map Salesforce Users to App Users
View Your Service Provider Details
Enabling Identity Providers and Defining Service Providers for Portals and Sites
Using the Identity Provider Event Log
731
Set Up and Maintain Your Salesforce Organization Single Sign-On
Examples Using Identity Providers and Service Providers
SEE ALSO:
Enable Salesforce as an Identity Provider
View Your Identity Provider Details
Prerequisites for Defining Service Providers
Defining Service Providers as SAML-Enabled Connected Apps
Map Salesforce Users to App Users
View Your Service Provider Details
Enabling Identity Providers and Defining Service Providers for Portals and Sites
Examples Using Identity Providers and Service Providers
Enable Salesforce as an Identity Provider
To enable Salesforce as an identity provider:
1.
Set up a domain using My Domain , and deploy it to all users.
2. From Setup, enter
Identity Provider
in the
Quick Find
box, then select Identity
Provider, and then click Enable Identity Provider.
3. By default, a Salesforce identity provider uses a self-signed certificate generated automatically with the SHA-256 signature algorithm. If you've already created self-signed certificates, select the certificate to use when securely communicating with other services.
If you want to use a CA-signed certificate instead of self-signed certificate, following these steps.
a. Create and import a new CA-signed certificate. For instructions, see
.
b. From Setup, enter
Identity Provider
in the
Quick Find
box, then select
Identity Provider.
c. Click Edit, and then select the CA-signed certificate.
d. Click Save.
After you enable Salesforce as an identity provider, you can define service providers by creating connected apps (From Setup, enter
Apps
in the
Quick Find
box, then select Apps).
SEE ALSO:
Identity Providers and Service Providers
Generate a Self-Signed Certificate
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
732
Set Up and Maintain Your Salesforce Organization Single Sign-On
View Your Identity Provider Details
After you enable an identity provider for your organization, you can view the details from Setup by entering
Identity Provider
in the
Quick Find
box, then selecting Identity Provider.
You might need to share this information, such as
Issuer
, with your service provider.
From this page you can click:
•
Edit to change the certificate associated with your identity provider.
Warning: Changing the certificate can disable access to external applications. You might need to update all external applications to validate the new certificate information.
•
Disable to disable your identity provider.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
Warning: If you disable your identity provider, users can no longer access any external applications.
USER PERMISSIONS
•
Download Certificate to download the certificate associated with your identity provider. Your service provider can use this information for connecting to Salesforce.
•
Download Metadata to download the metadata associated with your identity provider. Your service provider can use this information for connecting to Salesforce.
Define and modify identity providers and service providers:
•
Customize Application
•
In the SAML Metadata Discovery Endpoints section, you can access URLs for the SAML identity provider information for your custom domain and each community. Your service provider can use these URLs to configure single sign-on to connect to Salesforce.
–
Salesforce Identity—URL of identity provider metadata for your custom domain in My Domain.
–
Community Name
Community Identity—URL of identity provider metadata for the named community.
•
In the service providers section, next to the name of an existing service provider, click Edit to change its definition, click Profiles to add or remove user profiles that have access to this service provider, or click Del to delete it.
Note: To define a new service provider, from Setup, enter
Apps
in the
Quick Find
box, then select Apps and then create a new SAML-enabled connected app.
SEE ALSO:
Identity Providers and Service Providers
733
Set Up and Maintain Your Salesforce Organization Single Sign-On
Prerequisites for Defining Service Providers
Before you define a service provider in Salesforce, follow these steps to define an identity provider and exchange configuration information with your provider.
1.
Enable Salesforce as an identity provider
.
2. Give your service provider information about your configuration of Salesforce as an identity provider. This information is available as metadata that you can download and give to your service provider. To obtain this metadata, from Setup, enter
Identity Provider
in the
Quick Find
box, select Identity Provider, then click Download Metadata.
If your service provider doesn’t support metadata, but supports certificates instead, you can download the certificate. From Setup, enter
Identity Provider
in the
Quick Find box, then select Identity Provider, then click Download Certificate.
3. Get the following information from your service provider:
•
Assertion consumer service (ACS) URL
•
Entity ID
•
Subject type—Specifies if the subject for the SAML response from Salesforce (as an identity provider) is a Salesforce user name or a federation ID
•
Security certificate—Only required when the service provider is initiating login to Salesforce and signing their SAML requests
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
SEE ALSO:
Identity Providers and Service Providers
Defining Service Providers as SAML-Enabled Connected Apps
.
EDITIONS
2. From Setup, enter
Apps
in the
Quick Find
box, then select Apps.
3. Under Connected Apps, click New.
4. Specify the required fields under Basic Information.
Available in: both Salesforce
Classic and Lightning
Experience
5. Under Web App Settings, select Enable SAML and then provide the following:
Entity Id
This value comes from the service provider. Each entity ID in an organization must be unique.
If you’re accessing multiple apps from your service provider, you only need to define the service provider once, and then use the
RelayState
parameter to append the URL values to direct the user to the correct app after signing in.
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
ACS URL
The ACS, or assertion consumer service, URL comes from the SAML service provider.
Subject Type
Specifies which field defines the user’s identity for the app. Options include the user’s username, federation ID, user ID, a custom attribute, or an algorithmically calculated
Define and modify identity providers and service providers:
•
Customize Application persistent ID. A custom attribute can be any custom field added to the User object in the organization, as long as it is one of the following data types: Email, Text, URL, or Formula (with Text Return Type). After you select
Custom Attribute
for the Subject Type, Salesforce displays a Custom Attribute field with a list of the available User object custom fields in the organization.
734
Set Up and Maintain Your Salesforce Organization Single Sign-On
Name ID Format
Specifies the format attribute sent in SAML messages. “Unspecified” is selected by default. Depending on your SAML service provider, you may want to set this to email address, persistent, or transient.
Issuer
By default, the standard issuer for your identity provider is used (your organization’s My Domain). If your SAML service provider requires a different value, specify it here.
6. Optionally specify the following:
Start URL
Directs users to a specific location when they run the application. The Start URL can be an absolute URL, such as https://na1.salesforce.com/001/o
, or it can be the link for the application name, such as https://customer.goodApp.com
for GoodApp. Specifying a Start URL makes the application available in the Force.com
app menu and in App Launcher.
Verify Request Signatures
Select
Verify Request Signatures
if the service provider gave you a security certificate. Browse your system for the certificate. This is only necessary if you plan to initiate logging in to Salesforce from the service provider and the service provider signs their SAML requests.
Important: If you upload a certificate, all SAML requests must be signed. If no certificate is uploaded, all SAML requests are accepted.
Encrypt SAML Response
Select
Encrypt SAML Response
to upload a certificate and select an encryption method for encrypting the assertion.
Valid encryption algorithm values are
AES–128
(128–bit key).
AES–256
(256–bit key). and
Triple-DES
(Triple Data
Encryption Algorithm).
7. Click Save.
To authorize users for this SAML application:
1. From Setup, enter
Connected Apps
in the
Quick Find
box, then select the option for managing connected apps.
2. Click the name of the application.
3. Select the profiles and/or permission sets that can access the application.
SEE ALSO:
Identity Providers and Service Providers
735
Set Up and Maintain Your Salesforce Organization Single Sign-On
Map Salesforce Users to App Users
If the
Subject Type
for the service provider definition is
Federation ID
, you must map the Salesforce user to the username used to sign into the service provider.
To map a Salesforce user to the app user:
1. From Setup, enter
Users
in the
Quick Find
box, then select Users, then click Edit for every user who needs to be mapped.
2. In
Federation ID
, under Single Sign On Information, enter the username to be used to log into the service provider.
3. Click Save.
Tip:
Use SOAP API if you have a large number of user profiles or permission sets to update.
See the
SOAP API Developer's Guide
.
SEE ALSO:
Identity Providers and Service Providers
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
View Your Service Provider Details
After you define a service provider for your organization by creating a SAML-enabled connected app, you can view the details from Setup by entering
Connected Apps
in the
Quick Find box, then selecting Connected Apps, and then selecting the name of the app. You might need to share this information, such as
SP-Initiated POST Endpoint
or
SP-Initiated
Redirect Endpoint
, with your service providers.
From this page you can click:
•
Edit to change the values of the service provider definition.
•
Delete to delete a service provider definition.
Warning:
If you delete a service provider definition, your users will no longer have access to that service provider.
•
Profile Access to change which profiles have access to this service provider.
SEE ALSO:
Identity Providers and Service Providers
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
736
Set Up and Maintain Your Salesforce Organization Single Sign-On
Enabling Identity Providers and Defining Service Providers for Portals and Sites
When enabling identity providers and defining service providers for Force.com Sites, Customer
Portals and partner portals, note the following:
•
When
defining a service provider , if the
Subject Type
is
Username
, the Salesforce organization ID is prepended to the user name in the SAML assertion. For example, if the user is [email protected]
, the subject for the SAML assertion contains
00DE0000000FFLT@[email protected]
. If the
Subject Type
is
Federation
ID
, the exact federation ID is used.
•
The attribute is_portal_user
included in the SAML assertion generated by Salesforce contains values. You might want to share the following example with your service provider.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance, and Unlimited Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
<saml:Attribute Name="is_portal_user"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
<saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:anyType">true
</saml:AttributeValue>
</saml:Attribute>
SEE ALSO:
Identity Providers and Service Providers
737
Set Up and Maintain Your Salesforce Organization Single Sign-On
Using the Identity Provider Event Log
The identity provider event log records both problems and successes with inbound SAML authentication requests from another app provider, and outbound SAML responses when Salesforce is acting as an identity provider. To view the identity provider event log, from Setup, enter
Identity Provider Event Log
in the
Quick Find
box, then select Identity Provider
Event Log. You can show successes, failures, or both in the log. You can view the 50 most recent events in the UI; you can view more by creating a report.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
Examples Using Identity Providers and Service Providers
This section contains two examples of setting up Salesforce as an identity provider, then setting up two different service providers:
•
Google Apps —shows service-provider initiated login.
•
Salesforce —shows identity-provider initiated login.
Setting up Single Sign-on to Google Apps Example
This example shows how to set up single sign-on from Salesforce to Google Apps. In this example,
Google is the service provider, and Google Apps is the app provided by the service provider.
For this example to work:
•
You must already have a Premier Edition Google Apps account
•
Your Salesforce organization must be set up for single sign-on using SAML 2.0
The general steps are as follows, with more specifics on each step below.
1.
Generate a domain name and enable an identity provider in your Salesforce organization.
2.
Define the service provider in Salesforce.
3.
Enable the Salesforce user and profile.
4.
5.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Developer,
Enterprise, Performance,
Unlimited, and
Database.com Editions
Tabs are not available in
Database.com
USER PERMISSIONS
Define and modify identity providers and service providers:
•
Customize Application
Generating a Domain Name and Enabling an Identity Provider
To prepare your Salesforce organization for this example, generate a domain name and enable Salesforce as an identity provider:
1. Log in to Salesforce.
2. Generate a domain name for your organization:
738
Set Up and Maintain Your Salesforce Organization Single Sign-On
a.
From Setup, enter
My Domain
in the
Quick Find
box, then select My Domain, enter a new subdomain name, and click
Check Availability.
b. If the name is available, click the Terms and Conditions check box, then click Register Domain.
Important: You must deploy your domain name before you can enable Salesforce as an identity provider.
3. Enable Salesforce as an identity provider:
a. From Setup, enter
Identity Provider
in the
Quick Find
box, then select Identity Provider.
b. Click Enable.
c. Click Download Certificate. Remember where you save the certificate, as you will upload it later.
Defining a Service Provider
To define the service provider:
1. Log in to Salesforce.
2. From Setup, enter
Apps
in the
Quick Find
box, then select Apps.
3. Click New in the Connected Apps section and for
Connected App Name
, enter
Google Apps
.
4. In the Web App Settings area, select Enable SAML and then enter the following information:
Field
ACS URL
Entity ID
Subject Type
Value
The URL for your Google App account, such as https://www.google.com/a/respond.info
google.com
Federation ID
5. Click Save.
6. To authorize access to this app, enter
Connected Apps
in the
Quick Find
box, select the option for managing connected apps, and then click the name of the application. Then select the current user’s profile.
7. Copy the value in the
SP-Initiated Redirect Endpoint
field. You will use this value later.
Mapping the Salesforce user to the Google Apps user
1. From your personal settings, enter
Advanced User Details
in the
Quick Find
box, then select Advanced User Details.
No results? Enter
Personal Information
in the
Quick Find
box, then select Personal Information.
2. Click Edit.
3. For
Federation ID
, enter the username you use to sign into Google Apps, for example, [email protected].
4. Click Save.
Setting up Google Apps
1. Log in to your Google Apps account.
739
Set Up and Maintain Your Salesforce Organization Single Sign-On
2. Click the Advanced tools tab, then the Set up single sign-on (SSO) link.
3. Check the
Enable Single Sign-on
checkbox.
4. For
Sign-in page URL
, enter the URL copied from the
SP-Initiated Redirect Endpoint
field, from
.
5. For
Sign-out page URL
, specify the URL where you want your users to go after they log out of Google Apps, such as, http://www.mydomain.salesforce.com
.
6. For
Change password URL
, use the following URL: https://mydomain.salesforce.com/_ui/system/security/ChangePassword
, where
mydomain
is the name you specified for your custom domain when you generated your domain.
7. For
Verification certificate
, upload the certificate you downloaded from enabling an identity provider
.
8. Click Save Changes.
Testing Your Implementation
To verify that your Salesforce organization can use single sign-on to Google Apps:
1. Log out of Google Apps and Salesforce.
2. Try to access a Google app page, such as http://docs.google.com/a/respond.info/
or http://mail.google.com/a/respond.info/
.
3. You are redirected to a Salesforce sign-on page. After you login, you are at the specified Google app page.
An alternate test is to add the Google App to a web tab in your Salesforce organization.
1. Log in to Salesforce.
2. From Setup, enter
Tabs
in the
Quick Find
box, then select Tabs, then click New in the
Web Tabs
section.
3. Choose a tab layout and click Next.
4. Enter a label to display on the tab.
5. Use the default name. This is the same as the label.
6. Click the
Tab Style
lookup icon to display the Tab Style Selector. Select an icon. Keep all other defaults.
7. Click Next.
8. In the Button or Link URL text box, enter a Google App page, such as docs.google.com/a/respond.info/
or mail.google.com/a/respond.info/
, then click Next.
Note:
This has to be an absolute URL, that is, it must contain either http://
or https://
.
9. Click Next and Save.
10. Click the new tab at the top of your page. You are automatically logged into the specified Google app page.
Setting up Single Sign-on from Salesforce to Salesforce
This example shows how to set up a Salesforce app to initiate single sign-on from one Salesforce organization to another.
The initiating Salesforce organization, that is, the organization that you want to initially log into, acts as the identity provider. The Salesforce organization that you want to access using an app acts as the service provider.For example, suppose you have two Salesforce organizations: a sales organization and an ideas organization. You can set up single sign-on between the two organizations so your users only have to log into and remember the password for one.
740
Set Up and Maintain Your Salesforce Organization Single Sign-On
For this example to work, your initiating Salesforce organization must be set up for single sign-on using SAML 2.0. The general steps are as follows, with more specifics on each of these steps.
1.
2.
Set up the Salesforce organization
that is acting as a service provider.
3.
Define the service provider app
in the Salesforce organization that is acting as an identity provider.
4.
Generating a Domain Name and Enabling an Identity Provider
All the work in the following steps is done on the Salesforce organization that is acting as the identity provider.
To prepare your Salesforce organization for this example, generate a domain name and enable Salesforce as an identity provider:
1. Log in to Salesforce.
2. Generate a domain name for your organization:
a. From Setup, enter
My Domain
in the
Quick Find
box, then select My Domain, enter a new subdomain name, and click
Check Availability.
b. If the name is available, click the Terms and Conditions check box, then click Register Domain.
Important: You must deploy your domain name before you can enable Salesforce as an identity provider.
3. Enable Salesforce as an identity provider:
a. From Setup, enter
Identity Provider
in the
Quick Find
box, then select Identity Provider.
b. Click Enable.
c. Click Download Certificate. Remember where you save the certificate, as you will upload it later.
Setting up a Salesforce Organization as Service Provider
To configure a second Salesforce organization as the service provider:
1. Log in to the Salesforce organization that acts as the service provider.
2. Enable and configure SAML:
a. From Setup, enter
Single Sign-On Settings
in the
Quick Find
box, then select Single Sign-On Settings, then click Edit.
b. Select the
SAML Enabled
check box.
c. Use the following settings:
Field
SAML Version
Issuer
Identity Provider Certificate
Value
2.0
The identity provider issuer URL, created when the identity provider is set up. For example, https://mycustomdomain.salesforce.com
.
Browse for the certificate you downloaded in enabling an identity provider.
741
Set Up and Maintain Your Salesforce Organization
Field
SAML User ID Type
SAML User ID Location
Single Sign-On
Value
Select
Assertion contains the Federation
ID from the User object
Select
User ID is in the NameIdentifier element of the Subject statement
d. Click Save.
e. Copy and save the values from the fields
Salesforce Login URL
and
Entity ID
. You need these values later, when defining the Salesforce service provider.
3. Link your user in the service provider organization to the user in the identity provider organization:
a. From your personal settings, enter
Advanced User Detail
in the
Quick Find
box, then select Advanced User
Detail. No results? Enter
Personal Information
in the
Quick Find
box, then select Personal Information.
b. Click Edit.
c. For
Federation ID
, enter the username used to sign into theSalesforce identity provider organization, for example,
d. Click Save.
Defining the Service Provider in the Identity Provider Organization
To define the service provider, you create a SAML enabled Web App as a connected app:
1. Log in to the Salesforce organization that acts as the identity provider.
2. From Setup, enter
Apps
in the
Quick Find
box, then select Apps, then in the Connected Apps section, click New.
3. Specify the following information:
Field
Connected App Name
Contact Email
Enable SAML
Entity Id
ACS URL
Subject Type
Value
Salesforce Service Provider
Contact Salesforce should use for contacting you or your support team.
Select this option to enter service provider details.
Use the Entity ID from setting up the service provider
Use the Salesforce Login URL from
setting up the service provider
Select
Username
4. Click Save.
5. Select the profiles allowed to access this service provider. You must select the current user's profile for this example to work.
6. Click Save.
7. Copy down the value of the
IdP-Initiated Login URL
field. You will use this value later, in testing.
742
Set Up and Maintain Your Salesforce Organization Single Sign-On
Testing Your Implementation
To verify that your Salesforce organizations can use single sign-on to connect, create a web tab:
1. Log in to the Salesforce organization that is acting like a service provider.
2. From Setup, enter
Tabs
in the
Quick Find
box, then select Tabs, then click New in the
Web Tabs
section.
3. Choose a tab layout and click Next.
4. Enter a label to display on the tab.
5. Use the default name. This is the same as the label.
6. Click the
Tab Style
lookup icon to display the Tab Style Selector. Select an icon.
7. Click Next.
8. In the Button or Link URL text box, enter the value of the
IdP-Initiated Login URL
field from
defining the service provider ,
then click Next.
Note:
This has to be an absolute URL, that is, it must contain either http://
or https://
.
9. Click Next, then Save.
10. Click the new tab at the top of your page. If you have logged out of the Salesforce organization that acts as the identity provider, you are prompted to log in. Once you are logged in, you should see the Salesforce organization that acts as the identity provider in the tab.
SEE ALSO:
Identity Providers and Service Providers
Configure Remote Site Settings
Before any Visualforce page, Apex callout, or JavaScript code using XmlHttpRequest in an s-control or custom button can call an external site, that site must be registered in the Remote Site Settings page, or the call fails.
Note: To enable corresponding access for Lightning components, create a CSP Trusted Site.
To access the page, from Setup, enter
Remote Site Settings
in the
Quick Find
box, then select Remote Site Settings. This page displays a list of any remote sites already registered and provides additional information about each site, including remote site name and URL.
For security reasons, Salesforce restricts the outbound ports you may specify to one of the following:
•
80: This port only accepts HTTP connections.
•
443: This port only accepts HTTPS connections.
•
1024–66535 (inclusive): These ports accept HTTP or HTTPS connections.
To register a new site:
1. Click New Remote Site.
2. Enter a descriptive term for the
Remote Site Name
.
3. Enter the URL for the remote site.
4. To allow access to the remote site regardless of whether the user’s connection is over HTTP or
HTTPS, select the
Disable Protocol Security
checkbox. When selected, Salesforce
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited,
Developer, and
Database.com Editions
Visualforce and S-controls are not available in
Database.com
USER PERMISSIONS
To configure remote settings:
•
Customize Application or Modify All Data
743
Set Up and Maintain Your Salesforce Organization Single Sign-On can pass data from an HTTPS session to an HTTP session, and vice versa. Only select this checkbox if you understand the security implications.
5. Optionally, enter a description of the site.
6. Click Save to finish, or click Save & New to save your work and begin registering an additional site.
Named Credentials
A named credential specifies the URL of a callout endpoint and its required authentication parameters in one definition. To simplify the setup of authenticated callouts, specify a named credential as the callout endpoint. If you instead specify a URL as the callout endpoint, you must register that URL in your org’s remote site settings and handle the authentication yourself. For example, for an Apex callout, your code would need to handle authentication, which can be less secure and especially complicated for OAuth implementations.
Salesforce manages all authentication for callouts that specify a named credential as the callout endpoint so that you don’t have to. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the named credential.
Named credentials are supported in these types of callout definitions:
•
Apex callouts
•
External data sources of these types:
–
Salesforce Connect: OData 2.0
–
Salesforce Connect: OData 4.0
–
Salesforce Connect: Custom (developed with the Apex Connector Framework)
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
By separating the endpoint URL and authentication from the callout definition, named credentials make callouts easier to maintain. For example, if an endpoint URL changes, you update only the named credential. All callouts that reference the named credential simply continue to work.
If you have multiple orgs, you can create a named credential with the same name but with a different endpoint URL in each org. You can then package and deploy—on all the orgs—one callout definition that references the shared name of those named credentials.
For example, the named credential in each org can have a different endpoint URL to accommodate differences in development and production environments. If an Apex callout specifies the shared name of those named credentials, the Apex class that defines the callout can be packaged and deployed on all those orgs without programmatically checking the environment.
Named credentials support basic password authentication and OAuth 2.0. You can set up each named credential to use an org-wide named principal or to use per-user authentication so that users can manage their own credentials.
To reference a named credential from a callout definition, use the named credential URL. A named credential URL contains the scheme callout:
, the name of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path
.
You can append a query string to a named credential URL. Use a question mark (?) as the separator between the named credential URL and the query string. For example: callout:My_Named_Credential/some_path?format=json
.
Example: In the following Apex code, a named credential and an appended path specify the callout’s endpoint.
HttpRequest req = new HttpRequest(); req.setEndpoint(
'
callout:
My_Named_Credential/some_path
'); req.setMethod('GET');
Http http = new Http();
744
Set Up and Maintain Your Salesforce Organization
HTTPResponse res = http.send(req);
System.debug(res.getBody());
The referenced named credential specifies the endpoint URL and the authentication settings.
Single Sign-On
If you use OAuth instead of password authentication, the Apex code remains the same. The authentication settings differ in the named credential, which references an authentication provider that’s defined in the org.
In contrast, let’s see what the Apex code looks like without a named credential. Notice that the code becomes more complex to handle authentication, even if we stick with basic password authentication. Coding OAuth is even more complex and is an ideal use case for named credentials.
HttpRequest req = new HttpRequest(); req.setEndpoint(
'
https://my_endpoint.example.com/some_path
'); req.setMethod('GET');
// Because we didn't set the endpoint as a named credential,
// our code has to specify:
// - The required username and password to access the endpoint
// - The header and header information
String username = '
myname
';
String password = '
mypwd
';
Blob headerValue = Blob.valueOf(username + ':' + password);
745
Set Up and Maintain Your Salesforce Organization Single Sign-On
String authorizationHeader = 'BASIC ' +
EncodingUtil.base64Encode(headerValue); req.setHeader('Authorization', authorizationHeader);
// Create a new http object to send the request object
// A response object is generated as a result of the request
Http http = new Http();
HTTPResponse res = http.send(req);
System.debug(res.getBody());
IN THIS SECTION:
Create a named credential to specify the URL of a callout endpoint and its required authentication parameters in one definition. You can then specify the named credential as a callout endpoint to let Salesforce handle all the authentication. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the named credential.
Grant Access to Authentication Settings for Named Credentials
For named credentials that use per-user authentication, grant access to users through permission sets and profiles. Doing so lets users set up and manage their own authentication settings for accessing the external system.
SEE ALSO:
Grant Access to Authentication Settings for Named Credentials
Apex Developer Guide : Invoking Callouts Using Apex
External Authentication Providers
Define a Named Credential
Create a named credential to specify the URL of a callout endpoint and its required authentication parameters in one definition. You can then specify the named credential as a callout endpoint to let Salesforce handle all the authentication. You can also skip remote site settings, which are otherwise required for callouts to external sites, for the site defined in the named credential.
Named credentials are supported in these types of callout definitions:
•
Apex callouts
•
External data sources of these types:
–
Salesforce Connect: OData 2.0
–
Salesforce Connect: OData 4.0
–
Salesforce Connect: Custom (developed with the Apex Connector Framework)
To set up a named credential:
1. From Setup, enter
Named Credentials
in the
Quick Find
box, then select Named
Credentials.
2. Click New Named Credential, or click Edit to modify an existing named credential.
3. Complete the fields.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
USER PERMISSIONS
To view named credentials:
•
View Setup and
Configuration
To create, edit, or delete named credentials:
•
Customize Applications
746
Set Up and Maintain Your Salesforce Organization
Field
Label
Name
URL
Certificate
Identity Type
Description
Single Sign-On
A user-friendly name for the named credential that’s displayed in the Salesforce user interface, such as in list views.
If you set
Identity Type
to Per User, this label appears when your users view or edit their authentication settings for external systems.
A unique identifier that’s used to refer to this named credential from callout definitions and through the API.
The name can contain only underscores and alphanumeric characters. It must be unique, begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores.
The URL or root URL of the callout endpoint. Must begin with
http://
or
https://
. Can include a path but not a query string. Examples:
•
http://my_endpoint.example.com
•
https://my_endpoint.example.com/secure/payroll
You can, however, append a query string and a specific path in the callout definition’s reference to the named credential. For example, an Apex callout could reference the named credential
“My_Payroll_System” as follows.
HttpRequest req = new HttpRequest(); req.setEndpoint(' callout:My_Payroll_System/paystubs?format=json
');
If you specify a certificate, your Salesforce org supplies it when establishing each two-way SSL connection with the external system. The certificate is used for digital signatures, which verify that requests are coming from your Salesforce org.
Determines whether you're using one set or multiple sets of credentials to access the external system.
•
Anonymous: No identity and therefore no authentication.
•
Per User: Use separate credentials for each user who accesses the external system via callouts.
Select this option if the external system restricts access on a per-user basis.
After you grant user access through permission sets or profiles in Salesforce, users can manage their own authentication settings for external systems in their personal settings.
•
Named Principal: Use the same set of credentials for all users who access the external system from your org. Select this option if you designate one user account on the external system for all your Salesforce org users.
4. Select the authentication protocol.
•
If you select Password Authentication, enter the username and password for accessing the external system.
•
If you select OAuth 2.0, complete the following fields.
747
Set Up and Maintain Your Salesforce Organization Single Sign-On
Field
Authentication
Provider
Scope
Description
Choose the provider. See
External Authentication Providers
on page 693.
Specifies the scope of permissions to request for the access token. Your authentication provider
determines the allowed values. See Use the Scope Parameter
on page 722.
Note:
–
The value that you enter replaces the
Default Scopes
value that’s defined in the specified authentication provider.
–
Whether scopes are defined can affect whether each OAuth flow prompts the user with a consent screen.
–
We recommend that you request a refresh token or offline access. Otherwise, when the token expires, you lose access to the external system.
Start
Authentication Flow on Save
To authenticate to the external system and obtain an OAuth token, select this checkbox. This authentication process is called an OAuth flow.
When you click Save, the external system prompts you to log in. After successful login, the external system grants you an OAuth token for accessing its data from this org.
Redo the OAuth flow when you need a new token—for example, if the token expires—or if you edit the
Scope
or
Authentication Provider
fields.
5. If you want to use custom headers or bodies in the callouts, enable the relevant options.
Field
Generate Authorization Header
Description
By default, Salesforce generates an authorization header and applies it to each callout that references the named credential.
Deselect this option only if one of the following statements applies.
•
The remote endpoint doesn’t support authorization headers.
•
The authorization headers are provided by other means. For example, in Apex callouts, the developer can have the code construct a custom authorization header for each callout.
This option is required if you reference the named credential from an external data source.
Allow Merge Fields in HTTP Header
Allow Merge Fields in HTTP Body
In each Apex callout, the code specifies how the HTTP header and request body are constructed. For example, the Apex code can set the value of a cookie in an authorization header.
These options enable the Apex code to use merge fields to populate the
HTTP header and request body with org data when the callout is made.
These options aren’t available if you reference the named credential from an external data source.
748
Set Up and Maintain Your Salesforce Organization Single Sign-On
To reference a named credential from a callout definition, use the named credential URL. A named credential URL contains the scheme callout:
, the name of the named credential, and an optional path. For example: callout:My_Named_Credential/some_path
.
You can append a query string to a named credential URL. Use a question mark (?) as the separator between the named credential URL and the query string. For example: callout:My_Named_Credential/some_path?format=json
.
SEE ALSO:
Grant Access to Authentication Settings for Named Credentials
Apex Developer Guide : Invoking Callouts Using Apex
Grant Access to Authentication Settings for Named Credentials
For named credentials that use per-user authentication, grant access to users through permission sets and profiles. Doing so lets users set up and manage their own authentication settings for accessing the external system.
1. From Setup, enter
Permission Sets
in the
Quick Find
box, then select Permission
Sets or Profiles.
2. Click the name of the permission set or profile that you want to modify.
3. Do one of the following.
•
For a permission set, or for a profile in the enhanced profile user interface, click Named
Credential Access in the Apps section. Then click Edit.
•
For a profile in the original profile user interface, click Edit in the Enabled Named Credential
Access section.
4. Add the named credentials that you want to enable.
5. Click Save.
SEE ALSO:
EDITIONS
Available in: Salesforce
Classic and Lightning
Experience
Available in all editions
Permission sets available in:
Contact Manager,
Professional, Group,
Enterprise, Performance,
Unlimited, Developer, and
Database.com Editions
USER PERMISSIONS
To edit permission sets and user profiles:
•
Manage Profiles and
Permission Sets
749
Set Up and Maintain Your Salesforce Organization Single Sign-On
Identity Connect
Identity Connect integrates Microsoft Active Directory (AD) with Salesforce. User information entered in AD is shared with Salesforce seamlessly and instantaneously. Companies that use AD for user management can use Identity Connect to manage Salesforce accounts.
Changes in AD are reflected in Salesforce in near real time. For example, when a user is created in
AD, the Salesforce user account is created as part of the provisioning process. When deprovisioned, the user’s Salesforce session is revoked immediately.
You can also use Identity Connect for single sign-on to Salesforce.
Identity Connect runs as a service on either Windows or Linux platforms.
IN THIS SECTION:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available for an additional cost in: Enterprise,
Performance, and
Unlimited Editions.
Developer Edition includes
10 Identity Connect permission set licenses.
SEE ALSO:
Identity Connect Implementation Guide
Installing Identity Connect
Your organization must have at least one Identity Connect license. To obtain Identity Connect, contact Salesforce.
The Identity Connect software will typically be installed on a server by your IT department. Each user does not need to install Identity Connect individually.
1. From Setup, enter
Identity Connect
in the
Quick Find
box, then select Identity
Connect.
Note: Identity Connect doesn’t appear in Setup until Salesforce adds the feature to your organization.
2. Click the download link that corresponds to your operating system.
3. Install the software according to the Salesforce Identity Connect Implementation Guide .
SEE ALSO:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available for an additional cost in: Enterprise,
Performance, and
Unlimited Editions.
Developer Edition includes
10 Identity Connect permission set licenses.
USER PERMISSIONS
To install Identity Connect:
•
Manage Users
750
Set Up and Maintain Your Salesforce Organization My Domain
Enabling Identity Connect
To obtain Identity Connect, contact Salesforce.
To enable Identity Connect for a user:
1.
Assign the Identity Connect license to the user .
2. Create a permission set and add the “Use Identity Connect” permission to it.
3. Assign the permission set to the user.
SEE ALSO:
Identity Connect Implementation Guide
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available for an additional cost in: Enterprise,
Performance, and
Unlimited Editions.
Developer Edition includes
10 Identity Connect permission set licenses.
USER PERMISSIONS
To assign a permission set license:
•
Manage Internal Users
To create and assign permission sets:
•
Manage Profiles and
Permission Sets
To view users that are assigned to a permission set:
•
View Setup and
Configuration
My Domain
Add a subdomain to your Salesforce org URL with the My Domain Salesforce feature. Having a subdomain lets you highlight your brand and makes your org more secure. A subdomain is convenient and allows you to personalize your login page.
Using My Domain, you define a subdomain that's part of your Salesforce domain. For example, developer
is a subdomain of the salesforce.com
domain. With a subdomain, you replace the URL that Salesforce assigned you, like https://na30.salesforce.com
, with your chosen name, like https://somethingcool.my.salesforce.com
. A subdomain is also referred to as a custom domain. However, a custom domain has a specific meaning for
Salesforce Communities.
A subdomain name helps you better manage login and authentication for your org in several key ways. You can:
•
Highlight your business identity with your unique domain URL
•
Brand your login screen and customize right-frame content
•
Block or redirect page requests that don’t use the new domain name
•
Work in multiple Salesforce orgs at the same time
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
751
Set Up and Maintain Your Salesforce Organization My Domain
•
Set custom login policy to determine how users are authenticated
•
Let users log in using a social account, like Google and Facebook, from the login page
•
Allow users to log in once to access external services
My Domain is required before you can use these Salesforce features:
•
Single sign-on (SSO) with external identity providers
•
Social sign-on with authentication providers, such as Google and Facebook
•
Lightning components in Lightning component tabs, Lightning pages, the Lightning App Builder, or standalone apps
Watch a Demo (5:11 minutes)
My Domain is also available for sandbox environments.
Your domain name uses standard URL format, including:
•
Protocol: https://
•
Subdomain prefix: your brand or term
•
Domain: my.salesforce.com
Your name can include up to 40 letters, numbers, and hyphens. You can’t start the subdomain name with root, status, or a hyphen.
You have the chance to try out names and check availability before you commit to your domain name.
Salesforce is enabled as an identity provider when a domain is created. After your domain is deployed, you can add or change identity providers and increase security for your org by customizing your domain’s login policy.
Important: After you deploy your domain, it’s activated immediately, and requests with the original URL are redirected to your new domain. Only Salesforce Customer Support can disable or change your domain name after it’s deployed.
IN THIS SECTION:
Implementing your subdomain name with My Domain is quick and easy.
Register your org’s custom domain name with My Domain. You can try out names and check availability before registering the name.
Guidelines and Best Practices for Implementing My Domain
These tips smooth the transition to using the subdomain that you created with My Domain.
Test and Deploy Your New My Domain Subdomain
After you set up your subdomain with My Domain, test it and then roll it out to your users. Testing gives you the chance to explore your subdomain. It also helps you verify URLs for pages before rolling out the subdomain to your users.
When you set up a subdomain name for your org with My Domain, all your application URLs, including Visualforce pages, also change. Make sure that you update all application URLs before you deploy a domain name. For example, the
Notification URL
field in Chatter Answers continues to send notifications with the old URLs to internal users unless you update it. This table shows you the differences.
Set the My Domain Login Policy
Manage your user logins by customizing the login policy for your domain. By default, users log in from a generic Salesforce login page, bypassing the login page specific to your domain. If you don’t set a login policy, users can make page requests without your domain name, such as when using old bookmarks.
752
Set Up and Maintain Your Salesforce Organization My Domain
Customize Your Login Page with Your Brand
Customize the look and feel of your login page by adding a background color, logo, and right-side content. Customizing your login page with your company’s branding helps users recognize your page.
Add Identity Providers on a Login Page
Allow users to authenticate using alternate identity provider options right from your login page. If you’ve enabled single sign-on and configured SAML, or set up external authentication providers as Auth. Providers in Setup, you can provide links to these identity providers on your domain’s login page. Users are sent to the identity provider’s login screen to authenticate and then redirected back to Salesforce.
Get System Performance and Maintenance Information with My Domain
You can get information about system performance and availability from trust.salesforce.com
. Trust reports status information based on your org instance. If you’re using My Domain and don’t know your org instance, you can look it up.
Set Up a My Domain Name
Implementing your subdomain name with My Domain is quick and easy.
1.
Find a domain name that’s available and sign up for it.
2.
Customize the logo, background color, and right-frame content on your login page.
3.
Add or change the identity providers available on your login page.
4.
Test your domain name and deploy it to your entire org.
5.
Set the login policy for users accessing your pages.
SEE ALSO:
Test and Deploy Your New My Domain Subdomain
Set the My Domain Login Policy
Customize Your Login Page with Your Brand
Add Identity Providers on a Login Page
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
USER PERMISSIONS
To set up a domain name:
•
Customize Application
753
Set Up and Maintain Your Salesforce Organization My Domain
Define Your Domain Name
Register your org’s custom domain name with My Domain. You can try out names and check availability before registering the name.
Start setting up your My Domain subdomain by finding a domain name unique to your org and registering it. Choose your name carefully. When you register, Salesforce updates its domain name registries with your domain name. After the name is registered, only Salesforce Customer Support can disable or change your domain name.
1. From Setup, enter
My Domain
in the
Quick Find
box, then select My Domain.
2. Enter the subdomain name you want to use within the sample URL. For example, if a company called Universal Containers uses the subdomain universalcontainers
, the company’s login URL is https://universalcontainers.my.salesforce.com/
. Your name can include up to 40 letters, numbers, and hyphens.
You can’t use these reserved words for subdomains:
•
www
•
salesforce
•
heroku
You can’t start the domain name with:
•
root
•
status
•
a hyphen (-)
3. Click Check Availability. If your name is already taken, choose a different one.
4. Click Register Domain.
5. You receive an email when your domain name is ready for testing. It can take a few minutes.
The new subdomain is available to your users after you test and deploy it.
SEE ALSO:
Guidelines and Best Practices for Implementing My Domain
Test and Deploy Your New My Domain Subdomain
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
USER PERMISSIONS
To define a domain name:
•
Customize Application
754
Set Up and Maintain Your Salesforce Organization My Domain
Guidelines and Best Practices for Implementing My Domain
These tips smooth the transition to using the subdomain that you created with My Domain.
EDITIONS
•
Communicate the upcoming change to your users before deploying it.
•
Deploy your new subdomain when your org receives minimal traffic, like during a weekend, so you can troubleshoot while traffic is low.
•
If you’ve customized your Salesforce UI with features, such as custom buttons or Visualforce pages, make sure that you test your customizations thoroughly before deploying your domain name. Look for broken links due to hard-coded references (instance-based URLs), and use your subdomain URLs instead. For more information, enter “hard-coded references” in Salesforce
Help Test them in a sandbox environment first.
•
Make sure that you update all application URLs before you deploy a domain name. For example, the
Email Notification URL
field in Chatter Answers continues to send notifications with the old URLs to internal users unless you update it.
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
•
If your domain is registered but has not yet been deployed, URLs contain your subdomain name when you log in from the My
Domain login page. However, links that originate from merge fields that are embedded in emails sent asynchronously, such as workflow emails, still use the old URLs. After your domain is deployed, those links show the new My Domain URLs.
•
Help your users get started using your new subdomain by providing links to pages they use frequently, such as your login page. Let your users know if you changed the login policy, and encourage them to update their bookmarks the first time they’re redirected.
•
Choose the Redirect Policy option Redirected with a warning to the same page within the domain to give users time to update their bookmarks with the new subdomain name. After a few days or weeks, change the policy to Not redirected. This option requires users to use your subdomain name when viewing your pages. It provides the greatest level of security.
•
Only use Prevent login from https://login.salesforce.com if you’re concerned that users who aren’t aware of your subdomain try to use it. Otherwise, leave the option available to your users while they get used to the new domain name.
•
Bookmarks don’t work when the Redirect to the same page within the domain option is selected for partner portals. Manually change the existing bookmarks to point to the new domain URL by replacing the Salesforce instance name with your custom domain name. For example, replace https://na30.salesforce.com/
with https://yourDomain.my.salesforce.com/
in the bookmark’s URL.
•
If you block application page requests that don’t use the new Salesforce subdomain URLs, let your users know that they must either update old bookmarks or create new ones for the login page. They must also update tabs or links within the app. If you change your login redirect policy to Not Redirected, users must use the new subdomain URLs immediately.
•
If you are using My Domain, you can identify which users are logging in with the new login URL and when. From Setup, enter
Login
History
in the
Quick Find
box, then select Login History and view the Username and Login URL columns.
•
On the login.salesforce.com
page, users can click Log in to a custom domain to enter your subdomain name and log in. In this case, they must know the subdomain name. As a safeguard, give them a direct link to your subdomain’s login page as well.
If You Have the Following
API integrations into your org
Do the Following
Check to see if the API client is directly referencing the server endpoint. The API client should use the LoginResult.serverURL
value returned by the login request, instead of using a hard-coded server URL.
After your subdomain is deployed, Salesforce returns the server
URL containing your domain. Redirect policy settings have no effect on API calls. That is, old calls to instance URLs continue to work.
755
Set Up and Maintain Your Salesforce Organization
If You Have the Following
Email templates
Custom Visualforce pages or custom Force.com apps
Chatter
Zones for Communities (Ideas/Answers/Chatter Answers)
My Domain
Do the Following
However, the best practice is to use the value returned by
Salesforce.
Replace references to the org’s instance URL with your subdomain.
Replace references to the org’s instance URL with your subdomain.
See How to find hard-coded references with the Force.com IDE .
Tell your users to update any bookmarks in the left navigation of their Chatter groups.
Manually update the email notification URL.
To update the URL, clear the existing URL so that the field is blank and save the page. Then the system populates the field with your new My Domain URL.
SEE ALSO:
Test and Deploy Your New My Domain Subdomain
Test and Deploy Your New My Domain Subdomain
After you set up your subdomain with My Domain, test it and then roll it out to your users. Testing gives you the chance to explore your subdomain. It also helps you verify URLs for pages before rolling out the subdomain to your users.
Important: After you deploy your domain, it’s activated immediately, and requests with the original URL are redirected to your new domain. Only Salesforce Customer Support can disable or change your domain name after it’s deployed.
1. Test your domain login. From Setup, enter
My Domain
in the
Quick Find
box, then select My Domain. Or, log out of your DE org and log in to Salesforce using your new subdomain name. Or, click the login link in the activation email you received.
You can customize your domain login page and add authentication services (like social sign-on) before you deploy the domain to your users. You can also test the domain in a sandbox environment.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
USER PERMISSIONS
2. Test the new domain name by clicking tabs and links. All pages now show your new domain name.
To set up a domain name:
•
Customize Application
If you’ve customized your Salesforce UI with features, such as custom buttons or Visualforce pages, make sure that you test your customizations thoroughly before deploying your domain name. Look for broken links due to hard-coded references (instance-based URLs), and use your subdomain URLs instead. For more information, enter “hard-coded references” in Salesforce Help
3. To roll out the new domain name to your org, from Setup, enter
My Domain
in the
Quick Find
box, then select My
Domain.Then click Deploy to Users and OK.
756
Set Up and Maintain Your Salesforce Organization My Domain
When you deploy your domain, it’s activated immediately, and all users are redirected to pages with new domain addresses. You can now set login policies in the Domain Settings section that appears after you deploy your domain. For example, you can prevent users from logging in from login.salesforce.com.
SEE ALSO:
Guidelines and Best Practices for Implementing My Domain
Customize Your Login Page with Your Brand
Add Identity Providers on a Login Page
Set the My Domain Login Policy
My Domain URL Changes
When you set up a subdomain name for your org with My Domain, all your application URLs, including Visualforce pages, also change. Make sure that you update all application URLs before you deploy a domain name. For example, the
Email Notification URL
field in Chatter
Answers continues to send notifications with the old URLs to internal users unless you update it.
This table shows you the differences.
URL Type
Login
Old URL New URL
https://login.salesforce.com
https://<subdomain>.my.
salesforce.com
Application page or tab
Visualforce page with namespace https://<instance>.salesforce.com/<pageID> https://<subdomain>.my.
salesforce.com/<pageID>
Visualforce page with no namespace https://c.<instance>visual.force.com/apex/<pagename> https://<subdomain>--c.
<instance>.visual.
force.com/apex/<pagename> https://<yournamespace101>.
<instance>.visual.
force.com/apex/<pagename> https://<subdomain>--
<yournamespace>.
<instance>.visual.force.com
/apex/
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
Note: If you implement My Domain in a sandbox environment, the URL format is https://<subdomain>--<sandboxname>.<instance>.my.salesforce.com
. Because you can’t have namespaces in a sandbox environment, the format of all Visualforce page URLs in a sandbox is https://<subdomain>--<sandboxname>--c.<instance>.visual.force.com/apex/<pagename>
.
SEE ALSO:
Guidelines and Best Practices for Implementing My Domain
757
Set Up and Maintain Your Salesforce Organization My Domain
Set the My Domain Login Policy
Manage your user logins by customizing the login policy for your domain. By default, users log in from a generic Salesforce login page, bypassing the login page specific to your domain. If you don’t set a login policy, users can make page requests without your domain name, such as when using old bookmarks.
1. From Setup, enter
My Domain
in the
Quick Find
box, then select My Domain.
2. Under My Domain Settings, click Edit.
3. To disable authentication for users who don’t use your domain-specific login page, set a login policy. Selecting the login policy prevents users from logging in on the generic https://<instance>.salesforce.com/
login page and then being redirected to your pages after login.
4. Choose a redirect policy.
a. To allow users to continue using URLs that don’t include your domain name, select Redirect
to the same page within the domain.
Note:
Bookmarks don’t work when the Redirect to the same page within the
domain option is selected for partner portals. Manually change the existing bookmarks to point to the new domain URL by replacing the Salesforce instance name with your custom domain name. For example, replace https://na30.salesforce.com/
with https://yourDomain.my.salesforce.com/
in the bookmark’s URL.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
USER PERMISSIONS
To set login policy for a domain:
•
Customize Application
b. To remind users to use your domain name, select Redirected with a warning to the same page within the domain. After reading the warning, users are redirected to the page. Select this option for a few days or weeks to help users transition to a new domain name.
c. To require users to use your domain name when viewing your pages, select Not redirected.
5. Click Save.
SEE ALSO:
Guidelines and Best Practices for Implementing My Domain
758
Set Up and Maintain Your Salesforce Organization My Domain
Customize Your Login Page with Your Brand
Customize the look and feel of your login page by adding a background color, logo, and right-side content. Customizing your login page with your company’s branding helps users recognize your page.
Setting Up a My Domain (5:10 minutes. Login page branding starts at 2:43.)
1. From Setup, enter
My Domain
in the Quick Find box, then select My Domain.
2. Under Authentication Configuration, click Edit.
3. To customize your logo, upload an image.
Images can be .jpg, .gif, or .png files up to 100 KB. Maximum image size is 250px by 125px.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
4.
To customize your login page background, click the or enter a valid hexadecimal color code.
USER PERMISSIONS
5. To support advanced authentication methods for iOS users, select Use the native browser
for user authentication on iOS.
To customize a login page:
•
Customize Application
This iOS user authentication option is for users of Salesforce1 and Mobile SDK applications on iOS devices. It enables support of authentication methods, such as Kerberos, Windows NT LAN Manager (NTLM), or certificate-based authentication. When you select this option, users on iOS devices are redirected to their native browser when using single sign-on authentication into your custom domain. For other operating systems, Salesforce1 and applications using Mobile SDK version 3.1
or later can support certificate-based authentication when the applications are integrated with Mobile Device Management (MDM) software.
6. Enter the URL of the file to be included in the right-side iFrame on the login page.
The content in the right-side iFrame can resize to fill about 50% of the page. Your content must be hosted at a URL that uses SSL encryption and the https:// prefix. To build your own custom right-side iFrame content page using responsive web design, use the
My Domain Sample template.
Example:
https://c.salesforce.com/login-messages/promos.html
7. Optionally, select authentication services as identity providers on the login page, such as social sign-on providers like Google and
Facebook. Users can then log in with their social account credentials. Configure authentication services as Auth. Providers in Setup.
8. Click Save.
SEE ALSO:
Add Identity Providers on a Login Page
Set the My Domain Login Policy
External Authentication Providers
759
Set Up and Maintain Your Salesforce Organization My Domain
Add Identity Providers on a Login Page
Allow users to authenticate using alternate identity provider options right from your login page. If you’ve enabled single sign-on and configured SAML, or set up external authentication providers as Auth. Providers in Setup, you can provide links to these identity providers on your domain’s login page. Users are sent to the identity provider’s login screen to authenticate and then redirected back to Salesforce.
Note: Available authentication services include all providers configured as SAML single sign-on identify providers or external authentication providers, except Janrain. You can’t use
Janrain for authentication from the login page.
1. From Setup, enter
My Domain
in the
Quick Find
box, then select My Domain.
2. Under Authentication Configuration, click Edit.
3. Select one or more already configured authentication services as an identity provider.
4. Click Save.
SEE ALSO:
Customize Your Login Page with Your Brand
Set the My Domain Login Policy
External Authentication Providers
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
USER PERMISSIONS
To add identity providers on a login page:
•
Customize Application
Get System Performance and Maintenance Information with My Domain
You can get information about system performance and availability from trust.salesforce.com
. Trust reports status information based on your org instance. If you’re using My Domain and don’t know your org instance, you can look it up.
Here’s how to get status information using your domain name.
1. Go to trust.salesforce.com
.
2. Under System Status, click Learn More.
3. Under status.salesforce.com, click Status.
The Status & Maintenance page shows the status for each org instance.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, Professional, and Group Editions.
4. At the top right of the page, click My Domain.
5. Enter your domain name in the search bar to get your org instance.
Don’t enter the complete URL. For example, use
yourDomain
, not https://yourDomain.my.salesforce.com/
.
6. Under Status & Maintenance, select All, and look for your instance.
USER PERMISSIONS
To set up a domain name:
•
Customize Application
SEE ALSO:
760
Set Up and Maintain Your Salesforce Organization
My Domain FAQ
EDITIONS
IN THIS SECTION:
Using My Domain, Salesforce admins can define a subdomain within their Salesforce org. The subdomain name appears in all org URLs and replaces the instance name (such as na30). For example, you can brand your URL by naming the subdomain your company name, https://myCompanyName.my.salesforce.com/
. My Domain is not the same as the custom domain for sites, communities, or portals. The domains are defined separately.
Which Salesforce Editions is My Domain available in?
What are the advantages of My Domain?
Create a subdomain with My Domain to enable users to single sign-on into your org. You can also customize your login page and use Salesforce as an identity provider.
Does My Domain work differently in different Salesforce Editions?
Does My Domain work in sandboxes?
What are the differences between the redirect policy options?
How does My Domain work with single sign-on?
Is My Domain available for the API?
Is the subdomain for My Domain related to the subdomain for Sites or Communities?
How long can the subdomain name be?
After we set up My Domain, will we still be able to log in from https://login.salesforce.com?
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Performance,
Unlimited, Enterprise,
Developer, and
Database.com Editions.
Some topics don't apply to
Database.com.
Can we still use our old Salesforce bookmarks?
Will our Visualforce and content (files) page URLs change?
Can I change or remove my subdomain name?
What is My Domain?
Using My Domain, Salesforce admins can define a subdomain within their Salesforce org. The subdomain name appears in all org URLs and replaces the instance name (such as na30). For example, you can brand your URL by naming the subdomain your company name, https://myCompanyName.my.salesforce.com/
. My Domain is not the same as the custom domain for sites, communities, or portals. The domains are defined separately.
Which Salesforce Editions is My Domain available in?
Performance, Unlimited, Enterprise, Developer, Professional, and Group editions.
What are the advantages of My Domain?
Create a subdomain with My Domain to enable users to single sign-on into your org. You can also customize your login page and use
Salesforce as an identity provider.
My Domain allows you to:
•
Customize the login page with your own branding.
761
My Domain
Set Up and Maintain Your Salesforce Organization My Domain
•
Use Identity features for single sign-on. My Domain is required to:
–
Enable users to single sign-on into a Salesforce org
–
Use a Salesforce org as an identity provider for single sign-on into third-party applications or other Salesforce orgs
•
Preserve deep links (such as https://yourDomain.my.salesforce.com//001/o
) through any future org splits and migrations.
Does My Domain work differently in different Salesforce Editions?
My Domain works the same in most Salesforce editions except for Developer Edition URLs. Developer Edition URLs end with
“-de-ed.my.salesforce.com”, for example, https://yourDomain.de-ed.my.salesforce.com
. URLs in other editions end with “.my.salesforce.com”, for example, https://yourDomain.my.salesforce.com
.
Does My Domain work in sandboxes?
Sandboxes and production orgs are different environments and maintain separate domain name registries. So you can use the same
My Domain name in sandbox. In fact, during a sandbox refresh, the My Domain name of the production org is copied into sandbox.
For example, if the production org name is acme.my.saleforce.com
, the sandbox name is acme--<sandboxName>.csN.my.salesforce.com
.
Test your subdomain in sandbox before deploying it. Look for hard-coded references to instance URLs in Visualforce pages, email templates, and other content.
What are the differences between the redirect policy options?
After you deploy your subdomain with My Domain, you can select a redirect option for users trying to access a page in your org without using your subdomain name.
To see the assigned policy, from Setup, enter
My Domain
in the
Quick Find
box, then select My Domain.
If Redirected to the same page within the domain is selected, users are immediately sent to the new URL, without notification.
If Redirected with a warning to the same page within the domain is selected, users briefly see a warning message before being redirected to the new URL. The warning gives users a chance to change their bookmarks and get used to using the new subdomain
URL. You can’t customize the message.
If Not redirected is selected, the user gets a “page not found” error. Eventually, you want your users to use only subdomain URLs, but it’s a best practice to use Redirected with a warning to the same page within the domain for a short time after you deploy your subdomain so that users can get used to the new URLs.
How does My Domain work with single sign-on?
My Domain is required for setting up single sign-on. For inbound single sign-on requests, the subdomain enables deep linking directly to pages in the org. No changes are required for the identity provider. The Salesforce SAML endpoint ( login.salesforce.com
) continues to work for SAML and OAUTH requests, even if your org deploys My Domain and selects Prevent login from
https://login.salesforce.com in the My Domain Settings.
Note: If you’re using external Chatter groups along with single sign-on for employees, users outside your company are redirected to a SAML identity provider that they can’t access. To get single sign-on to work, migrate external Chatter groups to communities.
Or, from the My Domain settings, do not select
Prevent login from https://login.salesforce.com
. Doing so allows users to continue to log in through login.salesforce.com
.
762
Set Up and Maintain Your Salesforce Organization My Domain
Is My Domain available for the API?
Yes, you can use the Salesforce APIs with your My Domain subdomain.
Is the subdomain for My Domain related to the subdomain for Sites or Communities?
No. The subdomain names you use for Sites and My Domain can be the same or different. We like to refer to Sites and Salesforce
Communities as custom domains and My Domain as subdomains.
How long can the subdomain name be?
Your subdomain name can be up to 40 characters. The protocol ( https://
) and the domain ( my.salesforce.com
) are not included in the limit.
After we set up My Domain, will we still be able to log in from
https://login.salesforce.com
?
Yes, unless your system administrator prevents it. If so, you'll need to log in using your new My Domain URL.
Will we still be able to log in from a URL that includes a Salesforce instance, like
https://
yourInstance
.salesforce.com/
?
Yes, unless your system administrator prevents it. If so, you'll need to log in using your new My Domain URL.
Can we still use our old Salesforce bookmarks?
Yes, if your system administrator allows it. If so, you'll be redirected to the Salesforce page using its new My Domain URL. If your system administrator prevents using old bookmarks, or you see a warning, you should update your bookmarks using the new domain name.
Will our Visualforce and content (files) page URLs change?
URLs for your Visualforce pages contain your new domain name, such as https://<mydomain>--c.<instance>.visual.force.com
.
URLs for your content (files) also contain your new domain name, such as https://<mydomain>--c.<instance>.content.force.com
.
Can I change or remove my subdomain name?
You can’t change the subdomain name that you create with My Domain. And after your subdomain is deployed, you can’t reverse deployment. If you need to change your subdomain name, contact Salesforce Customer Support.
763
Set Up and Maintain Your Salesforce Organization App Launcher
App Launcher
The App Launcher is how users switch between apps. It displays tiles that link to a user’s available
Salesforce, connected (third-party), and on-premises apps. You can determine which apps are available to which users and the order in which the apps appear. You can also make the App
Launcher the default landing page when users first open Salesforce.
The App Launcher is available to all Lightning Experience and Lightning Classic users. Salesforce
Classic users need the Use Identity Features permission and the App Launcher option in their profile set to Visible. Users see only the apps that they are authorized to see according to their profile or permission sets.
In Salesforce Classic, Salesforce admins using the System Administrator profile have access to the
App Launcher. Admins using profiles cloned from the System Administrator profile don’t.
IN THIS SECTION:
Enable the App Launcher with a Profile in Salesforce Classic
Create a profile and assign it to users, so they can access the App Launcher.
Enable the App Launcher with a Permission Set in Salesforce Classic
Create a permission set and assign it to users, so they can access the App Launcher.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
SEE ALSO:
Identity Implementation Guide
Enable the App Launcher with a Profile in Salesforce Classic
Create a profile and assign it to users, so they can access the App Launcher.
Note: These steps work in Salesforce Classic. If you see the App Launcher icon ( ) on the left side of the navigation bar at the top of your screen, you're in Lightning Experience. If not, you're in Salesforce Classic.
In Salesforce Classic, Salesforce admins using the System Administrator profile have access to the
App Launcher. Admins using profiles cloned from the System Administrator profile don’t.
1. From Setup, enter
Profiles
in the
Quick Find
box, then select Profiles.
2. Click New Profile.
3. Select an Existing Profile as a basis for the new profile.
For example, select Standard User.
4. Enter the name of the new profile.
For example,
Standard User Identity
.
5. Click Save.
6. In the detail page for the new profile, click Edit.
7. In Custom App Settings, set the App Launcher to Visible, if it isn’t already.
Under Tab Settings, verify that the App Launcher tab is set to
Default On
.
8. Under Administrative Permissions, select Use Identity Features.
EDITIONS
Available in: Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
764
Set Up and Maintain Your Salesforce Organization
9. Click Save.
10. From Setup, enter
Users
in the
Quick Find
box, then select Users.
11. Click Edit next to each user you want to access the App Launcher.
12. In the user’s Profile field, select the new profile that has “Use Identity Features” enabled.
For example, you might use the
Standard User Identity
profile.
13. Click Save.
When you log in as the selected user, the App Launcher appears in the drop-down app menu.
App Launcher
SEE ALSO:
Enable the App Launcher with a Permission Set in Salesforce Classic
Create a permission set and assign it to users, so they can access the App Launcher.
EDITIONS
Note: These steps work in Salesforce Classic. If you see the App Launcher icon ( ) on the left side of the navigation bar at the top of your screen, you're in Lightning Experience. If not, you're in Salesforce Classic.
1. From Setup, enter
Permission Sets
in the
Quick Find
box, then select Permission
Sets.
2. Click New.
3. Enter a Label for the new permission set.
For example,
Identity Features
.
Available in: Salesforce
Classic
Available in: Enterprise,
Performance, Unlimited, and Developer Editions
4. Optionally, restrict the use of this permission set to a specific User License.
5. Click Save.
6. Click System Permissions.
7. Click Edit.
8. Select Use Identity Features.
9. Click Save.
765
Set Up and Maintain Your Salesforce Organization Configure File Upload and Download Security Settings
10. From Setup, enter
Users
in the
Quick Find
box, then select Users.
11. Click the name of an existing user to whom you want to give access to the App Launcher.
12. In the Permission Set Assignments related list, click Edit Assignments.
13. Add the new permission set you created for identity features to Enabled Permission Sets.
14. Click Save.
When you log in as the selected user, the App Launcher appears in the drop-down app menu.
Note:
Still not seeing the App Launcher? In the profile associated with the user, select Visible for the App Launcher setting.
SEE ALSO:
Configure File Upload and Download Security Settings
To provide more security, control the way some file types are handled during upload and download.
To manage file upload and download settings:
1. From Setup, enter
File Upload and Download Security
in the
Quick Find box, then select File Upload and Download Security.
2. Click Edit.
3. To prevent users from uploading files that can pose a security risk, select
Don't allow
HTML uploads as attachments or document records
.
This setting blocks the upload of these MIME file types:
.html
,
.htt
,
.mht
,
.svg
,
.swf
,
.thtml
, and
.xhtml
.
Warning: Keep the following in mind when selecting this option:
•
If your organization uses the partner portal to give your partner users access to
Salesforce, we don't recommend enabling this setting. Enabling this setting prevents your organization from customizing the appearance of your partner portal.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
USER PERMISSIONS
To configure file upload and download settings:
•
Customize Application
766
Set Up and Maintain Your Salesforce Organization Certificates and Keys
•
HTML attachments are not permitted on solutions, regardless of whether this security setting is enabled. In addition, this setting does not affect attachments on email templates; HTML attachments on email templates are always permitted.
•
After this setting is enabled, previously-uploaded HTML documents and attachments are unaffected. However, when users attempt to view an HTML attachment or document, their browser first prompts them to open the file in the browser, save it to their computer, or cancel the action.
4. Set download behavior for each file type:
a. Download (recommended): The file, regardless of file type, is always downloaded.
b. Execute in Browser: The file, regardless of file type, is displayed and executed automatically when accessed in a browser or through an HTTP request.
c. Hybrid: Salesforce Files are downloaded. Attachments and documents execute in the browser.
5. Click Save.
Certificates and Keys
Salesforce certificates and key pairs are used for signatures that verify a request is coming from your organization. They are used for authenticated SSL communications with an external web site, or when using your organization as an Identity Provider. You only need to generate a Salesforce certificate and key pair if you're working with an external website that wants verification that a request is coming from a Salesforce organization.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
You can export all your certificates and private keys into a keystore for storage or import certificates and keys from a keystore. This allows you to move keys from one organization to another. The exported file is in the Java Keystore (JKS) format, and the imported file must also be in the JKS format. For more information about the JKS format, see Oracle's Java KeyStore documentation .
USER PERMISSIONS
API Client Certificate
To create, edit, and manage certificates:
•
Customize Application
The API client certificate is used by workflow outbound messages, the AJAX proxy, and delegated authentication HTTPS callouts. For security reasons, the API client certificate should be known only to your org.
Choose an API client certificate based on the remote endpoint you connect to. Some endpoint servers require a certificate chain that is trusted by a certificate authority; others are fine with directly trusting a self-signed certificate.
IN THIS SECTION:
Generate a Self-Signed Certificate
Generate a certificate signed by Salesforce to show that communications purporting to come from your organization are really coming from there.
Generate a Certificate Signed by a Certificate Authority
A certificate authority-signed (CA-signed) certificate can be a more authoritative way to prove that your org’s data communications are genuine. You can generate this type of certificate and upload it to Salesforce.
Set Up a Mutual Authentication Certificate
To prevent security from being compromised by simple impersonation, you can require clients and servers to prove their identity to each other with a mutual authentication certificate.
767
Set Up and Maintain Your Salesforce Organization Certificates and Keys
Configure Your API Client to Use Mutual Authentication
Enforce SSL/TLS mutual authentication.
Encrypted custom fields, such as
Social Security Number
or
Credit Card Number
, are encrypted with a master encryption key. This key is automatically assigned when you select fields to encrypt. You manage your own master key according to your organization’s security and regulatory needs.
Generate a Self-Signed Certificate
Generate a certificate signed by Salesforce to show that communications purporting to come from your organization are really coming from there.
1. From Setup, search for
Certificate and Key Management
in the
Quick Find box.
2. Select Create Self-Signed Certificate.
3. Enter a descriptive label for the Salesforce certificate.
This name is used primarily by administrators when viewing certificates.
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
USER PERMISSIONS
4. Enter a unique name. You can use the name that’s automatically populated based on the certificate label you enter.
This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. Use the unique name when referring to the certificate using the Force.com web services API or Apex.
To create, edit, and manage certificates:
•
Customize Application
5. Select a key size for your generated certificate and keys.
Certificates with 2048-bit keys last one year and are faster than certificates with 4096-bit keys. Certificates with 4096-bit keys last two years.
Note: After you save a Salesforce certificate, you can’t change its type or key size.
6. Click Save.
Downloaded self-signed certificates have
.crt
extensions.
After you successfully save a Salesforce certificate, the certificate and corresponding keys are automatically generated.
You can have a maximum of 50 certificates.
SEE ALSO:
Generate a Certificate Signed by a Certificate Authority
768
Set Up and Maintain Your Salesforce Organization Certificates and Keys
Generate a Certificate Signed by a Certificate Authority
A certificate authority-signed (CA-signed) certificate can be a more authoritative way to prove that your org’s data communications are genuine. You can generate this type of certificate and upload it to Salesforce.
EDITIONS
1. From Setup, enter
Certificate and Key Management
in the
Quick Find
box, then select Certificate and Key Management.
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
2. Select Create CA-Signed Certificate.
3. Enter a descriptive label for the Salesforce certificate.
This name is used primarily by administrators when viewing certificates.
USER PERMISSIONS
4. Enter a unique name. You can accept the name that’s populated based on the certificate label you enter.
To create, edit, and manage certificates:
•
Customize Application
This name can contain only underscores and alphanumeric characters, and must be unique in your org. It must begin with a letter, not include spaces, not end with an underscore, and not contain two consecutive underscores. Use the unique name when referring to the certificate using the Force.com web services API or Apex.
5. Select a key size for your certificate and keys.
We recommend that you use the default key size of 2048 for security reasons. Selecting 2048 generates a certificate using 2048-bit keys. Selecting 4096 generates a certificate using 4096-bit keys.
Note: After you save a Salesforce certificate, you can’t change its type or key size.
6. Enter the following information.
These fields are combined to generate a unique certificate.
Field
Common Name
Email Address
Company
Department
City
State
Country Code
Description
The fully qualified domain name of the company requesting the signed certificate, generally of the form http://www.mycompany.com
.
The email address associated with this certificate.
Either the legal name of your company or your legal name.
The branch of your company using the certificate, such as marketing or accounting.
The city where the company resides.
The state where the company resides.
A two-letter code indicating the country where the company resides. For the United States, the value is
US
.
7. Click Save.
After you save a Salesforce certificate, the certificate and corresponding keys are automatically generated.
8. Find your new certificate from the certificates list, then click Download Certificate Signing Request.
Downloaded certificate signing requests have
.csr
extensions.
769
Set Up and Maintain Your Salesforce Organization Certificates and Keys
9. Send the certificate request to the certificate authority of your choice.
10. After the certificate authority sends back the signed certificate, go back to
Certificate and Key Management
, click the name of the certificate, then click Upload Signed Certificate.
The CA-signed certificate must match the certificate created in Salesforce. If you try to upload a different CA-signed certificate, the upload fails.
11. To complete the upload process, click Save.
After you upload the CA-signed certificate, the status of the certificate is changed to Active and you can use it.
Tip:
If you need to edit a certificate that you’ve uploaded, upload it again; Published site domains are republished if they have at least one Force.com site or community. The expiration date of the certificate record is updated to the expiration date of the newly uploaded certificate.
You can have up to 50 certificates.
Set Up a Mutual Authentication Certificate
To prevent security from being compromised by simple impersonation, you can require clients and servers to prove their identity to each other with a mutual authentication certificate.
EDITIONS
1. On the Certificate and Key Management page, click Upload Mutual Authentication Certificate.
Note: If you don’t see this option on the Certificate and Key Management page, contact
Salesforce to enable the feature.
Available in: both Salesforce
Classic and Lightning
Experience
2. Give your certificate a label and name and click Choose File to locate the certificate.
3. Click Save to finish the upload process.
4. Enable the “Enforce SSL/TLS Mutual Authentication” user permission for an “API Only” user.
This “API Only” user configures the API client to connect on port 8443 to present the signed client certificate.
Available in: Enterprise,
Performance, Personal,
Unlimited, Developer, and
Database.com Editions
USER PERMISSIONS
If you are using a certificate chain, the client certificate must include any intermediate certificates in the chain when contacting port 8443.
To create, edit, and manage certificates:
•
Customize Application
A certificate chain is a hierarchical order of certificates where one certificate issues and signs another certificate lower in the hierarchy. Upload a certificate chain as a single PEM-encoded CA-signed certificate representing the concatenated chain of certificates. The uploaded certificate chain must include the intermediate certificates in the following order.
•
Start with the server or client certificate and then add its signing certificate.
•
If more than one intermediate certificate exists between the server or client certificate and the root, add each certificate as the one that signed the previous certificate.
•
The root certificate is optional, and generally should not be included.
SEE ALSO:
Configure Your API Client to Use Mutual Authentication
770
Set Up and Maintain Your Salesforce Organization Certificates and Keys
Configure Your API Client to Use Mutual Authentication
Enforce SSL/TLS mutual authentication.
1. After you've set up mutual authentication, log in to the Salesforce service using port 8443.
Include your credentials and your signed certificate information.
For example, your configuration using cURL
may look something like this, where “@login.txt” contains the login Soap message with your credentials and “fullcert.pem:xxxxxx” is your certificate information:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in: Enterprise,
Performance, Personal,
Unlimited, Developer, and
Database.com Editions
USER PERMISSIONS
To create, edit, and manage certificates:
•
Customize Application
To Enforce mutual authentication on port 8443 for standard SSL/TLS connections:
(Assign to users with the Api
Only User permission.)
•
Enforce SSL/TLS Mutual
Authentication
To access Salesforce only through a Salesforce API:
•
Api Only User curl -k https://login.salesforce.com:8443/services/Soap/u/31.0 -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: login" -d @login.txt -v -E fullcert.pem:xxxxxx
2. Once a session ID is returned from your call, you can perform other actions, such as queries. For example: curl -k https://yourInstance.salesforce.com:8443/services/Soap/u/31.0 -H "Content-Type: text/xml; charset=UTF-8" -H "SOAPAction: example" -d @accountQuery.xml -v -E fullcert.pem:xxxxxx where @accountQuery.xml is the file name containing the query Soap message with session ID from the login response.
SEE ALSO:
Set Up a Mutual Authentication Certificate
771
Set Up and Maintain Your Salesforce Organization Certificates and Keys
Manage Master Encryption Keys
Encrypted custom fields, such as
Social Security Number
or
Credit Card Number
, are encrypted with a master encryption key. This key is automatically assigned when you select fields to encrypt. You manage your own master key according to your organization’s security and regulatory needs.
With master encryption keys, you can:
EDITIONS
Available in: both Salesforce
Classic and Lightning
Experience
Available in all editions
•
Archive the existing key and create a new key.
•
Export an existing key after it's been archived.
•
Delete an existing key.
•
Import an existing key after it's been deleted.
USER PERMISSIONS
To create, edit, and manage certificates:
•
Customize Application
Archiving and Creating New Keys
To archive your current key and create a new key , click Archive Current Key and Create New
Key on the
Certificate and Key Management
Setup page. A new key is generated, assigned the next sequential number, and activated. All new data is encrypted using the new key.
Existing data continues to use the archived key until the data is modified and saved. Then data is encrypted using the new key.
After you archive a key, you can export or delete it.
Exporting Keys
You can export your keys to a back-up location for safe keeping. It’s a good idea to export a copy of any key before deleting it.
Exporting creates a text file with the encrypted key, so you can import the key back into your organization later.
Deleting Keys
Don't delete a key unless you're absolutely certain no data is currently encrypted using the key. After you delete a key, any data encrypted with that key can no longer be accessed.
Important: Export and delete keys with care. If your key is destroyed, you must reimport it to access your data. You are solely responsible for making sure your data and keys are backed up and stored in a safe place. Salesforce cannot help you with deleted, destroyed or misplaced keys.
Importing Keys
If you have data associated with a deleted key, you can import an exported key back into your organization. Any data that was not accessible becomes accessible again.
Click
Import
next to the key you want to import.
Note:
This page is about Classic Encryption, not Shield Platform Encryption. What's the difference?
SEE ALSO:
772
Shkarko
Lidhja publike u përditësua
Lidhja publike për bisedën tuaj është përditësuar. You may view and manage your chat links after registration here.
Lidhja publike e dokumentit
Reklamë
