Set Up SAML With a Generic Security Provider

The following steps show how to set up BeyondInsight with a generic security provider.

Configure SAML in the BeyondInsight Console

To configure SAML in the BeyondInsight console, follow the following steps:

  1. Navigate to Configuration > Authentication Management > SAML Configuration.

Screenshot of SAML Configuration in BeyondInsight Console

  1. From the SAML Identity Providers pane, click Create New SAML Identity Provider.
  2. Provide a name for the new SAML Identity Provider (IdP).
  1. Complete the Identity Provider Settings as follows:
    • Check the Default Identity Provider option if you have more than one IdP for the same service provider, and would like this IdP to be used as default for service provider initiated logins. This is useful in the case in which someone accesses the URL without providing an IdP.
    • Identifier: Enter the name of the identity provider entry, normally supplied by the provider.
    • Single Sign-on Service URL: Provide the SSO URL, from the provider.
    • SSO URL Protocol Binding: Select either HTTP Redirect or HTTP Post as the type.
    • Single Logout Service URL: Enter the SLO URL, from the provider.
    • SLO URL Protocol Binding: Select either HTTP Redirect or HTTP Post as the type.
    • Encryption and Signing Configuration: Check applicable boxes to enable options, as required by your service provider.
    • Signature Method: Select the method, as is required by your IdP, from the dropdown.
    • Current Identity Provider Certificate: Upload the identity provider certificate.
    • User Mapping: Select the type of user account from the dropdown. This indicates how user claims from the SAML provider are mapped in the BeyondInsight User database.
      • None: This is the legacy type of mapping, which is not based on type of user.
      • Local: Select this option for local user account claims. BeyondInsight maps the user and group name.
      • Azure Active Directory: Select this option for Azure Active Directory user account claims. When selected, BeyondInsight maps the ObjectID attribute to the AppUser and UserGroup attributes for the user.
      • Active Directory: Select this option for Active Directory user account claims. If the claims are configured to pass the SID of the user and group, BeyondInsight maps the SID for the user and group, which is preferred over mapping domain name and group name attributes.
  2. Click Save SAML Identity Provider.
  3. The following Service Provider Settings are auto-generated by BeyondInsight:
    • Entity ID: This is the fully qualified domain name, followed by the file name: https://<serverURL>/eEye.RetinaCSSAML/. This is used for audience restriction.
    • Assertion Consumer Service URL: The HTTPS endpoint on the service provider where the identity provider redirects to with its authentication response. .
  4. Click Save SAML Configuration.

 

Once the SAML configuration is saved, a public SP certificate is available to download. It can be uploaded to the IdP, if required.

For more information on configuring an Azure Active Directory SAML Provider, please see Configure Azure Active Directory SAML with BeyondInsight SAML.

Configure SAML Using the saml.config File

In the case where you have multiple service providers, you can configure SAML manually as outlined below.

Copy Certificates from IdP

  1. Copy the idp.cer file you received from the IdP to the following folder on the UVM: C:\Program Files (x86)\eEye Digital Security\Retina CS\WebSiteSAML\Certificates.

Generate or Obtain a Private Service Provider Certificate (sp.pfx file)

Generate your own Self Signed Certificate as follows:

  1. Use PowerShell to generate a new certificate:
New-SelfSignedCertificate -Subject "BI SAML SP" -CertStoreLocation cert:\LocalMachine\My - Provider "Microsoft Enhanced RSA and AES Cryptographic Provider" -HashAlgorithm SHA256 - KeyLength 2048 -NotAfter 1/1/2050         

This command requires PowerShell 5.0 or later (Windows 10 or Server 2016).

  1. Make note of the Thumbprint for later use, for example: 7120E0BD353429D18F9829096AB3BC9A80AF33B8.
  2. Export the public key for your certificate:
Export-Certificate -Cert cert:\LocalMachine\My\7120E0BD353429D18F9829096AB3BC9A80AF33B8 - FilePath c:\certs\sp.der
  1. Convert the certificate to base 64:
Certutil.exe -encode c:\certs\sp.der c:\certs\sp.cer

Use a certificate obtained from a Certificate Authority as follows:

Your Certificate must have the following capabilities:

  • Enhanced Key Usage: Client Authentication, Server Authentication
  • Key Usage: Digital Signature, Key Encipherment

