Authentication and authorization in Niagara can be controlled using Azure.  The following guide shows how SSO for users of our Niagara software was configured.  In our environment, the configuration involves on-premises Active Directory, our Azure tenant and our Niagara system.

 

 

Two groups had been created in on-prem AD.

 

 

 

Two User Prototypes had been created within our Niagara system, by logging into the supervisor station and adding the following objects.  Note that each respective on-prem AD group name matches its associated Niagara system User Prototype name.

 

 

 

The enterprise application entry named Niagara was created as shown.  Note that we leverage an Azure sync agent, which runs on a domain controller and synchronizes objects and attribute values between on-prem AD and our Azure tenant.

 

Below is the SAML setup overview in Azure.

 

 

The Niagara SAMLAuthenticationScheme was added to our supervisor station.  Also added to this station is the SAMLAttributeMapper object.

 

Note the Entity ID matches the Azure SAML configuration's Entity ID value above.  IdP Host URL matches the Login URL protocol and domain values in the Azure SAML config and IdP Login Path matches the Login URL path value in the Azure SAML config.

 

 

 

The IdP Cert was created in Azure and imported into our Niagara system's Platform Certificate Management.

 

In Azure, the SAML Signing Certificate was created and it's Base64 encoded file downloaded.

 

 

 

In Niagara, the downloaded certificate is imported into the User Trust Store of the Platform's Certificate Management space.

 

 

 

Our Niagara system is reachable at the URL https://bms.uscsd.k12.pa.us, which presents the user's web browser with a third party certificate.  This certificate is additionally used by Niagara to sign SAML requests.  This certificate was selected in the SAML Server Signing Cert selection box, which is populated with certificates found in the User Key Store within the Platform's Certificate Management space. 

 

 

 

 

 

Note that although a certificate is selected in the SAML Server Signing Cert selection box, Azure is not configured to ensure SAML requests from Niagara have been signed using this certificate.

 

 

 

Claims sent by Azure to Niagara must be defined within Azure.  These claims include multiple user claims and a single group claim.

 

A group claim has been created, which is the reason the Add a group claim button is greyed.

 

The claim's name was customized as being groupid as shown in the Customize the name of the group claim section.  Note that I've chosen to limit group names to come from only those groups assigned to the Azure Niagara enterprise application by selecting Groups assigned to the application.   The Source attribute selection of sAMAccountName ensures the group name is sent in a format that matches the Niagara configuration.

 

 

 

Above, it was mentioned that I'd chosen to limit group names to come from only those groups assigned to the Azure Niagara enterprise application.  The Users and groups selections and Assignment required? selection in Properties shown below speak to that configuration.

 

 

 

 

 

Claims send by Azure must be mapped to associated Niagara attributes.  Doing so allows Niagara to provision an account, populate the account with values such as name and email address, and assign the account to a User Prototype. 

 

The SAMLAttributeMapper is configured to associate Azure claims groupid, email, username and fullname with Niagara user account attributes.

 

 

 

When a user logs into Niagara by selecting the Log in using SSO account button, Niagara creates the user and populates the Niagara user account with the values from Azure.

 

Note that the button text was defined at the supervisor station's SAMLAuthenticationScheme in the Login Button Text field.

 

 

 

Reviewing the UserService listing of users shows that the user jdoe was created, as this user had logged into Niagara just prior to user account creation.

 

 

 

If troubleshooting is needed, Niagara offers tools for reviewing system activity.  Using a web browser extension that reveals SAML transactions is helpful as well.

 

By logging into the supervisor station and opening Spy, you can adjust the logging and logging levels in order to capture authentication related events.

 

 

 

Within logSetup, setting the saml logging level to ALL will reveal all SAML related events seen by a Niagara system.

 

 

 

Logged events are seen by logging into the Platform and opening Application Director.  The SAML related events shown below include the raw response from Azure and the XML-formatted response from Azure.  Following the XML-formatted response, each claim Azure has sent to Niagara is shown.

 

Note that the email claim and its associated attribute value [email protected] is shown.

 

The grouid claim attribute value Niagara_ReadOnly tells Niagara to assign this user account to the Niagara_ReadOnly User Prototype.  Also note the line reading 'found prototype value', which indicates that Niagara has taken the groupid value and matched it to the aforementioned User Prototype found in Niagara. 

 

The fullname claim and username claim attribute values are also used by Niagara to populate the user's account.

 

 

 

A Firefox extension named SAML-tracer was used to discover the claims and associates attribute values being received from Azure and posted to Niagara.  Some XML tags of interest include Audience, which shows the SAML endpoint consuming the claims being sent by Azure.  Note that this matches the Entity ID value (https://bms.uscsd.k12.pa.us/saml/) defined in the Niagara station's SAMLAuthenticationScheme menu.

 

Also shown are the claims and their respective attribute values - email, groupid, username and fullname.

 

 

 

I hope this guide helps people configure a SAML based SSO experience for their Niagara system.