User Provisioning with SAML
When using SAML for authentication, Birst can use attributes in the SAML assertion to do just-in-time user provisioning. This allows you to create new users and modify existing users on the fly during the authentication process. The identity passed in via the SAML assertion will be used for the user name when creating the user or determining if the user already exists.
To set up user provisioning you add Birst specific SAML attributes to the SAML assertion.
Birst-Specific SAML Attributes
The following assertions are only for provisioning users, not for creating/modifying spaces, profiles, or groups, nor for disabling or deleting users.
| Assertion Name | Required for User Creation? | Comment |
|---|---|---|
| birst.accountId | No | ID of the account in which to create the user. This is for cases where the SAML IdP can be mapped to multiple Birst accounts. If there are multiple Birst accounts for the IdP this parameter must be specified. If this parameter is not specified and there are multiple accounts for the IdP the user creation and authentication will fail. If this parameter is specified and does not match the IdP, the user creation and authentication will fail. |
| birst.dashboardsView | No | Allows the user to pin to a specific Dashboard view. Allowed values are: flash, html, dashboard2.0. (This is similar to the SSO parameters). |
| birst.defaultSpace | No | The Space ID of the default space that can be associated with the user. After the user has been provisioned, this allows the users logging into Birst to default to a particular space. |
| birst.globalGroups | No | Dynamically assigns space membership to a user based on the groups to which the user belongs. Within an account, Birst finds all the spaces that have the specified group name or names and the new user is added to all of the matching spaces. Important: Be very careful using this assertion in case the user would be given unintended access to a space. It is a best practice to use both birst.memberSpaces and birst.group instead. |
| birst.group | No |
Adds the user to the groups in the birst.group attributes. If no groups are specified the user will be assigned to the default USERS$ group. birst.group can be a multi-value attribute, see the example code below. Alternatively, use a single-value attribute with a comma-separated list of group names. Tip: This setting assumes that the birst.spaceId attribute is already specified. Important: If the user already exists and is already a member of groups in this space, the user will be removed from any groups not specified by birst.group. |
| birst.memberSpaces | No |
Adds the user to all spaces specified by the space IDs. birst.memberSpaces can be a multi-value attribute, the same as for birst.group, refer to the example code below. Alternatively, use a single-value attribute with a comma-separated list of space IDs. Important: Also include all spaces to which a user may already have access. Access to any space that the user is already a member of but is not specified by birst.memberSpaces will be removed. Exceptions are the spaces already created by the user, the Space Owner. Access to spaces created by the user cannot be removed in this manner. |
| birst.mobileStatus | No | Sets the permission to access Dashboards 2.0 dashboards on a mobile device. This is the same as in the User Management - Update Mobile Status. Valid values are: "Online", "Online + Offline", or "None". The default is "None". To use Online + Offline, the account must first be enabled for the Birst Mobile off line feature. In addition, user accounts must be granted access to Dashboards 2.0. |
| birst.relayState | No |
Allows multiple Dashboards 2.0 dashboards to be embedded in different pages of another web application. Space-specific parameters can be passed dynamically as part of an SP-initiated SAML URL. 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.spaceCreation | No | Allows the newly provisioned user to create spaces. The value is either true or false. The default value is true. |
| birst.spaceId | No |
Adds the user to the space and sets the space as the default login space. Tips:
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.
|
| birst.userEmailAddress | Yes |
Email address of the user. The email address is used for email notifications to the user and for password reset if interactive login is allowed. The Birst email address must meet criteria associated with the Birst account. For example, your Birstaccount may be set up to only allow email addresses associated with your corporate email domain. If birst.userLoginName is not specified, birst.userEmailAddress will be used for the Birst username. |
| birst.userLoginName | No | The login name for the user. This can be different from the identity used in the SAML assertion. If this does not exist, birst.userEmailAddress will be used for the Birst username. If the username is different than the SAML identity, a mapping will be added to associate with identity and user. |
| birst.userProducts | No |
Enables or disables the following non-licensed products for the user: Birst Connect (ID 9), Live Access (ID 10), and Web Services (ID 11). Licensed products cannot be added with this attribute. The value is one or more product IDs. For example: birst.userProducts = 9,10,11 If a user already has a product (Birst Connect, Live Access, and/or Web Services) and birst.UserProducts is provided but it does not contain the product ID, then the product is disabled. If a user already has a product and birst.UserProducts does not contain the value for it, the product is disabled. If birst.userProducts is not provided, then a user will have the same products as before. |
| birst.userProfile | No |
ID of the user profile to which the user will be assigned. If the parameter is missing, the account level default profile is used. If the user already exists, the user's profile will be changed to this value. Tip: Profiles contain, among other things, information about users locale, ability to interactively login, and look and feel settings. Over time various account level parameters (such as idle timeouts and authentication options) and Birst product settings (such as the ability to use Birst Connect or Birst Web Services) will move here. The Infor Team recommends that users that authenticate via SAML be assigned to profiles that have interactive login disabled unless there is a specific need to allow the user to login via the default form-base login page (this may be the case for Administrators). |
| birst.userRelease | No | Sets the user's release version type. This functionality is the same as the User Management - Update Release Usage window. Valid values are either "Default" or a valid release version number such as "5.23.10". The default for a newly-provisioned user account is "Default". For existing user accounts, the default is the current setting. |
Example SAML AttributeStatement for Just-In-Time User Provisioning
The following example shows a set of attributes for just-in-time provisioning.
<saml:AttributeStatement> <saml:Attribute Name="birst.userEmailAddress" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">nobody@example.com </saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="birst.userProfile" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">23e2ff70-4434-49eb-af29-d926bc2d77de </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:anyType">53425f70-8434-4a3b-af29-d926bc2d77fe </saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="birst.group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">sales </saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="birst.group" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"> <saml:AttributeValue xsi:type="xs:anyType">marketing </saml:AttributeValue> </saml:Attribute> </saml:AttributeStatement>
ADFS and User Provisioning
To configure just-in-time user provisioning when using ADFS, you map information in AD/LDAP to SAML attributes in the assertion. The SAML assertion attributes will have the same structure as the attributes shown in Integrating Birst with SAML. See also the article Tips for Setting Up SAML with ADFS 2.0.
In Active Directory, you map Active Directory attributes to SAML attributes using Claims. Consult your ADFS SAML documentation for detailed information about Claims and how to map them to SAML attributes. You will need to understand how to create custom claim rules. See the Microsoft Claim Rules topics.