Note: Nintex Apps data centers are located in West US and Australia (AUS). In-region processing of Nintex Apps data is only available in these regions.

Single Sign-On

Single sign-on (SSO) refers to the practice of using a single authentication service to log into other services. Nintex Apps's implementation of SSO uses then XML-based Security Assertion Markup Language (SAML). This authentication protocol is used by many services to allow end users to log into an identity provider (IdP) that grants them access to multiple different services, known as service providers (SP).

With SSO, a log-in process can be IdP-initiated or SP-initiated:

IdP-initiated: Users login once to their IdP, where they enter their unique username and password. Users then select the service they wish to access and are then logged in, without having to enter a username/password for the chosen service.
SP-initiated: User starts at the service provider's login page and chooses to login using a known IdP.

Alternatively, a user may navigate to a service provider from another portal or hub besides the IdP. They then can then choose to login using a known IdP.

Nintex Apps supports both IdP-initiated and SP-initiated logins. By ensuring users have one method of entry into various services, authentication becomes a more streamlined—and arguably more secure—process.

Both Nintex Apps and Nintex Apps for Salesforce can be used with the SAML protocol. By configuring Nintex Apps for SAML, you can allow your users to login into Nintex Apps with the click of a button. You can also authenticate your end users to connections used in Nintex Apps pages.

Prerequisites

When using SAML to connect to Nintex Apps —or your connections—the actual screen-by-screen experience will vary depending on which single sign-on services you utilize. Work closely with an administrator who is familiar with SSO as a concept, as well as your identity provider of choice. Included in the collapsed section below is a reference of concepts, phrases, and acronyms commonly seen throughout this process.

Concepts and definitions to know

Single Sign-On (SSO): The actual process of logging into an identity provider to access multiple service providers.

Security Assertion Markup Language (SAML): An XML-based standard for SSO. Nintex Apps only supports SAML 2.0.

Identity Provider (IdP): An application that defines your end users and which applications/services these users are able to access. Examples include:

Azure Active Directory
Okta
Ping Identity
OneLogin

Additionally services like Salesforce and Google Apps may be used as IdPs.

Service Provider (SP): The services being accessed by the IdP. This can include Nintex Apps, Google apps, Salesforce, or other services.

Assertion: The term used for the XML message IdPs send to SPs to authenticate. Assertions contain several necessary authentication values used for logging in, as well as user provisioning when enabled.

IdP metadata files: A file provided by an IdP describing what is contained within the XML of its authentication assertion. These files contain the following:

Entity ID: Tells the service provider who the IdP is.
Certificates: One or more security certificate used for identifying the IdP and encrypting/decrypting SAML messages.
Single sign-on location URL: A URL that the SP can redirect a user to in order to initiate SSO. If the user has not logged in to the IdP yet, they will be prompted to login, otherwise they will be redirected back to the SP's ACS URL with an assertion.

Assertion Consumer Service (ACS) URL: The URL where an IdP will send an assertion for an SP to consume and properly authenticate users.

Service Provider Entity ID / Audience URI: The SP entity ID is a unique identifier for a service provider, often written in the form of a URI. Because of this convention, it's common for this value to also be the service provider's audience URI, which is states the intended audience of a SAML assertion. Audience URIs are also sometimes referred to as an audience restriction, referring to its use within the AudienceRestriction tag.

The entity ID and audience URI serve as verification mechanisms to help ensure an assertion is received by the appropriate service provider. Your IdP requires these values to properly send its assertions.

Nintex Apps uses the same value for an IdP connection's entity ID, audience URI, and as the location of its service provider metadata. This XML file can be used to simplify registration of Nintex Apps as a service provider in many identity provider systems.

Federated SSO and Federation ID (FID): In federated SSO, the IdP serves as a singular entry point to a group—or federation—of applications. To accomplish this, the IdP and SP will typically communicate a federation ID, which is a trusted piece of data—known to both systems—that can identify individual users.

