Salesforce As SAML SSO Identity Provider
Last Updated -
- Overview: Agent Single Sign-on (SSO) via JWT and SAML 2.0
- Agent SSO via JWT Setup Details
- Agent SSO via SAML 2.0 Setup Details
OverviewThis article is about establishing Salesforce as a SAML based Identity Provider for Single Sign-On with your Desk.com site.
Key Abbreviations and Acronyms
- ACS - Assertion Consumer Service
- IdP - Identity Provider (Saleforce and your Saleforce Organization are providing identities)
- SAML - Security Assertion Markup Language
- SP - Service Provider (your site at Desk.com)
- SSO - Single Sign-On
Desk.com Salesforce Org Identity Provider Certificate
- Salesforce certificates and key pairs are used for signatures that verify a request coming from your organization.
- To enable this in your Salesforce Org, go to: Administer > Security Controls > Identity Provider > Identity Provider Setup.
- If one has not yet been created, set up a Domain name.
- Click 'Enable Identity Provider.'
- If you need to set up a new self signed certificate click 'Edit.'
- In the Identity Provider Setup window, click 'Save.'
Note: Do not create a certificate if it already exists.
For further information on certificates and keys, go to the About Salesforce Certificates and Keys page.
Create a Salesforce Connected App
In order to use Salesforce as a SAML Identity Provider for your Desk.com site you need to create a Connected App (SP) for it in the Salesforce Organization Admin panel.
- From the left hand side navigation go to: Build > Create > Apps and click 'New' in the Connected Apps section of the Salesforce organization. This will take you to the New Connected App page.
The example site below named "example" has been created at https://example.desk.com. The two pertinent sub-groups are Basic Information and Web App Settings.
- Fill in the required fields and check the appropriate boxes (see, below).
- Select the required settings from the dropdown menus (see, below).
- Connected App Name: The common/friendly name of your application
- API Name: <your desk site name>
- Contact Email: Your contact email address
Web App Settings
- Start URL: https://<your desk site name>.desk.com/web/agent
- Enable SAML (selected)
- Entity Id: <your desk site name>
- ACS URL: https://<your desk site name>.desk.com/auth/saml/acs
- Subject Type: (choose Federation ID)
- Name ID Format: choose: urn:oasis:name:tc:SAML:1.1:nameid-format:emailAddress
- Issuer: https://<your saleforce org id>.my.salesforce.com (Salesforce automatically sets this value)
Important: The Subject Type "Federation ID" is a unique attribute that is set for each user you add to your Salesforce Organization. The Federation ID is set when creating or updating a user and is intended to be the link between users in each service provider that is supported by the identity provider. In this case, the Federation ID must be the email address that is associated with each agent in your Desk Team panel; your Desk site is the service provider, and your Salesforce Organization is the identity provider. This is discussed in greater detail in the latter half of this article, under the section Linking Agents in Desk.com to the Salesforce SAML Identity Provider.
- Now click 'Save' for the New Connected App form. The saved application will now present some basic information about your application.
- Click 'Manage' to view a full listing of information about the application.
- To retrieve the x509 certificate, go to: Administer > Security Controls > Identity Provider > Identity Provider Setup.
- Click 'Download Certificate,' which contains the x509 certificate that is used to encrypt login information between Desk and Salesforce during the single sign on sequence.
openssl x509 -sha1 -fingerprint -in ~/Downloads/SelfSignedCert_07Aug2015_191906.crt
The output from "openssl" will look like the example below. The hexadecimal value after "SHA1 Fingerprint=" is the certificate fingerprint. You will need the certificate fingerprint for the SAML setup in the Desk admin panel for your site.
SHA1 Fingerprint=3F:27:BD:3D:14:01:DC:5B:1E:18:09:75:B7:E7:2C:AE:91:3F:40:EC -----BEGIN CERTIFICATE----- MIIEazCCA1OgAwIBAgIOAUxdpijZAAAAAAwKxKkwDQYJKoZIhvcNAQEFBQAwfDEU ... 7y/cBjo/PmqCntrOJKAFGBlErYKPeFP7FeC6Iv0Rdw== -----END CERTIFICATE-----
Desk.com Admin Settings for SAML Single Sign-On
To access the Single Sign-On settings in the Admin panel for your Desk.com site, go to: Admin > Settings > Single Sign-On. For our example site the URL to this section of the panel is https://example.desk.com/admin/settings/security.
Paste the hexadecimal value into Certificate fingerprint window and click 'Save.'
Desk SAML SSO Settings
- Authentication Service Name - Friendly name displayed in the Desk login form when "Also allow Desk Authentication" is enabled.
- Remote login URL - "Issuer" in the Salesforce Connected App's Web App Settings
- Remote logout URL (Optional) - leave blank
- Certificate fingerprint - the value output from the openssl command
- Also allow Desk Authentication (checked) - we encourage this to stay enabled until SAML SSO is configured properly
Login form when Desk Authentication is enabled
The Desk login form will be displayed when Desk Authentication is enabled and the Authentication Service Name will be linked to the Salesforce Identity Provider based login form as in the example.
Linking Agents in Desk.com to the Salesforce SAML Identity Provider
- To see the index of users in your Salesforce Organization, go to: Administer > Manage Users > Users .
- To create a new user click the 'New User' button in the All Users index.
- Salesforce provides identities for all the users that are established in your Organization; therefore, choose Required Information values such as First Name, Last Name, Alias, Email, as well as the Role permissions and Profile that fit your organization's needs.
- The section Single Sign-On Information is where you set the Federation ID. It is recommended that you set the Federation ID value with the user's email address and associating the Federation ID with the SAML name identifier. It is the email address in the Federation ID that links users in Salesforce to agents in your Desk.com site. There is a one-to-one relation between the user's email address as a Federation ID in Salesforce and the corresponding Desk agent with the same email address.
- Click 'Save' at the bottom of the page to complete new user creation.