Add the certificate to the Local Machine, Personal Store and add any Intermediate or Root certs to the proper stores if needed.

If you want to use the Service Provider cert from the Certificate Store you must grant permissions to IIS to READ the Private Key:

  1. Open MMC.
  2. Add the Certificate SnapIn for Local Machine.
  3. Explore to Personal/Certificates.
  4. Right -click on your Certificate that was setup for the service provider.
  5. Select All Tasks > Manage Private Keys.
  6. Add the IIS user: IIS_IUSRS.

Modify saml.config File

The file is located here: C:\Program Files (x86)\eEye Digital Security\Retina CS\WebSiteSAML.

Update the Service Provider section as follows:

  • Name: Should be fully qualified domain followed by eEye.ReintaCSSAML. This is used for the Audience Restriction.
  • Description: Add a description.
  • AssertionComsumerServiceUrl: This shouldn't need to be modified.
  • If you save the certificate for the SP to the certificate folder use these options:
    • LocalCertificateFile: Path to the certificate
    • LocalCertificatePassword: Password for the PFX file
  • If you want to use the certificate from the cert store remove LocalCertificateFile and LocalCertificatePassword and add:
    • LocalCertificateThumbprint: Thumbprint of the certificate

You can remove all but your one IdP entry.

The following IdP fields must be updated to your environment settings:

  • Name: The name of the Provider entry, normally provided by the provider
  • SingleSignOnServiceUrl: URL for SSO from IdP
  • SingleLogoutServiceUrl: URL for SLO from IdP
  • PartnerCertificateFile: Location to the public cert for the IdP

The other settings are set to what your Provider requires.

Below are some common configurations for some of the common IdPs:

example saml.config (this is configured for OKTA using a self signed service provider certificate)

<?xml version="1.0" encoding="utf-8"?>
<SAMLConfiguration xmlns="urn:componentspace:SAML:2.0:configuration">
 <ServiceProvider 
  Name=https://pws.mydomain.com/eEye.RetinaCSSAML/
  Description="Example Service Provider"
  AssertionConsumerServiceUrl="~/SAML/AssertionConsumerService.aspx">
  <LocalCertificates>
   <Certificate
    Thumbprint="05552BAF3B8BC9675C94EDB885D4B821F3DC15DE" />
  </LocalCertificates>
 </ServiceProvider>
 <PartnerIdentityProviders>
  <PartnerIdentityProvider 
   Name=http://www.okta.com/exk1dg5hqz3LbpBIj5d7
   Description="ADFS"
   SignAuthnRequest="false"
   SignLogoutRequest="false"
   WantSAMLResponseSigned="false"
   WantAssertionSigned="false"
   WantAssertionEncrypted="false"
   WantLogoutResponseSigned="false"
   SingleSignOnServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   SingleSignOnServiceUrl=https://dev-25872691.okta.com/app/dev-25872691_bi212_1/exk1dg5hqz3LbpBIj5d7/sso/saml
   SingleLogoutServiceBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
   SingleLogoutServiceUrl=https://dev-25872691.okta.com/app/dev-25872691_bi212_1/exk1dg5hqz3LbpBIj5d7/slo/saml>
   <PartnerCertificates>
    <Certificate
    FileName="Certificates\okta.cer" />
   </PartnerCertificates>
  </PartnerIdentityProvider>
 </PartnerIdentityProviders>
</SAMLConfiguration>

Update Host Name and SAML access URL

This is applicable to on-premises installations only. For PS Cloud or on-premises installations, Access URLs can also be set in the BI configuration.

  1. Open the BeyondInsight Configuration Tool.
  2. Scroll Down to SAML Access URL.
  3. Update it to the fully qualified domain, followed by the file name:

    https://<FQDN>/eEye.RetinaCSSAML/

  4. Scroll down to the Host Name field under the Web Site Information section.
  5. Update it to the fully qualified domain, for example, bidev.shines.test.cloud.
  6. Click Apply.

The host name is the fully qualified domain name used to access BI/PS. If this is a load-balanced instance, the host name is the same on all servers.

Configure Identity Provider (IdP)

