Integrate single sign-on (SSO)

Single sign-on (SSO) in NationBuilder allows you to integrate your nation as a service provider with your SAML 2.0 identity provider. This can expand or replace the normal methods of signing into a nation. It is only available to nations on the Enterprise or Network plan. Your permission set must have access to the Settings section of the control panel and you must have the "manage authentication modes" permission to use these instructions. 


Set up a custom SAML SSO

1. Go to Settings > Auth

SAML SSO added in NationBuilder control panel settings section 

If you do not see the Auth option in Settings, contact your Enterprise Account Manager to have single sign-on enabled. Your nation must be on the Enterprise or Network plan to use this feature.

2. Click on +New provider.

3. Enter the provider name.

NationBuilder SAML SSO provider name and slug fields

4. The slug for the provider will be generated automatically based on the name entered. Any consecutive series of characters that are not English alphanumeric characters, underscores, or dashes will be replaced with a single underscore in the automatically generated slug. You can edit the slug, which can include English alphanumeric characters, underscores, or dashes.

5. Once the name and slug are created, information that needs to be added to your identity provider's control panel will display on the right side.

NationBuilder entity ID, ACS, and SSO URLs

Note that your identity provider's slug is included in these credentials. If changes are made to the provider slug field, these credentials will be updated once the cursor is moved out of the slug field.

6. Log into your identity provider's control panel and add the NationBuilder application details as described above. The entity ID, assertion consumer service URL, and single sign-out endpoint are unique to each identity provider within a nation and should be copied directly from your nation's control panel. 

7. Add the identity provider to NationBuilder. 

Identity provider details needed in NationBuilder 

The unique ID, single sign-on endpoint, and X.509.pem certificate fields are required.

Be sure to include the entire X.509.pem certificate. This means that the information is enclosed between "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----" The lines beginning and ending the certificate must be included for the certificate to be valid.

8. You have the option of giving new users access to your control panel. If you check this box, you then need to choose a permission set for new users.

When the box is unchecked, new users signing in through your identity provider will only be able to access areas of your public website; they will not have access to your control panel. Since this option provides the same level of access to your control panel for all new users, you also have the option of mapping IDs within profiles, and specifying different permission sets for each user. 

9. Click the Save button to save your identity provider.


Display the new sign-on option

You will need to update your theme to display your new authentication provider on your website. The following code example will display the login button on your page.  Simply replace slug with the correct slug assigned to your provider in the control panel.

{% if request.authentication_modes.slug %}
<a class="sign-in-button" title="Sign in with SSO" href="{{ request.authentication_modes.slug.sign_in_url }}">SSO Provider</a>
{% endif %}


Edit identity mapping in a profile

Once an identity provider is created in the Settings section, profiles in your people database will include a new section to view and edit identity mapping.

 

identity mapping within a profile

The "Identity mappings" section of a profile will include space to insert a unique identifier for each provider created in the Settings section. This will allow you to complete the integration process if you are not using just in time provisioning. Having access to a profile's identity mappings also allows you to specify different permission sets for people, rather than providing the same permission set for all control panel users logging in with the identity provider. 

Please note that a user must already exist in your identity provider. Inserting a unique ID in a NationBuilder profile will not create that ID in your SAML SSO provider. 


Import identity mappings

Once an identity provider is created in the Settings section of the control panel, identity mappings can be added to profiles by importing them in a one-time import or a voter import.

The identity mapping connects a profile to an identity provider, but it is not a unique identifier for a NationBuilder profile. This means that when you import identity mappings, you must import an additional unique ID.

If you are using the email attribute as your name identifier format in your identity provider, you could duplicate the email address field in your CSV and then map the email address field twice: first as the signup email address, then within the SSO Identity Mappings category, to the field labeled for a particular identity provider.


Filter by identity mappings

Once an identity provider is created in the Settings section of the control panel, a new filter category will appear in the People section. Select "SSO identity mappings," then select "External user identifier." A row will be added to your filter criteria. You will have to select a particular identity provider to search within. Then, you can search whether the external user identifier:

  • is [text field to enter criteria]
  • contains [text field to enter criteria]
  • does not contain [text field to enter criteria]
  • starts with [text field to enter criteria]
  • ends with [text field to enter criteria]
  • exists [select yes or no: "yes" to search for profiles that contain an identity mapping for that provider; "no" to search for profiles that do not contain an identity mapping for that provider]

Use SAML with NationBuilder SSO

How to manage control panel users

If you’re unclear on how this feature works, please ask a question. If you would like to see changes to this feature, please submit a suggestion.