HomeGuidesRecipesAPI
HomeGuidesAPILog In

Overview

SmartIQ supports SAML 2.0 which is an open federation standard that allows an identity provider (IdP) to authenticate users and pass identity and security information between SmartIQ and other service providers (SP) enabling Single Sign-On (SSO) and Single Logout (SLO).

The diagram below shows how the SP-initiated SAML flow works.

852852

📘

Note

SmartIQ supports both SP-initiated and IdP-initiated SAML flows. This means users can either login from the IdP login page and redirects to SmartIQ or users login from SmartIQ and redirects to the IdP page.

Single Sign-On (SSO)

SmartIQ supports the use of IdP for authentication to enable access without the need to re-key credentials when an existing session is present.

When a user attempts to log in, SmartIQ uses HTTP Redirect to pass an authentication request to the IdP. The IdP determines whether the user has already been authenticated or requires login. After login, the IdP sends an HTTP post binding back to SmartIQ with the status of the login and some additional metadata about the user.

Single Logout (SLO)

Typically, service providers use session cookies to keep sessions open when authenticated through an IdP for SSO. Once users logout of the IdP, most users assume that all sessions have been logged out. However, individual session cookies are valid until expired.

With SLO, when the user indicates they wish to logout, SmartIQ supports SAML Single Logout to completely close all sessions from all service providers.

Prerequisites

  • An existing SmartIQ environment installed with default Forms Authentication.

  • A SAML 2.0 provider with an Identity Provider (IdP) configured to:

    • (Mandatory) Return a group membership as an assertion attribute (for example, IsMemberOf) to ensure that at least one user can be added to a SmartIQ Administrator Role after switching to SAML
    • (Optional) Return profile information such as first and last name

📘

Refer to your respective identity provider’s documentation for configuration settings. For example, Okta or Azure Active Directory.

  • Identity Providers for both SmartIQ Manage and Produce whereby:
    • The response is configured to be sent via HTTP-Redirect to: http://yourserver/Manage/account/samlauthenticate or http://yourserver/Produce/account/samlauthenticate respectively
    • The HTTP-Redirect or HTTP-POST response is signed.
    • A meaningful name is given to the Service Providers (usually Produce and Manage)
    • A certificate either installed on the SmartIQ web server or uploaded as file that can be used to check the SAML response signature (i.e. the certificate used by the IdP to sign the response).
    • A user configured in the SAML 2.0 provider for testing that is a member of at least one known group.
    • For single logout service, the Identity Provider should have the Single Logout Service response configured to be sent via HTTP-Redirect to: http://yourserver/Manage/Account/SamlLogout or http://yourserver/Produce/Account/SamlLogout respectively
    • Pass through of Relay State must be enabled in the Identity Provider if the use of deep links is desired.

Terminology may vary among different Identity Providers, so check the Identity Provider documentation if you are not sure what values should be configured in SmartIQ and in the Identity Provider

SAML Authentication in Multi-Tenant Environments

To allow navigation to a specific tenancy and to authenticate using SAML instead of forms authentication:

  • When navigating to a specific form, SmartIQ is able to determine the tenancy of that form and will, therefore, use the authentication method defined by that tenancy.

  • A TenantId may be used to specify what tenancy to log in to if navigation to the Produce home page is required. The produce homepage in this situation will be the normal home page with "/b/" appended to the URL.

For example, if Produce is normally http://IQtransform.com, then a specific tenancy can be navigated to at http://IQtransform/b/12345, where the tenant id is 12345.

📘

Once a SAML Produce instance is navigated to, a cookie will be stored on that computer and will remember that SAML login is preferred when accessing that instance of SmartIQ. In this situation, in the unlikely situation where forms authentication is desired, the SAML tenancy must be logged out and cookies cleared.

SmartIQ Configuration

Step 1 - Identify a SAML Administrator Group

When the first user (usually a server administrator) attempts to access SmartIQ via SAML Authentication, SmartIQ needs to assign permissions to an External Group so they can access appropriate functions. If this step is not completed, user will not be able to administer anything post authentication.

Step 2 - Enable and Configure SAML

  1. Open the SmartIQ Manage application and log in as an Administrator with Change settings permission.

  2. Click Settings > SAML 2.0.

932932
  1. Provide the necessary information. Refer to your Identity Provider's documentation for configuration and settings. For example: Okta or Azure Active Directory.

