Azure Single Sign On using SAML

Introduction

The Azure Single Sign On (SSO) using Security Assertion Markup Language (SAML) is a proof of concept of an Iguana log-in with Azure Active Directory using a Service Provider (SP)-initiated workflow.

To get a better understanding of SAML and Service Provider-initiated workflow, see https://developers.onelogin.com/saml.

Using the Code [top]

To implement the POC, you will have to complete 3 steps:

  1. Configure Iguana (User roles, channel groups, SAML Channels)
  2. Create Non Gallery Application (NGA) in Azure Enterprise Apps
  3. Set up the NGA (User roles, SSO)

1. Configure Iguana

  1. On the server that contains Iguana, we must first install Python. The POC relies on Python for two tasks: a) the deflation of the request and b) the response signature validation. This has two implications:
    • Any new environment will require that Python is installed. You’ll just have to download the MSI (x86 or x64) installer, click it, and it will take care of the rest. Here is a link to Python 2.7.14. The install directory will need to be added to the configuration file (see Step 1.3).
    • The new environment will also need to have the signXML library. Installation is straightforward. You can do this by just typing ‘pip install signxml’ into CMD. If pip is not readily available, navigate (cd) to the Python install directory in the Scripts folder (ex. ‘C:\Python27\Scripts’) and then run the command.

      Note: The functionality of the SAML channels that are used in the POC have only been tested using Python 2.7.14.

  2. Once Python and signXML are installed, Import the SAMLAssertion and SAMLUser channels from the Interfaceware Support repository.
  3. Once imported, navigate to the SAMLUser channel script and locate the shared/SAMLConfig.lua file. The descriptions of the variables of importance can be seen below. In addition, the values with an asterisk (*) must be configured for the SAML channels in any given environment.
    • IGUANA_URL*: The URL of the Iguana that contains the SAML channels.
    • Audience: The identifier of the external app (used in Azure SSO settings).
    • ACS_URL: This is the Assertion Consumer Service URL indicating where the Assertion will be consumed. It is configured as the URL of the channel receiving the response
    • Issuer*: This refers to the issuer we expect for the response and the assertion. This value can be obtained in Section 4 of the NGA’s SSO settings under “Azure AD Identifier”.
    • IDP_URL*: This is the Login URL supplied by Azure. This value can be obtained in Section 4 of the NGA’s SSO settings under “Login URL”.
    • replayStoreName*: The name of the replay store. This can remain the same.
    • requestStoreName*: The name of the request store. This can remain the same.
    • certLocation*: The SAML certificate used for validation. The production cert can be obtained from section 3 of the NGA’s SSO settings. Simply copy the cert and paste into a text file. Then update this certLocation variable.
    • signxmlLocation*: This is the path to the signxml library
    • pythonLocation*: This is the path to the Python installation directory
    • pyScrLocation*: This is where the Python scripts will be saved. It is set to be the Iguana working directory by default.
    • pwDirectory*: The directory of the master password used for authenticating all user accounts on the Iguana excluding the Administrator account.

      Note: The location of the Azure AD Identifier, Login URL, and SAML certificate can be found by following Microsoft’s SSO set up instructions below in step 3: Set up the NGA

  4. After updating the config file, create the roles that will be used for Iguana (e.g. Programmer, LogUser, Support), and assign them all a master password that will be saved as an encrypted file in the pwDirectory.
  5. Lastly, create a self signed certificate to authenticate Iguana’s application URL and port, and for Iguana’s http port.

2. Create Non Gallery Application

In order to create a Non Gallery Application in Azure, please follow Microsoft’s official instructions here: https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/add-non-gallery-app.

3. Set up the NGA

  1. https://docs.microsoft.com/en-us/azure/active-directory/manage-apps/configure-single-sign-on-non-gallery-applications. In order to complete the SSO, the parameters in the chart below will be required. Replace “localhost:6544” to correspond to your Iguana’s IP address and https port if different.
  2. https://docs.microsoft.com/en-us/azure/active-directory/fundamentals/active-directory-users-profile-azure-portal

At this point, the POC workflow can be tested out by initiate the log-in procedure. This can be done by visiting: https://<Iguana_URL>:<https_channel_port>/SAMLUser/. If you are already logged in, you will immediately be redirected to the dashboard. Otherwise, you will be asked to log in to a Microsoft log-in page.

For reference, the main functions of the SAMLUser and SAMLAssertion Channels can be found below respectively:

SAMLUser main.lua:

SAMLAssertion main.lua:

How it works [top]

The workflow is designed to allow users to log into Iguana through Azure Active Directory and to be directed to Iguana with a user associated with their AD profile under the “department” category. Under SAML definitions, Iguana is the service provider (SP) and Azure AD is the Identity Provider (IdP).

The Iguana has roles, each associated with one or many users. These users correspond to the departments in the Azure AD user profile page.

The implementation is carried out over two channels:

  • SAMLUser: This channel generates a request and redirects the user to the IdP log-in page.
  • SAMLAssertion: This channel receives back a response containing an assertion from the IdP. The response and assertion are validated and the attributes in the response can then be used to grant the user access.
    • Currently, the PoC uses the department returned in the attributes to log the user in.  Alternatively, the attributes can be used for something else (like authenticating API calls or pulling patient-specific data).

More information [top]