Below are some of the values an IdP might need:

  • Audience Restriction: https://<FQDN>/eEye.RetinaCSSAML/
  • SSO Service URL: https://<FQDN>/eEye.RetinaCSSAML/SAML/AssertionConsumerService.aspx
  • SLO Service URL: https://<FQDN>/eEye.RetinaCSSAML/SAML/SLOService.aspx
  • Service Provider Certificate: (generated when SAML configuration is saved)

Your identity provider needs to provide the following attributes in the assertion:

  • Group: (Required) This must match the group created in BeyondInsight or imported from Active Directory. If an Active Directory group is used, it must match the BI format Domain\GroupName.
  • Name: (Required) This should be the be in the format domain\username or UPN.
  • Email: (Optional)
  • Surname: (Optional)
  • GivenName: (Optional)

Configure Azure Active Directory SAML with BeyondInsight SAML

You can integrate Azure Active Directory (Azure AD) SAML with BeyondInsight SAML so that when BeyondInsight receives claims from Azure AD, it can enumerate groups for the user directly from Azure AD using the Group ID value in the claim. This allows an Azure AD user to log in to BeyondInsight using SAML authentication when the user account does not yet exist in the BeyondInsight User database. BeyondInsight adds the user to its database automatically upon successful Azure AD group enumeration and authentication into BeyondInsight.

To configure the integration between Azure AD SAML and BeyondInsight SAML, log in to your Azure AD tenant and follow the instructions below to add a new enterprise application to host the SAML configuration for BeyondInsight:

Screenshot of adding a new enterprise application in Azure Active Directory

  1. In Azure, navigate to Enterprise Applications, and then click + New Application.

 

Screenshot of creating your own enterprise application in Azure Active Directory

  1. Click + Create your own application.
  2. Provide a name.
  3. Select the Integrate any other application you don’t find in the gallery (Non-gallery) option.
  4. Click Create.

 

  1. In the BeyondInsight console, create a new SAML Identity Provider. To complete the SAML IdP config in BeyondInsight, use the following information from the enterprise application you just created:
  2. Screenshot of SAML Login URL and Azure AD Indentifier for enterprise application in Azure Active Directory

    • In Azure, go to the SAML-based Sign-on configuration page for the application.
    • In the Set up <application name>section, copy the Login URL and the Azure AD Identifier and save them.
    • Paste them into the Identifier, Single Sign-on Service URL, and Single Logout Service URL fields in the BeyondInsight SAML IdP configuration.

 

Screenshot of Set up single sign-on option when creating your own enterprise application in Azure Active Directory

  1. In Azure, open the Properties for the newly created enterprise application.
  2. From the Getting Started section, click Set up single sign-on.

 

Screenshot of Basic SAML Configuration for enterprise application in Azure Active Directory

  1. In the Basic SAML Configuration section, provide the Identifier (Entity ID) and Reply URL (Assertion Consumer Service URL) obtained from the SAML IdP you just created in BeyondInsight.
  2. In the User Attributes & Claims section, click Edit to add the group claim.

 

Screenshot of adding a new claim for enterprise application SAML based sign-on in Azure Active Directory

  1. Click + Add a group claim.
  2. In the Group Claims section:
    • Select which groups associated with the user to return in the claim: either Groups assigned to the application or Security Groups.
    • Select Group ID from the Source attribute.

 

For more information on configuring a SAML IdP in BeyondInsight, please see Configure SAML in the BeyondInsight Console.

Disable Forms Login

In environments where SAML, smart card, or claims-aware is configured, we recommend enabling the Disable Forms Login authentication option to disallow users from using the standard login form in BeyondInsight.

To disable forms login for existing users, enable this option directly on a user account as follows:

  1. Click the vertical ellipsis for the user account, and then click Edit User Details.

Screenshot of Disable Forms Login option on a User account.

  1. Under Authentication Options, toggle Disable Forms Login to enable the option.

Please contact support for assistance if you need to bulk-apply this setting to existing accounts.

 

To configure login forms to automatically be disabled for newly created users:

Screenshot of the Forms Login Options

  1. Navigate to Configuration > Authentication Management > Authentication Options.
  2. Under Forms Login Options, enable one or both options as applicable:
    • Disable Forms Login for new directory accounts
    • Disable Forms Login for new local accounts