Administrator

How do I set up SAML authentication for my domain?

  • Updated:
    info_outline
    Created:

SAML authentication can be used to establish a secure single sign-on (SSO) connection between Buzz and an external identity provider (IdP). 

Terminology

Term Definition
Identity provider (IdP) The IdP is used to identify users based on credentials. The IdP provides the login screen interface and presents information about the authenticated user to the SP after successful authentication.

Examples: Google Apps, ADFS, PowerSchool
Metadata Information about the SP or IdP, often referred to as the SP metadata or IdP metadata. This metadata should be provided as XML and is used by the SP and IdP to inform each about the settings and URLs of the other.
Security Assertion Markup Language (SAML) An XML-based, open-standard data format for exchanging authentication and authorization data between parties, in particular, between an IdP and an SP.
Service provider (SP) An SP is a website providing information and other tools to the authenticated user. For these instructions, Buzz is the SP.
Single sign-on (SSO) An authentication service that permits a user to use one set of login credentials (e.g., username and password) to access multiple applications.

How does SAML SSO work?

SAML in Buzz is initiated by a user. This is the basic process:

  1. A user selects "Login" from the Buzz login webpage. 
  2. Buzz generates SAML request and redirects the webpage to the IdP.
  3. IdP receives the SAML request and verifies user. If the user is not already authenticated into the IdP, then the user will be prompted to authenticate.
  4. IdP sends SAML response to Buzz and redirects the webpage to Buzz. 
    • NOTE: Buzz requires that the SAML response contains the following attributes:
      • Assertion
      • NameId (must match the user's Buzz username)
      • Response
      • SessionIndex
      • Subject
  5. Buzz receives and verifies SAML response.
  6. Buzz grants user access.

How to set up your SAML authentication?

To set up your SAML authentication:

  • Access the SP (Buzz) metadata file using the following URL (replace the bolded text with your userspace name):
    • https://api.agilixbuzz.com/SAML/[INSERT USERSPACE]/metadata.xml
  • Go to your IdP and create a new SAML configuration. Each IdP is different in how to configure and setup a new SAML configuration and you may need to consult an expert research it on the internet. 
  • The IdP will ask to either (a) enter, (b) upload, (c) copy and paste, or (d) provide the URL to the SP metadata (see step 1).
    • When you can, choose to enter the URL as it could dynamically pull the information into the IdP from the SP, reducing the need for future changes.
  • Once configured and available in your IdP, download the IdP metadata file, and complete the SAML steps in this article:
  • Attempt to login to Buzz using your new SAML integration.

How to upgrade your SAML implementation

On October 29, 2020, we updated our SAML implementation. Domains using SAML authentication that was set up prior to that date should upgrade their implementation using the following steps.

In order to upgrade your SAML using the following steps, you must sign into the Buzz Admin tool as a domain administrator.

1. Download the current SAML metadata file

  1. Sign into the Buzz Admin tool as a domain administrator.
  2. Click Resources tab.
  3. Choose -saml in the Folder dropdown, and click idp-meta.xml link.
  1. Click the Download button in the upper-right corner.
    • Be sure to take note of the downloaded file’s location, so you can find it.

2. Create a sandbox domain to test the new SAML configuration

  1. Open the Subdomains tab in the Admin tool.  
  2. Create a new "sandbox" subdomain for testing the new SAML configuration.
  3. Switch to the sandbox subdomain, and open Domain settings.
  4. In the Authentication card, choose SAML as the authentication type
  5. Click Add Identity Provider, and in the popup, upload the idp-meta.xml file you downloaded.
  6. Click Done, and Save the configuration.
  7. Create a test user in the sandbox subdomain with a username that matches one you can authenticate with SAML.

3. Test your sandbox domain

  1. Enter the URL for your sandbox domain.
  2. Click the Login button which should redirect you to your Identity provider (IdP).
  3. Enter the credentials that match the test user you created in step 7.
  4. This should redirect you back to Buzz as that test user, verifying that your SAML configuration is working correctly.
  5. Click Logout to logout of Buzz.

4. Update your production domain

Once you've verified the safe setup of SAML authentication in your sandbox domain, repeat the process for configuring SAML in your production domain:

  1. In your production domain, open Domain settings.
  2. On the Authentication, choose SAML as the Type.
  3. Click Add Identity Provider, and in the popup, upload the idp-meta.xml file that you uploaded to your sandbox domain.
  4. Click Done, and Save the configuration.
forum

Have a question or feedback? Let us know over in Discussions!