Setting

Description

SAML 2.0

Provides the option to use SAML 2.0

Create Users

Provides the option to create a user in the SmartIQ platform. If unchecked, the user must already exist in SmartIQ to be able to login.

Manage Entity Id (Mandatory)

The Entity Id of the Manage Service Provider. For example, Manage, ManageTest, ManageProd Etc.

  • For Azure Active Directory, the Application (client) ID will be the Manage Entity Id and Produce Identity Id.
  • For OKTA, this is the Audience URI (SP Entity Id).
    • For Single Sign-Out, the Manage entity ID should match the SP issuer in Okta if you are setting up SAML Login for Manage.

Note: This needs to be different from the Produce Entity Id.

Produce Entity Id (Mandatory)

The Entity Id of the Produce Service Provider. For example, Produce, ProduceTest, ProduceProd Etc.

  • For Azure Active Directory, the Application (client) ID will be the Manage Entity Id and Produce Identity Id.
  • For OKTA, this is the Audience URI (SP Entity Id).
    • For Single Sign-Out, the Produce entity ID should match the SP issuer in Okta if you are setting up SAML Login for Produce.

Note: This needs to be different from the Manage Entity Id.

Metadata URL

Enables reading information about the requirements of the service from this URL.

  • For Azure Active Directory, paste the Federation Metadata Document.

Clicking Save after typing the Metadata URL will automatically populate the available fields.

Identity Provider Issuer (Mandatory)

The Issuer ID of the Identity Provider. For example, http://openam.example.com:8080/openam

  • If using Okta, this information is labelled as “Identity Provider Issuer” when you click the “View Setup Instructions” button within the Settings page in Okta.

Identity Provider Login URL (Mandatory)

The URL of the Single Sign on Service URL that SmartIQ will make the Redirect Request to. For example, http://openam.example.com:8080/openam/SSOPOST/metaAlias/idp

  • If using Okta, this information is labelled as “ Identity Provider Single Sign-On URL” when you click the View Setup Instructions button within the Settings page in Okta.

Identity Provider Logout Binding (Mandatory)

Logout binding determines which binding will be used when a request is made. SmartIQ supports both REDIRECT and POST. The correct option is dependent on what your IDP is expecting.

  • HTTP-Redirect (Default) – A Logout request using its signature to pass an authentication request element to the identity provider
  • HTTP-POST – A Logout Request with the embedded signature

Identity Provider Logout URL

The URL of the Single Sign Out Service in IDP that SmartIQ will make a logout request to.

Identity Provider Certificate (Mandatory)

The certificate SmartIQ will use to check the signature received in the HTTP-Redirect Response.

A certificate can be installed in the server and referenced by a thumbprint or uploaded directly to the application.

SmartIQ Signing Certificate
(Mandatory) if Identity Provider Logout URL is provided.

The certificate SmartIQ will use to create the signature for the logout request.

A certificate can be installed on the server and referenced by a thumbprint (preferred) or uploaded directly to the application (not recommended as this requires the private key to be included without the password).

For logout requests, the certificate to sign the logout request with so that the IDP knows it came from the correct source.

SmartIQ Signing Algorithm

Provides a selection of hashing methods for the SAML logout request to use with the above certificate.

Log Mode

Enables capturing a more verbose description of all events during a SAML authentication (i.e. success and fail) that can be viewed in the Event Log. Useful for fault-finding new implementations.

Last Failed SAML Login

Displays the last failed message, if logging has been turned on.

Step 3 - User Profile Mapping

As attributes specified in a SAML response are arbitrary, it is necessary to map particular user profile fields to the values provided in the SAML response.

  1. Open the SmartIQ Manage application and log in as an Administrator with Change settings permission.

  2. Click Settings > User Profile Mapping.

  3. Provide at least the name of the attribute where the user’s Group Memberships are specified. Optionally specify any other user fields.

920920

Available User Profile Mapping Fields:

Setting

Description

User Name

A field to use for the SmartIQ Username if the default SAML ‘NameID’ element does not contain a meaningful value. This is a required field.

For example, use the email address.

Groups

The element to look for the user’s group Memberships.

Prefix, Job Title, Organization,
Last Name, Phone Number, Full Name, Fax Number, Email, Address Line 1,
Address Line 2, Suburb/Town/City,
State/Province/Region, Postal/Zip Code,
Country

