SAML

Integration of your B Series Appliance with external identity providers enables you to efficiently manage user access to BeyondTrust accounts by authenticating users against external directory stores.

This guide helps you configure the B Series Appliance to communicate with an identity provider using SAML 2.0 for the purpose of user authentication and group lookup.

Should you need any assistance, please log into the Customer Portal to chat with BeyondTrust Technical Support.

Configure the SAML security provider

Go to /login > Users & Security > Security Providers.

From the + ADD dropdown, select the type of server you want to configure.

ℹ️

Note

You can configure only one SAML provider for public portals. Multiple SAML providers can be configured for representatives, but a representative who is defined in more than one provider can only be mapped to the first provider.

SAML for representatives settings

Name

Enter a unique name to help identify your provider.

Enabled

If checked, your BeyondTrust Appliance B Series can search this security provider when a user attempts to log in to the representative console or /login. If unchecked, this provider will not be searched.

Associated email domains

This setting only applies if you have more than one active SAML provider and is ignored otherwise.

Add any email domains that should be associated with this SAML provider, one per line. When authenticating, users are asked to enter their email. The domain of their email is matched against this list, and they are redirected to the appropriate identity provider for authentication.

If multiple SAML providers are configured and the user's email does not match any of the associated domain on any provider, then they are not allowed to authenticate.

Identity provider settings

Metadata

The metadata file contains all the information needed for the initial setup of your SAML provider and must be downloaded from your identity provider. Save the XML file, and then click Upload Identity Provider Metadata to select and upload the selected file.

Entity ID

Unique identifier for the identity provider you are using.

Server certificate

This certificate will be used to verify the signature of the assertion sent from the identity provider.

ℹ️

Note

The fields for Entity ID, Single Sign-On Service URL, and Certificate are automatically populated from the identity provider's metadata file. If you cannot get a metadata file from your provider, this information can be entered manually. For metadata files with multiple identity providers, enter the Entity ID of the desired Identity Provider in the field below before uploading the metadata.

Single sign-on service URL

When you want to log in to BeyondTrust using SAML, this is the URL where you are automatically redirected so you can log in.

SSO URL protocol binding

Determines whether a user posts or is redirected to the sign on URL. This should be left defaulted to redirect unless otherwise required by the identity provider.

If request signing is enabled (under Service Provider settings), protocol binding is limited to redirect only.

Service provider settings

Download service provider metadata

Download the BeyondTrust metadata, which must then be uploaded to your identity provider.

Entity ID

This is your BeyondTrust URL. It uniquely identifies the service provider.

Private key

If necessary, you can decrypt messages sent by the identity provider, if they support and require encryption. Click Choose File to upload the private key necessary to decrypt the messages sent from the identity provider.

Signed AuthnRequest

Check to enable request signing. If enabled, SSO URL protocol binding is limited to redirect only. The SSO URL protocol binding field is updated automatically, if necessary.

A private key and signing certificate is required for request signing.

User attribute settings

SAML attributes are used to provision users within BeyondTrust. The default values match BeyondTrust-certified applications with various identity providers. If you are creating your own SAML connector, you may need to modify the attributes to match what is being sent by your identity provider. If your identity provider requires case-insensitivity for the NameID attribute, select Use case-insensitive comparison for NameIDs.

Authorization settings

Lookup groups using this provider

Enabling this feature allows faster provisioning by automatically looking up groups for this user, using Group Lookup Attribute Name and Delimiter. We recommend enabling this feature. If not used, SAML users must be manually assigned to group policies after their first successful authentication.

Group lookup attribute name

Enter the name of the SAML attribute that contains the names of groups to which users should belong. If the attribute value contains multiple group names, then specify the Delimiter used to separate their names.

If left blank, SAML users must be manually assigned to group policies after their first successful authentication.

Group lookup delimiter

If the Delimiter is left blank, then the attribute value may contain multiple XML nodes with each one containing a different name.

Available groups

This is an optional list of SAML groups always available to be manually assigned to group policies. If left blank, a given SAML group is made available only after the first successful authentication of a user member of such group. Please enter one group name per line.

Default group policy

Each user who authenticates against an external server must be a member of at least one group policy in order to authenticate to your B Series Appliance, logging into either the /login interface or the representative console. You can select a default group policy to apply to all users allowed to authenticate against the configured server.

If a default policy is defined, any allowed user who authenticates against this server might have access at the level of this default policy. Therefore, we recommend you set the default to a policy with minimum privileges to prevent users from gaining permissions you do not wish them to have.

ℹ️

Note

If a user is in a default group policy and is then specifically added to another group policy, the settings for the specific policy always take precedence over the settings for the default, even if the specific policy is a lower priority than the default, and even if the default policy's settings are set to disallow override.

Test settings

You can test the SAML configuration from this page. The provider must be saved before it can be tested. Click Save at upper left area of the screen, then scroll down and click Test. The configuration is tested against the identity provider, and a test results page shows the SAML response and a formatted version of the assertion XML. The responses can be copied to other tools if further review is required.

SAML for public portals settings

Name

The name for your SAML provider is auto-generated and cannot be edited at this time.

Enabled

If checked, your BeyondTrust Appliance B Series can search this security provider when a user attempts to log in to the public portal. If unchecked, this provider is not searched.

Identity provider settings

Metadata

The metadata file contains all the information needed for the initial setup of your SAML provider and must be downloaded from your identity provider. Save the XML file, and then click Upload Identity Provider Metadata to select and upload the selected file.

