Integrating Birst with SAML

Birst can integrate with Security Assertion Markup Language (SAML) 2.0 for Identity Provider (IdP) initiated access.  Birst supports using SAML for authentication, including passing session-scoped parameters and just- in-time user provisioning. Birst supports SAML providers such as Okta, OneLogin, date for JIRAPing Identity, and Site Minder.

Note: You can only use an entity ID with one endpoint. For instance, one service provider in Infor Ming.le will map to a specific Birst server (https://app2102.bws.birst.com).

If you want to point to another Birst server such as ( https://app2103.bws.birst.com), you will need to create a new service provider in Infor Ming.le that references another SAML configuration in Birst.

Note: Specifying the birst.spaceid parameter in the SAML response will limit the users access to the one specified space. If you want to direct a user to the Birst home page to access multiple Birst Spaces via SAML SSO, then remove the birst.spaceId parameter from the SAML response.

• Implementation Notes
• Prior to Configuring SAML
• To configure a SAML IdP in Birst
• Example of Using SAML with Single Sign-On (SSO)
• User Provisioning - see User Provisioning with SAML

Implementation Notes

• SAML 2.0 is supported.
• To authenticate a user to access the Home page, only the subject name identifier is needed in the SAML payload. The subject name identifier is the user name configured in Birst.
• If you want the user to sign on to a particular space or module, use the Birst SSO parameters. See the "Example of Using SAML with Single Sign-On (SSO)" section below.
• If you want to provision user accounts, see User Provisioning with SAML. Note: Birst does not support custom relay state. Users should not set the relay state in IDP. For IDP initiated SAML SSO, you should set the "Default Relay State" parameter to blank. This should return an empty RelayState in the SAML response to Birst. Otherwise, the SAML SSO will likely fail.
• Birst also supports SAML provided by Active Directory Federation Services (ADFS).
• The SAML Single Sign-On feature also supports Service Provider initiated flow. This requires configuration setup on both Birst as the Service Provider and on the IdP.
• Space-specific SSO parameters for embedding dashboards can be passed dynamically as part of a service-provider-initiated SAML URL. Parameters can be controlled through the URL itself. This allows the same IdP setup to be used for different spaces or for different dashboards without any explicit configuration change on the IdP. Example URL:
  https://hostname/SAMLSSO/Services.aspx?birst.idpid=idp _ID&birst.spaceId=space_ID&birst.module=module&other_SSO_parameters
• SAML SSO authentication supports SHA-256 as the signing hash algorithm.
• Tip for iOS: If the Birst account has more than one active SAML configuration, Mobile SSO for iOS devices will not work. Account Administrators can disable SAML configurations from the Account Settings page.

Prior to Configuring SAML

SAML configuration is set at the account level. You must be an Account Administrator to configure SAML for your Cloud account. Note: For your consumers to view the embedded Birst Content in another application via SAML, those users will need to be members of the Account where you create the Birst SAML configuration and they will need to have access to the Birst Space along with feature access (i.e. Visualizer, Designer and/or Dashboards) where the Birst content resides.

Additional details, Birst allows you to share spaces regardless of your account status but SAML requires the content being embedded and viewed via SSO to reside on the same account.

If you are adding SAML support for the Appliance, supply the configuration information in the Appliance Management UI at System Manager - Miscellaneous - SAML Configuration.

Before configuring Birst to support your SAML Identify Provider (IdP), first obtain the following information:

• Birst SAML endpoint
• For the Appliance, the URL is similar to: https://fqdn/SAMLSSO/Services.aspx
• For the Birst Cloud, the URL is similar to: https://login.bws.birst.com/SAMLSSO/Services.aspx
  • IdP certificate file
  • IdP issuer ID / entity ID
    • For an SP-Initiated SAML configuration, the IdP might need to know the entity ID of the Service Provider. When you configure SAML in Birst, there is the SP entity ID field generated by Birst. It looks like https://www.birst.com/<SAML_CONFIG_ID>. Use that SP entity ID in the IdP configuration settings.

And optionally:

• Key pair: For SAML assertion encryption. Birst Support can provide instructions on how to generate the key pair.
• Idle timeout value (in minutes).
• Logout page URL:  For a custom logout page that you want to be redirected to on timeout.
• Error page URL: For a custom error page that you want to be redirected to on error.

To configure a SAML IdP in Birst

1. From the Home page, click Account Settings.
   
   
   
   
2. On the SAML Configurations tab click Add (+ sign).
3. Name the new configuration and click Save (check box).
   
   The SAML configuration screen opens.
   
   
4. Enter the Issuer ID, also called the Entity ID, of the Identity Provider.
5. Copy and paste the authentication certificate into the Certificate pane.
6. Optionally, enter the URL for a custom error page to be redirected to if an error occurs.
7. Optionally, enter the URL for a custom log out page to be redirected to on log out.
8. Enter the idle duration in minutes after which a timeout occurs. The default is 20 minutes.
9. If you want to allow service provider initiated access:
   1. Check SP-Initiated.
   2. Enter the Identity Provider Single Sign-On URL.
      
10. Click Save.
11. For service provider-initiated access:
    1. After you click Save, Birst generates the SP initiated SSO URL and displays it.
    2. Use this ID value with the birst.idpid SAML query parameter for logging into Birst. For example:
       https://login.bws.birst.com/SAMLSSO/Services.aspx?birst.idpid=SAML_config_ID
       Use that URL to login to Birst
       Tip: Remember to use URL encoding for any non-ASCI characters. https://www.urlencoder.org/
    3. When browsers connect to this URL, they are redirected to the Identity Provider Single Sign-On URL as specified in Step 9.
       Tip: Users can bookmark the redirect URL for easier access to Birst.
       

Example of Using SAML with Single Sign-On (SSO)

Birst session-specific parameters, including spaceId, module, dashboard/page/report names, prompt values, session variables, and dynamic group settings, can be passed as part of the SAML assertion in the same way they are used in Birst custom SSO. See SSO Parameters.

Tip: SAML SSO parameters require the "birst." prefix. Some parameters have multiple naming conventions so make sure you are using the "birst." prefix.

The following is an example of SAML attributes for Birst SSO.

<saml:AttributeStatement>
       <saml:Attribute Name = "birst.module" NameFormat = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml:AttributeValue xsi:type = "xs:string" xmlns:xs = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance">dashboard</saml:AttributeValue>
       </saml:Attribute>
       <saml:Attribute Name = "birst.spaceId" NameFormat = "urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
            <saml:AttributeValue xsi:type = "xs:string" xmlns:xs = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance">E4BE5BDA-CF27-4C0A-B473-56C069F3C9E7</saml:AttributeValue>
       </saml:Attribute>
  </saml:AttributeStatement>

User Provisioning

See User Provisioning with SAML.