SalesForce

# Setting up MIRACL Trust SSO as an Identity Provider Within Salesforce

These instructions are up-to-date at the time of writing, but you should refer back to the Salesforce documentation on SAML settings for SSO to check for any changes. We cannot guarantee the accuracy of our SP-specific guidance.

# 1. Create Self-Signed Certificate

1. In the Administer panel under ‘Security Controls’ click on Certificate and Key Management, then click on Create Self-Signed Certificate:

   

2. Enter a Label and Unique Name and select a key size of 4096:

   

3. Now click on ‘Download Certificate’ and you have it ready to be deployed when you create your SSO service.

   

# 2. Create SSO Settings

1. Under ‘Administer’ click on Single Sign-On Settings under ‘Security Controls’:

   

2. Click on ‘New from Metadata File’:

   

3. Browse to pick up the metadata file which you previously downloaded from MIRACL Trust SSO:

   

   The metadata can be downloaded from http://<yourssoip>/metadata. Note that, for a production setup, if you manually download your IdP metadata file, the validUntil date at the top of the file needs to be edited to an appropriate date (it defaults to 48hrs from the current date).

4. Click ‘Create’:

   

5. Enter the details for your SSO setup:

   

   • The Issuer URL is the path to your IdP metadata file (http://<yourssoip>/metadata).
   • Set SAML Identity Type to ‘Assertion contains the Federation ID from the User object’.
   • Set SAML Identity Location to ‘Identity is in an Attribute element’ (urn:oid automatically set?).
   • Identity Provider Login URL should match that as provided in your SSO dashboard.
   • Click ‘Browse’ to pick up the Identity Provider Certificate, which is found in the ___ section of your SSO dashboard.
   • Upload the downloaded self-signed certificate to Assertion Decryption Certificate (this is the certificate which you downloaded in Step 1 of this guide).

   

6. Save and close.

# 3. Set Up Your Domain

1. In the Administer panel, click on Domain Management > My Dosso:

   

2. You are shown what your allocated domain name is. Click login to test it, followed by Deploy to Users:

   

3. Then you are presented with a confirmation message. Click ‘OK’ to deploy.

# 4. Enable SSO

1. Return to Single Sign-On Settings and click edit:

   

2. Tick SAML Enabled and save:

   

3. Return to Domain Management > My Domain and click Edit in the Authentication Configuration section:

   

4. In the config screen tick your SAML service and save:

   

# 5. Access SSO URL

1. You should now be able to visit the url for your configured SSO:

   

2. Clicking on Login with a Different Username should then give the option to login with your newly-configured service:

   

# 6. Add Federation ID to Associated User From Your Directory

1. In Administer go to Manage Users > Users and click to edit the user associated with SSO:

   

2. Scroll down to the Single Sign-On Information and add the email address from your user directory which is passed to Salesforce:

   

# 7. Download the Salesforce Metadata File

1. Return to Security Controls > Single Sign-On Settings and click on the name of your service:

   

2. Click to download the Salesforce SSO metadata:

   

3. Save the file as metadata.xml.

# Configuring Salesforce as a Service Provider Profile in MIRACL Trust SSO

1. Edit /etc/miracl-sso/service_providers/salesforce.yaml:

   sp:
     salesforce:
       description: Salesforce Customer Relationship Management (CRM)
       name: My CRM
       relay_state: /
       login_url: https://example.my.salesforce.com
       logout_url: https://example.lightning.force.com/secur/logout.jsp
       metadata: >-
         <!-- insert downloaded SP metadata here -->
       sign_response: true
       sign_assertion: true
       encrypt_assertion: true
       authorize:
       - - email: ^[^@]+@example.com
   

2. Note that the name under which the SP is registered in the sp section is used to create your IdP-initiated login url, i.e. https://<yourssoip>/login/salesforce.

3. Note that login_url and logout_url should be edited as per the url you are issued by the Salesforce admin console.

4. In the metadata field you need to enter the downloaded metadata, as per the final step in the previous section.

   If using JSON format, the downloaded metadata file must be converted to a single line and the " characters need to be escaped with \ to meet the json structure requirements. This can be achieved by running the following command on the downloaded metadata.xml file:

   echo -e "\n"$(cat metadata.xml | tr -d '\n' | sed -E 's/"/\\"/g')"\n"
   

   The contents are output in the terminal in a format that can be pasted into the metadata field of a JSON file.

5. In the authorize subsection, you can control what users are allowed to attempt login by following one or both of the below steps:

   • Call up an LDAP setup from an ldap.yaml file stored in /etc/miracl-sso/integrations.

   • Configure a regex list of email addresses/domains. The above config shows an example of how you would use email: ^[^@]+@example.com$ to only allow users from a certain email domain to login.

     Note that if this is not set correctly, you receive ‘unauthorized user’ messages.

     For more detailed info on using LDAP, API and/or regex to control authorized users, please see the authorization menu section.

6. Save and close the file.

7. In your /etc/miracl-sso/config.yaml file make sure you add salesforce.yaml to the list of ‘includes’:

   includes:
     - core.yaml
   
   # service providers
     - service_providers/salesforce.yaml
   

8. As always after config changes, restart the server.

9. Now your service is configured, you can visit https://<yourssoip>/login/salesforce or https://<yourssoip>/services to login to the service using IdP-initiated login, or visit the Salesforce login page and SP-initiated login are triggered automatically.

10. You are able to login using the in-browser PIN pad or with the MIRACL Trust app. When logging in to your SSO service for the first time you are asked to register an email address so as to confirm your identity and register you as a user.