Configuring Single Sign-on/SAML2 integrations (Azure Active Directory / ADFS)

The SAML2 integration is capable of enabling Single sign-on (SSO) with the Azure Active Directory (Azure AD) or ActiveDirectory Federation Services (AD FS) of your company.

Introduction

Before we start we give a short introduction of the SAML2 integration:

As being an integration there are two systems involved, which need to be configured:

  • The Identity Provider (IdP), being Azure AD or AD FS:
    The IdP must be configured to trust the GoBright Platform as Service Provider, and claims have to be configured.

    Please note: for enabling SAML in Azure AD, you need Azure AD Premium P1 or higher, for SAML in AD FS there is no extra requirement.

  • The GoBright Platform being the Service Provider (SP):
    The SAML integration has to be created as an 'Integration' of type 'SAML' in the portal, whereas you need to configure the details of the the IdP.
    You can have one SAML integration in a GoBright environment.

When configured you can also auto create users, so that users which are unknown to the system will automatically be created after successful SAML-based sign-on. 

Step 1: Create the SAML integration in the GoBright Portal

Follow these steps to create the SAML integration, and to get the information needed:

  • Log in with a manager user in the GoBright portal
  • Go to Settings > Integrations
  • Add an integration with the '+' button
  • Give the integration a name, and set the 'external system' to 'SAML'.
  • Save the integration

Now you will see more details, for now you need to copy the 'Reply URL (Assertion Consumer Service URL)' you will need this in the next step.

You can now proceed to step 2, the other details in this screen will be filled in step 3.

Step 2: Configure the IdP

Now you need to configure the IdP, select the IdP you are using below, and follow the steps:

Configure SAML in Azure AD

Create the Enterprise application for the GoBright platform:

  1. Login to your Azure Active Directory admin center
  2. Click 'Azure Active Directory' in the left-hand menu, and confirm that your Azure AD is 'Azure AD Premium P1' or higher
    AzureAD1-0.png
  3. Click 'Enterprise applications' and choose 'New application'
    AzureAD1-1.png
  4. Choose 'Non-gallery application', give it the name with 'GoBright', and choose 'Add'
    AzureAD2.png
  5. Now wait for Azure AD while it processes adding the application, this might take a minute, then Azure AD will open the overview of the application.
    AzureAD3.png
  6. Now add the users and groups you want to give access to this application (you can start off with a few test users):
    AzureAD3-2.png
  7. Now configure SAML for this enterprise application:
    Go to ‘Single sign-on’ and choose ‘SAML’
    AzureAD4.png
  8. You are now on the ‘Set up Single Sign-on with SAML’ page proceed with the next parts below.

Enterprise application configuration: Set up Single Sign-on with SAML:

  1. Basic SAML Configuration:
    Fill ‘Identifier (Entity ID)’ with ‘https://www.gobright.com/sso/
    Fill ‘Reply URL (Assertion Consumer Service URL)’ with the 'Reply URL (Assertion Consumer Service URL)' which you have found in step 1.
    AzureAD5.1.png
  2. User Attributes & Claims
    Configure the claims, whereas the images below show the minimum claims:
    AzureAD5.2.1.pngAzureAD5.2.2.png

    CLAIM NAME VALUE

    http://schemas.microsoft.com/identity/claims/displayname

    user.displayname

    http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

    user.userprincipalname
  3. SAML Signing Certificate
    Download the ‘Certificate (Base64)’ and save the file to a location of your preference, for example in 'C:\tokencertificate.cer'
    Now open 'Notepad' and load the exported certificate (for example 'C:\tokencertificate.cer').

    You will now see the text contents, in the following format:
    -----BEGIN CERTIFICATE-----
    ..........DATA.............
    -----END CERTIFICATE-----

    You will need this in step 3 to configure the GoBright portal.

    AzureAD5.3.png
  4. Set up GoBright
    Copy the 'Login URL' and 'Logout URL', you will need this in step 3 to configure the GoBright portal.
    AzureAD5.4.png

Please proceed to step 3. 

Configure SAML in AD FS

Create the Relying Party Trust for the GoBright platform:

  1. Login to your AD FS server
  2. Start the AD FS management console
  3. Select ‘Relying Party Trust’ in the left-hand treeview, and ‘Add Relying Party Trust…’ in the Actions panel.
    In the 'Add Relying Party Trust Wizard', choose 'Claims aware', and click 'Start'.
    AD_FS_1.png
  4. In 'Select Data Source', select 'Enter data about the relying party manually'.
    Then click 'Next'.
    AD_FS_2.png
  5. In 'Specify Display Name', fill 'Display name' with 'GoBright'.
    Then click 'Next'.
    AD_FS_3.png
  6. In 'Configure Certificate', click 'Next'.
    AD_FS_4.png
  7. In 'Configure URL', select 'Enable support for the SAML 2.0 WebSSO protocol'.
    Fill the 'Relying party SAML 2.0 SSO service URL' with the 'Reply URL (Assertion Consumer Service URL)' which you have found in step 1.
    Then click 'Next'.
    AD_FS_5.png
  8. In 'Configure Identifiers':
    Fill the 'Relying party trust identifier' with: https://www.gobright.com/sso/
    Then click 'Add' and click 'Next'.
    AD_FS_6.png
  9. In 'Choose Access Control Policy', you can configure who you want to have access to GoBright. Make sure that you have (at the very least) access with the account you will use to test the SAML integration.
    Then click 'Next'.
    AD_FS_7.png
  10. In 'Ready to Add Trust', you can review the settings and click 'Next'.
  11. In 'Finish', check 'Configure claims issuance policy for this application' click 'Close'.
    AD_FS_8.png