The SP will receive a federation ID from the IdP, and it will trust that the end user has been properly authenticated. In practice, this means some SPs will not require a password to authenticate a user if it receives the proper FID, and sometimes a password may not even exist.

Within Nintex Apps, users' federation IDs are set when a user is provisioned and can be updated by Nintex Apps admins at any time.

Creating A New Identity Provider Connection

Navigate to Settings > Single Sign-on.
Click Create identity provider or, if some IdP connections already exist, click Create in the Identity Providers section.
Give the IdP connection a name.
Confirm the name by clicking Create.

The IdP connection details appear in a pending state, as Nintex Apps needs additional information from your IdP to complete the setup. A Setup in progress badge will appear beside the IdP connection while it's in this state.

Three useful URLs appear for setup within your IdP:

The Entity ID
The Assertion Consumer Service (ACS) URL
The metadata file

These values are used when configuring Nintex Apps as a service provider within your IdP. Typically your IdP only needs your entity Id and ACS URL. Some services allow the use of a metadata file for expedited setup.

Adding identity provider details

After initial setup using an entity ID and ACS URL in the IdP, Nintex Apps needs some information from the IdP to complete the connection. Many IdPs provide a metadata file that conveys the other nuances of connecting to that service. Nintex Apps can parse these metadata files by uploading them directly or accessing it via a URL. Finally, it's also possible (through not typically recommended) to configure these IdP connection values manually.

These settings are configured in the Identity provider details section, after clicking Add details. Details can be added in one of the following ways:

Import from identity provider metadata file: Nintex Apps uses the metadata file from your IdP to automatically configure all of the necessary fields. Download the metadata file from your IdP and use this option to upload it.
Import from identity provider metadata file - from specified URL: Nintex Apps will use the metadata file from your IdP to automatically configure all of the necessary fields. Insert the URL that points to your IdP's metadata file.
Enter information manually: Configure the necessary IdP details manually.

Using your IdP's metadata file is the recommended way to create your identity provider connections.

Identity provider details

Each IdP connection in Nintex Apps has the following details:

Entity Id: The unique identifier for your IdP, frequently in URL format. This is sent by Nintex Apps as part of SAML exchanges, and is used by Nintex Apps to validate that a SAML message came from an authorized IdP.
Login URL: A URL from your IdP that Nintex Apps can use for SP-initiated SSO (i.e. this is the URL that the Login with SAML link on the login screen will go to).
Logout URL: While neither IdP nor SP-initiated single logout are currently supported, values stored in this property may be used for future single logout enhancements. This value cannot be specified manually.
Identity provider certificates: Any necessary certificates used to communicate with the IdP service.

Identity mapping

Identity mapping tell Nintex Apps how to parse the SAML assertion from the IdP. This allows Nintex Apps to do two things:

Extract a piece of information from the assertion that uniquely identifies the user.
Match this identity information with a corresponding attribute on an existing user record.
If user provisioning is enabled, a new Nintex Apps user is provisioned if the identity in the assertion does not correspond to an existing Nintex Apps user.

Identity mappings are created in a sentence-like format, composed of the following sections:

Subject name identifier / SAML attributes: Determines which piece of information Nintex Apps extracts to identify the user.
- Subject name identifier: When your IdP sends a SAML assertion to Nintex Apps in response to a user's request for SAML identification, this assertion will always include a "Name Identifier" element within a "Subject" statement. Generally, an IdP can be configured so that this Name Identifier element will contain the user's Nintex Apps username, and most SSO Configs will use this NameIdentifier option.
  - with a format of: Determines the format Nintex Apps can expect the name identifier element to take. Select this option based on your IdP's configuration so Nintex Apps can properly parse the identifier value.
    - For more information on name identifier formats, see section 8.3 of the Assertions and Protocols for the OASIS Security Assertion Markup Language (SAML) V2.0 document.
- SAML attribute: IdPs generally send various attributes about the user, such as the First Name, Last Name, Email, or a Federation Identifier, within various Attribute elements in the assertion. If the NameIdentifier element does not contain the necessary identity information, Nintex Apps will need to identify the user by examining one of these attribute elements.
  
  When selected, a second input appears where you must specify the name of the attribute that contains the desired identification element.
