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 help@nationbuilder.com 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 certificate fields are required. Be sure to include the entire X.509 certificate. 

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 in 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. 


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.

Not finding what you're looking for? Browse the Settings FAQs