Configure the Claims Issuance Policy:

  1. Open the Claims Issuance Policy properties (if it is not already open):
    AD_FS_Claims_1.png
  2. Choose 'Add Rule...':
    AD_FS_Claims_2.png
  3. The 'Add Transform Claim Rule Wizard' opens.
    Choose as 'Claim rule template' the option 'Send LDAP Attributes as Claims. 
    Then click 'Next'.
    AD_FS_Claims_3.png
  4. Now configure the claim rule:
    - Set the 'Claim rule name' to: GoBright default claims
    - Set the 'Attribute store' to: Active Directory
    - Configure the 'Mapping of LDAP attributes to outgoing claim types' with the exact values:
      (please copy-paste the values)
    LDAP Attribute Outgoing Claim Type
    User-Principal-Name Name ID
    Display-Name Common Name
    objectGuid http://schemas.microsoft.com/identity/claims/objectidentifier
    AD_FS_Claims_4.png
  5. Then click 'Finish' and click 'OK'

Configure the Secure Hash Algorithm:

  1. Please confirm the 'Secure hash Algorithm' is set to 'SHA-256' by following these steps.
  2. Open the Properties of the 'GoBright' Relying Party Trusts
  3. Open the tab 'Advanced'
  4. Set the 'Secure hash Algorithm' to 'SHA-256' if it is not already
  5. Click 'OK'
    AD_FS_Properties_1.png

Copy the token-signing certificate:

  1. In the AD FS management console, select ‘Certificates’ in the left-hand treeview
  2. Right click the active 'Token-signing' certificate
  3. Select 'View Certificate'
    AD_FS_Cert_1.png
  4. Select the 'Details' tab and choose 'Copy to File...'
    AD_FS_Cert_2.png
  5. The 'Certificate Export Wizard' opens, click 'Next'.
    Select 'Base-64 encoded X.509 (.CER)' and click 'Next'.
    AD_FS_Cert_3.png
  6. Save the file to a location of your preference, for example in 'C:\tokencertificate.cer'
  7. Click 'Next' and 'Finish'.
  8. Now open 'Notepad' and load the exported certificate (for example 'C:\tokencertificate.cer').
  9. You will now see the text contents, in the following format:
    -----BEGIN CERTIFICATE-----
    ..........DATA.............
    -----END CERTIFICATE-----

    You will need this in step 3 to configure the GoBright portal.

Determine the AD FS service url's:

Please determine the service url's of your AD FS installation.

Determine the 'Single Sign-on service url':

  • Mostly the 'Single Sign-on service url' is in the following format:
    https://[adfs service url, e.g. adfs.company.com]/adfs/ls
  • A real world example would be: https://adfs.company.com/adfs/ls

 Determine the 'Single Logout service url':

  • The 'Single Logout service url' is the 'Single Sign-on service url', plus the following extension: /?wa=wsignout1.0
  • The full format would then be: https://[adfs service url, e.g. adfs.company.com]/adfs/ls/?wa=wsignout1.0
  • A real world example would be: https://adfs.company.com/adfs/ls/?wa=wsignout1.0

You will need this information in step 3 to configure the GoBright portal.

Please proceed to step 3.

Step 3: Configure the SAML integration in the GoBright portal

In step 2 you have configured the IdP, and as a result you will have 3 pieces of information:

  • Single Sign-on service url 
  • Single Logout service url
  • Token-signing certificate

Now you need to configure the last steps in the GoBright portal:

  • Go back to the GoBright portal, log in with a manager user if you we're not already
  • Go to Settings > Integrations
  • Open the 'SAML' integration that was created in step 1.
  • Now fill the fields with the related data:
    • Single Sign-on service url 
    • Single Logout service url
    • Token-signing certificate
  • The 'Related Exchange / Office365 integration' should be set to the Exchange/Office365 configuration that is configured in the portal and where these users are having there mailboxes.
  • For enabling automatic user creation please refer to 'step 4' below.
  • The 'direct login url' is a link you can publish on, for example, your intranet. This link will automatically refer to the configured SAML integration and do a direct login. If a user wants to login without a 'direct login url' he can go to www.gobright.com, choose 'Login' and enter it's emailaddress. Based on the email address the login process will be started.

Step 4: Enabling automatic user creation

To enable automatic user creations, there are two steps involved:

  1. Configure the SAML integration with automatic user creation enabled, and choose the default role for automatic created users.
  2. The platform needs to know which company domains are related to your environment, for example: '@company.com'.

    Please provide these domains to GoBright via the request form.
    Supply the following in your request: your organization, the domains you want to use for automatic user creation.
    Please request this via this form.

    When provided GoBright will configure this, and provide you with feedback.

Troubleshooting

Troubleshooting AD FS

When the SAML process does not work, or gives unexpected errors, the easiest way to review what problems there might be is the Windows Event Log.

  1. Login to your AD FS server
  2. Start Event Viewer (run Administrative Tools > Event Viewer)
  3. Select in the left-hand treeview: Applications and Services Logs > AD FS > Admin 
  4. Probably you will see the issues right away in the topmost items, but if you don't see it, you can use the 'Find' options in the right-hand 'Actions'. Then search for the term 'SAML'.

AD_FS_EventViewer_1.png

 

0 out of 0 found this helpful