HomeGuidesAPI
HomeGuidesRecipesAPI
HomeGuidesAPILog In
Guides
These docs are for v16. Click to read the latest docs for v31.

SAML 2.0

Suggest Edits

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.

852

📘

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.

932
  1. Provide the necessary information. Refer to your Identity Provider's documentation for configuration and settings. For example: Okta or Azure Active Directory.
SettingDescription
SAML 2.0Provides the option to use SAML 2.0
Create UsersProvides 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 URLEnables 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 URLThe 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 AlgorithmProvides a selection of hashing methods for the SAML logout request to use with the above certificate.
Log ModeEnables 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 LoginDisplays 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.

920

Available User Profile Mapping Fields:

SettingDescription
User NameA 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.
GroupsThe 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
CultureA culture code to use for example en-AU, zh-CN, es, etc
LanguageA 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 ZoneAn 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.

Updated over 2 years ago