Regular fields

Culture

A culture code to use for example en-AU, zh-CN, es, etc

Language

A language to use must be supported by SmartIQ. Possible values:

  • ar
  • zh-cn
  • zh-tw
  • nl
  • en
  • en-us
  • fr
  • fr-ca
  • de
  • ko
  • pt
  • es
  • th

Time Zone

An appropriate user time zone. Possible Values:

  • Dateline Standard Time
  • UTC-11
  • Samoa Standard Time
  • Hawaiian Standard Time
  • Alaskan Standard Time
  • Pacific Standard Time (Mexico)
  • Pacific Standard Time
  • US Mountain Standard Time
  • Mountain Standard Time (Mexico)
  • Mountain Standard Time
  • Central America Standard Time
  • Central Standard Time
  • Central Standard Time (Mexico)
  • Canada Central Standard Time
  • SA Pacific Standard Time
  • Eastern Standard Time
  • US Eastern Standard Time
  • Venezuela Standard Time
  • Paraguay Standard Time
  • Atlantic Standard Time
  • Central Brazilian Standard Time
  • SA Western Standard Time
  • Pacific SA Standard Time
  • Newfoundland Standard Time
  • E. South America Standard Time
  • Argentina Standard Time
  • SA Eastern Standard Time
  • Greenland Standard Time
  • Montevideo Standard Time
  • UTC-02
  • Mid-Atlantic Standard Time
  • Azores Standard Time
  • Cape Verde Standard Time
  • Morocco Standard Time
  • UTC
  • GMT Standard Time
  • Greenwich Standard Time
  • W. Europe Standard Time
  • Central Europe Standard Time
  • Romance Standard Time
  • Central European Standard Time
  • W. Central Africa Standard Time
  • Namibia Standard Time
  • Jordan Standard Time
  • GTB Standard Time
  • Middle East Standard Time
  • Egypt Standard Time
  • Syria Standard Time
  • South Africa Standard Time
  • FLE Standard Time
  • Israel Standard Time
  • E. Europe Standard Time
  • Arabic Standard Time
  • Arab Standard Time
  • Russian Standard Time
  • E. Africa Standard Time
  • Iran Standard Time
  • Arabian Standard Time
  • Azerbaijan Standard Time
  • Mauritius Standard Time
  • Georgian Standard Time
  • Caucasus Standard Time
  • Afghanistan Standard Time
  • Ekaterinburg Standard Time
  • Pakistan Standard Time
  • West Asia Standard Time
  • India Standard Time
  • Sri Lanka Standard Time
  • Nepal Standard Time
  • Central Asia Standard Time
  • Bangladesh Standard Time
  • N. Central Asia Standard Time
  • Myanmar Standard Time
  • SE Asia Standard Time
  • North Asia Standard Time
  • China Standard Time
  • North Asia East Standard Time
  • Singapore Standard Time
  • W. Australia Standard Time
  • Taipei Standard Time
  • Ulaanbaatar Standard Time
  • Tokyo Standard Time
  • Korea Standard Time
  • Yakutsk Standard Time
  • Cen. Australia Standard Time
  • AUS Central Standard Time
  • E. Australia Standard Time
  • AUS Eastern Standard Time
  • West Pacific Standard Time
  • Tasmania Standard Time
  • Vladivostok Standard Time
  • Central Pacific Standard Time
  • New Zealand Standard Time
  • UTC+12
  • Fiji Standard Time
  • Kamchatka Standard Time
  • Tonga Standard Time
  1. Click Save.

Step 4 - Test

  1. Close all browsers to ensure any existing SmartIQ sessions are removed.

  2. Open a new browser and navigate to SmartIQ Manage or Produce.

SmartIQ will create a SAML session as per the configured settings. If logging in for the first time, the Identity Provider's Login screen should appear or, if you already have an existing session, you should be redirected to the Produce or Manage Home page.

  1. Log out of SmartIQ Manage or Produce. You should be redirected to the Logout URL page.

Troubleshooting

There are a number of SAML browser inspections extensions (eg: SAML Chrome Panel etc) that can be used to trace the SAML flow and allow inspection of the requests and responses sent back and forth between the browser, SmartIQ and the Identity Provider.

We recommend the use of some sort of inspection tool if you are experiencing difficulties with SAML.