Skip to main content

Custom SAML single sign-on

Gal Hoch avatar
Written by Gal Hoch
Updated over 2 weeks ago

Overview

If your preferred identity provider doesn't have a pre-built integration with Lusha, a custom SAML (Security Assertion Markup Language) connection can be used to establish the link between the two systems.

SAML is a standard for exchanging authentication and authorization data.

Please Note: Only users with admin or manager roles can set up a custom SAML connection.


Configure your identity provider

To set up the custom SAML connection, you will need the following information:

Step 1 - Gather Data

​1. SSO post-backup URL: https://dashboard-services.lusha.com/v2/sso-saml (Also known as the Assertion Consumer Service URL).

3. Considerations: Your identity provider must ensure that a user is both authenticated and authorized before sending an assertion. If a user is not authorized, assertions should not be sent, and it is recommended that your identity provider redirects them to an HTTP 403 page.

Step 2: Configure Attributes in IDP Response

The following attributes should be included in the IDP response:

  • NameID (Required)

  • Email Attribute (Required)

  • First Name Attribute (Required)

  • Last Name Attribute (Required)

NameID (Required)

<saml:Subject> <saml2:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"><email_address></saml2:NameID> </saml:Subject>

Email Attribute (Required)

<saml:Attribute Name="email" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">testuser@youremail.com </saml:AttributeValue> </saml:Attribute>

First Name Attribute (Required)

<saml:Attribute Name="firstName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">FirstName </saml:AttributeValue> </saml:Attribute>

Last Name Attribute (Required)

<saml:Attribute Name="lastName" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">LastName </saml:AttributeValue> </saml:Attribute>

Step 3: Certificates

Public Certificate: Lusha requires that the SAML response be signed, and you will need to paste a valid X.509 .pem Certificate to verify your identity. This certificate is different from your SSL certificate.


Enable SAML SSO in Lusha

Once you have configured your identity provider, you can enable SAML in Lusha.

To do this, copy the XML file, go to Account Settings, paste the file under the "Custom SAML 2.0" section, and click Connect.

💡Note: If you want to connect Azure or Okta to Lusha, refer to the "Set up SSO (single sign-on)" article.


Google SAML Configuration

  1. Go to the Google Admin console.

  2. On the left side bar, go to AppsWeb and mobile apps.

  3. Click the Add app dropdown → Add custom SAML app.

4. Under App details, name the app (for example: “Lusha saml”). The description is optional.

5. Click Continue.

6. Google identity provider details (IDP) - Download the IDP metadata we will need later.

7. Click Continue.

8. Enter Service provider details - ACS URL and Entity ID https://dashboard-services.lusha.com/v2/sso-saml

9. Change Name ID format to: EMAIL

10. Click Continue.

11. Attribute mapping:

  • Click Add mapping to add value for SAML response (click 3 times)

  • Use the following attributes and values:

Google directory attribute

App attribute

Primary email

email

First name

firstName

Last name

lastName

12. Click Finish.

13. You should then be able to see the app on the Web and mobile apps page.

14. Click the Lusha app.

15. Click the User Access box (Click the box itself - not “View details”/”Learn more”):

16. Change service status to ON.

17. Click Save.

18. Go to Account Settings on your Lusha account and enable SAML by clicking Custom SAML 2.0.

19. Copy the entire content of the IDP file you downloaded earlier.

20. Paste it into the custom SAML box.

21. Click Connect.

22. Go back to the Google Admin console → Apps → Web and mobile apps → Lusha → User Access - View Details.

23. Grant access to all users in your Lusha account.

24. Done! All users should be able to connect via SSO 🚀

Did this answer your question?