- matches Nintex Apps user ...: Determines which Nintex Apps user attribute the given information from the IdP should match. Options include:
  - Username
  - Federation ID
  - Email Address
    
    Note:
    When validating identity based on email address, you cannot have more than one user with the same email address. Nintex Apps cannot reconcile which user to authenticate as, because the email is not unique.
    
    Users who share an email will see errors when logging in via the IdP. Manually update any duplicate emails so that each user has a unique email, or consider using a different attribute for the identity mapping.
  - User Id
- Case-sensitive: Determines whether or not upper/lowercase letters should be recognized as unique.
  
  When enabled, example and Example are treated as unique values.
  
  When disabled, example and Example are treated as the same value.

Provisioning

The Provisioning tab contains properties and settings related to the management of Nintex Apps user data in relation to IdP user data. This typically involves creating Nintex Apps user accounts when users log in from an IdP, or updating a Nintex Apps user's account information to match what's sent in the SAML assertion.

Just-in-time user provision

With this property enabled, your Nintex Apps site will automatically generate new end user accounts for anyone that tries to authenticate through your IdP if their account does not already exist.

While the specific process varies depending upon the IdP, user provisioning always requires several attributes be set upon user creation. These attributes can be set via a SAML attribute ( <saml:Attribute /> nodes within the <saml:AttributeStatement /> ) or as a result of a formula.

Required properties include:

First Name
- Typically found within an attribute named one of the following:
  - User.FirstName
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname
Last Name
- Typically found within an attribute named one of the following:
  - User.LastName
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname
Email: The new user's email address, to which all user-related communications will be sent. Does not need to be unique.
- Typically found within an attribute named one of the following:
  - User.Email
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress
Username: Used for logging in to your Nintex Apps site. Must be unique within your site. Ensure that this username follows whatever standardized format you wish to follow on your site.
- Typically found within an attribute named one of the following:
  - User.Username
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier
Time Zone: The user's time zone.
Locale: The user's preferred language/region.
User type: The Nintex Apps subscription user category the user should be assigned fall into.
Site permission set name: The site-wide permission set assigned to the user.
Federation Identifier: Used for uniquely identifying a user across multiple service providers. If not provided separately from username, this will be extracted from the same set of attributes used for username.
- Typically found within an attribute named one of the following:
  - User.FederationId
  - User.Username
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
  - http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier

How you configure your assertion to include these values will vary from IdP to IdP.

Note: Any end users created through SSO provisioning will not have passwords on Nintex Apps; Nintex Apps authenticates any SSO-provisioned users differently. Therefore they cannot access Nintex Apps any other way than through the IdP (IdP-initiated SSO) or the Login with SAML link on the Nintex Apps Login page (SP-initiated SSO).

When existing users log in, automatically update properties mapped to SAML attributes and formulas with the latest information from your site's identity provider. This ensures Nintex Apps user data always matches any updates a user may make to their information in the IdP system.

When enabled, users whose Nintex Apps accounts were previously deactivated will have the accounts reactivated when logging in through this IdP. This allows for pruning of inactive users (for Nintex Apps subscription purposes), while not blocking any users that may eventually log back into the platform.

Certificates

By default Nintex Apps does not sign SAML request using a certificate. This behavior can be adjusted in the Certificates tab, which lists the following certificate-related properties:

Request Signing Certificate: For increased security, you can use your Nintex Apps site's default certificate, or create a custom certificate, sign SAML requests.

Note: Whichever certificate you choose for request signing must be downloaded and uploaded into your IdP's corresponding service provider configuration. Certificates can be downloaded by going to Settings > Certificates and clicking Download Default Certificate on the certificates table.
Assertion Decryption Certificate: The certificate used to decrypt an encrypted XML assertion from the IdP. You must first create or upload a certificate by navigating to Settings > Certificates, and then return here to select the certificate.
Request Signature Method: Select whether your requests will be signed using the SHA-1 or SHA-256 algorithm.