Entity ID

Unique identifier for the identity provider you are using.

Server certificate

This certificate will be used to verify the signature of the assertion sent from the identity provider.

ℹ️

Note

The fields for Entity ID, Single Sign-On Service URL, and Certificate are automatically populated from the identity provider's metadata file. If you cannot get a metadata file from your provider, this information can be entered manually. For metadata files with multiple identity providers, enter the Entity ID of the desired Identity Provider in the field below before uploading the metadata.

Single sign-on service URL

When you want to log in to BeyondTrust using SAML, this is the URL where you are automatically redirected so you can log in.

SSO URL protocol binding

Determines whether a user posts or is redirected to the sign on URL. This should be left defaulted to redirect unless otherwise required by the identity provider.

If request signing is enabled (under Service Provider settings), protocol binding is limited to redirect only.

Service provider settings

Download service provider metadata

Download the BeyondTrust metadata, which must then be uploaded to your identity provider.

Entity ID

This is your BeyondTrust URL. It uniquely identifies the service provider.

Private key

If necessary, you can decrypt messages sent by the identity provider, if they support and require encryption. Click Choose File to upload the private key necessary to decrypt the messages sent from the identity provider.

Signed AuthnRequest

Check to enable request signing. If enabled, SSO URL protocol binding is limited to redirect only. The SSO URL protocol binding field is updated automatically, if necessary.

A private key and signing certificate is required for request signing.

User attribute settings

SAML attributes are used to provision users within BeyondTrust. The default values match BeyondTrust-certified applications with various identity providers. If you are creating your own SAML connector, you may need to modify the attributes to match what is being sent by your identity provider. The SAML attributes can also be associated with customer sessions by adding custom fields with matching code names on the Custom Fields page in /login.

Test settings

You can test the SAML configuration from this page. The provider must be saved before it can be tested. Click Save at upper left area of the screen, then scroll down and click Test. The configuration is tested against the identity provider, and a test results page shows the SAML response and a formatted version of the assertion XML. The responses can be copied to other tools if further review is required.

Enable SAML authentication on a public site

Once SAML for Public Portals settings have been configured, you can enable SAML authentication on a public site in /login as follows:

1. Go to Public Portals > Public Sites.
2. Click Edit next to the desired public site.
3. Select Require SAML Authentication.
4. Click Save.

Log in to Remote Support using SAML

Representatives can utilize SAML single sign-on to gain access to the representative console or /login interface. Customers can utilize SAML single sign-on to gain access to the public support portal. Alternatively, a login can be initiated from the identity provider's side.

Sign in to the representative console using SAML credentials

1. Select SAML Credentials from the dropdown menu.
2. If you have not yet signed in to your identity provider, you will be redirected using the default browser.

ℹ️

Note

Representatives can access the mobile representative console using SAML for mobile.

Sign in to the /login interface using SAML credentials

ℹ️

Note

If you are already signed into your identity provider when you click Use SAML Authentication, you are taken directly to the /login interface.

1. From the /login interface, select Use SAML Authentication. If you have not yet signed in to your identity provider, you will be redirected to their site to enter your credentials.
2. Click Sign In. You are taken to the /login interface.

Sign in to the public portal using SAML credentials

A customer can access the public support portal using the URL provided by a representative. If SAML authentication is configured and enabled for the public site, the customer is presented with the Portal Login window. The customer must click Login and then provide credentials to authenticate with the identity provider.

The customer is then taken to the support portal page where they can submit their request for support. The customer's name and any custom fields that are configured, such as email, are automatically populated and are not editable.

ℹ️

Note

A green check mark displays next to the customer's name in the representative console chat window to indicate the user is public portal authenticated.

Sign in to BeyondTrust from the identity provider side

Depending on your identity provider, you can opt to sign in to your BeyondTrust representative console, public portal, or /login interface from the provider's web site. In this example, the provider has icons for BeyondTrust applications. Simply sign in to your provider's site, and then click on the application you want to use.

Sign in directly to the web rep console using SAML

It is possible to configure an application or tile in a SAML identity provider (IdP), (like the tiles used to sign in to Okta and similar applications) that takes you directly to the web rep console rather than to /login.

To configure this, you must:

• Set up application in the IdP as you would for /login
• Change the RelayState parameter. To obtain the correct parameter, copy the entire string shown for RelayState in the SAML request in SP-initiated login into the /console page, and paste this value into the SAML SP provider configuration for RelayState on the IdP side. This enables IdP-initiated login to be to the /console page instead of to the default /login page.

There are two parts to the SAML configuration: the IdP and service provider (SP). In this instance you are the SP, and the SAML service is the IdP (OneLogin, Okta, and similar). Currently, you can export metadata from the SAML security provider on /login (in the Service Provider section), which you can then import into the IdP to help configure the SAML side. If, as part of this configuration, you set the RelayState parameter to console, then any login initiated from the IdP (for example, clicking the tile in Okta) sends you to the web rep console rather than to /login.

Manage security providers

The list of security providers has several icons at the right end of row. Click the pencil icon to edit the provider. Click the trash can icon to delete the provider. Click the ellipsis for actions available for that providers. Actions available depend on the provider type and setting, but usually include Disable and View Log.

Disable

Disable this security provider connection. This is useful for scheduled maintenance, when you want a server to be offline but not deleted.

View Log

View the status history or any errors for a security provider connection.