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.

SAML 2.0 for Nintex Apps connections

Using OAuth's Authorization Code grant type, Nintex Apps is able to easily connect to a variety of connections and display them in one place. And while the process is already relatively painless—only requiring that end users sign in with their credentials through an OAuth popup window—single sign-on can streamline that process even further. This is accomplished using the SAML 2.0 Bearer Assertion OAuth grant type. In this OAuth flow, Nintex Apps —through your IdP—authenticates users to the individual connections used within your Nintex Apps site without any user intervention.

In practice, this means users would sign in to Nintex Apps through SAML, and then go straight to work in their apps—no other OAuth popup windows or other authentication steps.

Check the documentation of your preferred connection to see what the requirements are for their application and whether it supports this authentication flow.

While this process can vary depending on your use case, there are some common steps. For a specific example, see Accessing a Salesforce org as a Nintex Apps connection with the SAML 2.0 OAuth Flow.

1. Download a certificate for identity verification

Certificates are a key component of the SAML 2.0 Bearer Assertion OAuth grant type, ensuring that your IdP and your connection can mutually identify one another and securely exchange identity information using SAML.

Whichever certificate you choose to use, you will need to identify this certificate in the OAuth client / app connection you'll configure within your connection in Step 4. Configure an authentication provider and connection.

2. Configure your connection and your IdP for SSO authentication

To access Nintex Apps via SAML, you'll need to configure an SSO application within your IdP of choice. However, to take advantage of the SAML 2.0 Bearer Assertion flow with any connection, you must also configure a service provider application for your chosen connection within your IdP, and the corresponding identity provider connection for your IdP within that connection.

These identity provider connections are essential: they enable the connection to delegate authentication of an end user requesting access to its data to the IdP. You'll be using the issuer value from your connection's identity provider connection when configuring your OAuth app connection as well, so take note of this field.

This process will vary from connection to connection, and also from IdP to IdP. Refer to the documentation of the connection and IdP of your choice for more information.

3. Creating an OAuth app connection within your connection

As with other OAuth flows, you'll need to create an OAuth client within your connection application. This OAuth client will then register Nintex Apps as a party authorized to connect to the connection's API. After creating this OAuth client within the connection application, you should receive a client Id and client secret —or similarly named credentials.

You will need to securely store these credentials for later access, as they are needed to configure your connection connection within Nintex Apps.

As part of your OAuth client setup, you will also need to configure SAML-specific settings. This will vary depending on the external connection you are connecting to.

• Salesforce
• SAP
• Microsoft connections through Azure Active Directory

Two of these key settings:

• You must upload the certificate from Step 1. Download a certificate for identity certification within your connection's OAuth client configuration.
• You must use the Issuer field from the identity provider connection within your connection, as described in Step 2. Configure your connection and your IdP for SSO authentication.

With all fields properly configured—and these two essential values in place— the OAuth client connection will facilitate the actual data connection between Nintex Apps and the connection being accessed.

4. Configure an authentication provider and connection

First, create a Nintex Apps authentication provider.

1. Navigate to Settings > Connections > Authentication Provider.

2. Click New Authentication Provider.

3. Fill out the fields as follows:

   • Name: Enter an appropriate name for your authentication provider, such as <Your Connection>SAML.
   • Authentication Method: OAuth 2.0 / OpenID
   • Provider Type: Select the appropriate provider for the connection you're accessing.
   • Grant Type: SAML 2.0 Bearer Assertion
   • Token Endpoint URL: Depending on your external connection, you may need to edit the value of this field, perhaps filling in your My Domain or organization ID.
   • Signing Certificate: Select the certificate you used in the first section.
   • Client ID: Enter the the appropriate id or key of the OAuth client / connected app from the previous section.
   • Client Secret: Enter the enter the appropriate key or secret of the OAuth client / connected app from the previous section.

4. Click Save.

After this, you'll need to create a Nintex Apps connection that uses the above authentication provider to authenticate. Within that connection, also configure the name identifier to use to send in the SAML assertion sent to the external connection—a field that correlates with a user record on the external connection, such as a username, federation identifier, or email address.

1. Navigate to Settings > Connections.
2. Click New Connection.
3. Select appropriate option for your Connector.
4. Enter an appropriate Name for your connection, such as <Your Connection>SAML.
5. Click Next Step.
6. Configure any connection specific options.
7. Click Next Step.
8. Select the authentication provider you configured in the previous section.
9. Click Save new Connection.

After creating this new connection, configure the advanced settings to properly send a username to the external connection you are connecting to. If you do not see the settings listed below, refresh your page.

1. Click Advanced Settings for the newly created connection.
2. Ensure that your Authentication Method is still set for the authentication provider you configured in the previous step.
3. Beside SAML Name Identifier Source or Name Identifier Field, enter a value that will correlate to the name identifier of the org you are connected to. Select an option appropriate for your use case:
   • Email: Use this option to send the email of the current user—on Salesforce or Nintex Apps —as the identifier in the assertion.
   • Federation Identifier: Use this to send the federation identifier of the current user—on Salesforce or Nintex Apps —as the identifier in the assertion.
   • Username: Use this option to send the username of the current user—on Salesforce or Nintex Apps —as the identifier in the assertion.
   • Result of a Formula: If none of the identifiers above directly correlate with the the connection's expected name identifier syntax, you can dynamically generate the expected value with a formula using text transformation functions and merge syntax here. The following functions are available:
     • LOWER(): Will return the parameter in entirely lowercase letters.
     • UPPER(): Will return the parameter in entirely uppercase letters.
     • FIRST(): Will return the first letter of its parameter.
     • LAST(): Will return the last letter of its parameter.
     • An example formula with a function and merge syntax: LOWER({{$User.FirstName}}) && "@example.com"
       • If the user's first name is "Sally" --> sally@example.com
4. Click Save.

Within the Page Designer, create a new model and connect it to your newly created connection. At build time, it will act just like any other model. But at runtime, your end users will simply see the data they have access to—no OAuth popup windows or the like.

Troubleshooting

There are a lot of moving parts when configuring SSO, so try checking these key areas if you're seeing issues:

• The identity provider connection within the external connection for your IdP must be properly configured.
• The following fields within the OAuth client connection within the external connection must be properly configured with:
  • The Entity ID and ACS URL corresponding to your Salesforce org or Nintex Apps site.
  • The Issuer field from your external connection's identity provider connection
  • Your certificate of choice

Note:  To use this flow you must log into Salesforce/Nintex Apps using your IdP. If you login using the standard Salesforce or Nintex Apps login screen—and not through SAML or the Login with SAML option in Nintex Apps—then you will not be able to access connections using this flow.