Logging in via SSO

After configuring Nintex Apps and your IdP, both IdP-initiated and SP-initiated SSO are supported.

IdP-initiated: Within your IdP, you'll configure your Nintex Apps application and access as normal for your particular IdP.
SP-initiated: Once an identity provider connection exists within your Nintex Apps Site's settings, you'll see a Login with SAML link on your Nintex Apps site's login screen.
- If only one identity provider connection exists, clicking this link will log you in directly to Nintex Apps using the one available configuration.
- If more than one identity provider connection exists, clicking this link will display a list of all available SSO providers, so that the end user can select the desired provider.

Session Variables

Session variables provide a way to securely access the values of SAML attributes for logic within Nintex Apps. These extracted values are stored securely and only for the duration of the user's session. Session variables are not tied to individual identity providers; a value must be set for each identity provider connection—enabling their use on sites that have more than one IdP.

These variables are typically used in connection conditions, which are handled server-side by Nintex Apps, to limit data returned to the client. It's also possible to make session variables available client-side. This means that the variable can be used in things like display logic or model conditions. If SAML attributes are a useful means of conditional logic for your application, consider enabling client-side availability, but know that savvy end users could access the value of the variable.

For the security conscious, note that session variable values are only accessible during the user's session, and the values are not visible to the user unless they have been intentionally made available client-side. Nintex Apps does not have direct access to these SAML attribute values, instead passing these values along to Nintex Apps's other functions strictly for evaluating logic.

Important:

Because session variables rely on SAML attribute values, consider setting single sign-on as the default login method and enabling the Hide username and password login property in the Login screen section.

Users who authenticate through username/password will not have a SAML attribute associated with their session—and thus all conditions based on session variables will fail.

Creating session variables

Navigate to Settings > Single Sign-on.
In the Session variables section, click Create session variable / Create >
Configure the variable:
- Variable name: The name to refer the variable by.
- Values: Set which SAML attribute to use for each identity provider connection.
  
  Important:
  Be sure the attribute name exactly matches what is provided in the SAML assertion.
  
  Alternatively, select None - blank value if the IdP does not provide the expected value, though this is typically not recommended. If None is selected, then users logging in through that IdP will typically "fail" any condition using the session variable—such as on connection conditions. Client-side conditions may see other behaviors.
- Available client-side: Makes the session variable available for use in client-side features, like model conditions or display logic. If having the selected SAML attribute available to the user is not acceptable based on security requirements, do not enable this property.
Click Save.

The session variable is created, now available for use within connection conditions and, if enabled, client-side features.

Using session variables

Session variables, by default, can only be used in connection conditions. Variables can be chosen by setting the Value source to Session variable.

It's possible to use session variables in some client-side functionality, like display logic, by selecting Session variable as the value source and then choosing the specific variable.

In other instances it's possible to access session variables through merge syntax:

This is often useful where applications commonly display user information for personalization. For example, if a page serves as the dashboard for several departments (with the aid of conditional rendering), using a session variable in a Header component could be helpful:

{{$Session.variable.Department}} Dashboard

It's also possible to run a branch of actions based on whether or not a user's email contains the domain of an organization.

In this example we'll display a toast message if the user's email contains @example.com . Edit this example to match your expected domain:

Create a session variable named Email mapped to the appropriate SAML attribute.
Create or navigate to a Nintex Apps page.
Click to edit an Action Framework trigger area.
Click add Add action.
Set the newly created action's type to Branch.
Edit the branch's formula by clicking code-block Open Resource Editor.
Enter the following formula:

CONTAINS({{$Session.variable.Email}}, "@example.com")
Click dots-vertical > Add if-true action.
On the newly created if-true action, set the following properties:
- Action type: Show toast message
- Message to display: Confirmed user email!
Click Save.

When the end user activates the trigger area (such as by clicking a button), the branch action checks if the user's email contains @example.com . If it does, a confirmation toast is displayed.

This basic example illustrates how client-side session variables can be used to create branching actions. Adjust as needed to suit your use cases.