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.

Authentication and Nintex Apps

Nintex Apps provides several different mechanisms for authenticating to external services. You can choose to store (shared and/or individual) credentials securely within Salesforce, or you can choose to leverage standards like OAuth to delegate authentication to a third party.

Connection Authentication Methods

These authentication methods are available at the connection level.

No Authentication

Select this option if your service is publicly available and does not need any type of credentials for access. This method could also be relevant for services that are behind a firewall and the connection has Use Apex Proxy unchecked.

Basic HTTP Authentication

While OAuth is the recommended authentication flow for most connections, Nintex Apps also allows for basic HTTP authentication—in short, sending encrypted user credentials to a connection to login.

Nintex Apps encrypts all usernames and passwords using AES-256 symmetric encryption. Credential records are stored in Protected Custom Settings which are inaccessible to querying through any API—only Nintex Apps internal code can access this information, and Nintex Apps does so only when making authentication requests to connections. Your company's Salesforce administrator can change the encryption key from the Nintex Settings page.

Note:  It is impossible for Nintex Apps administrators to login as a different end user and gain access to that user's connection credentials.

With Basic HTTP Authentication, credentials are sent Base64 encoded as a header with every request. If you select this authentication method, Nintex Apps will automatically construct the Authorization as shown below. For example, if a username of Aladdin and a password of open sesame were provided, Nintex Apps would construct the following header.

Copy 
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

When configuring basic HTTP authentication for a connection, you must specify a credential source. This can either be:

  • Shared by all Site Users ( Nintex Apps ) / Shared Org-wide ( Nintex Apps for Salesforce ): If you want all end users to share the same username and password to access the external data system, select this option and enter the credentials on the form that appears below the picklist.
  • Shared Per-Profile, with optional Org-wide Defaults: If you want end users to share a login based on a Salesforce profile, enter the credentials on the form that appears below the picklist. You may also enter default org-wide credentials.

Note:  This credential source is not currently available on Nintex Apps.

  • Per-User, with optional shared Site-wide Defaults ( Nintex Apps ) / Per-User, with optional Profile / Org-wide Defaults ( Nintex Apps for Salesforce ): Allows users to enter their own individual credentials for a connection, with optional default credentials available if needed.

    End users manually add their own credentials within the Nintex Apps UI:

API Key Authentication

Some services authenticate by requiring a special key be passed along in each request—this key being associated with certain permissions in the service. By selecting this authentication type, the API key field appears, which stores the given API key as an encrypted piece of data in Nintex Apps. This key can then be used within any common HTTP header or body request data for the connection—where it will be securely injected server-side to prevent end users from seeing the key should they observe their network traffic.

  • API key: The key to store

Once entered and saved, use the {{$Auth.API_Key}} merge variable to set up a common request header or body data in the format required by the service.

Note:  This authentication method requires the use of Nintex Apps's proxy.

Example

Assume a service requires an API key be sent with as an Authorization header with this format:

Copy 
Authorization: Bearer <API_KEY>

Also assume the API key's value is abc123 .

To authenticate to this service using API key authentication:

  1. Create a new connection (or open an existing one).
  2. Set the authentication method to API Key Authentication.
  3. In the API key field, enter the API key: abc123 .
  4. Click Save.

Now you can use the {{$Auth.API_Key}} merge variable in a common request header matching the service's API reference material.

  1. Click Common HTTP Request Data.

  2. In the Common request headers section, click the box icon in the object, then click Append.

  3. Add a key-value pair that includes the $Auth merge variable:

    Authorization: Bearer {{$Auth.API_Key}}

  4. Click Save

Now, when a Nintex Apps model makes a request to this connection's service, the Authorization header will appear on the request. To end users, this header's value appears as Bearer {{$Auth.API_Key}} . However, when making the request, Nintex Apps's proxy securely injects the true value.

Separate Authentication URL

With the Separate Authentication URL option, Nintex Apps will first make a request to a separate authentication URL, which is expected to return an access token after successfully authenticating. This token can then be used on subsequent requests by updating the connection's Common request headers and/or Common request body data to use the {{$Auth.Response.Body}} and {{$Auth.Response.Headers}} merge variables. You can also access nested parameters/headers through those merge variables. For more information, see the Authentication Merge Variables section

When configuring a Separate Authentication, you can (but are not required to) specify a credential source. This can either be Shared: Org-Wide, Shared: Per-Profile, or Per-User.

  • If the Shared: Org-Wide setting is selected, then you will be prompted to enter the shared username and password.
  • If the Per-Profile, or Per-User settings are selected, then the credentials need to be entered on a separate screen.

Authentication Provider (OAuth, Custom, etc.)

Authentication Providers in Nintex Apps allow for the use of specialized protocols (like OAuth) or custom Apex Code to handle Authentication. Using Authentication Providers, Admins can configure OAuth connections or Custom Apex code.

Authentication Provider Authentication Methods

The following methods require the use of connection in conjunction with an authentication provider.

Custom Apex Authentication

This option is currently only used internally to support the Sharepoint connector's custom authentication process.

OAuth 2.0 / Open ID

OAuth is an open source standard for authentication. It allows a third party ( Nintex Apps ) to create models on services where Nintex Apps never actually receives or knows the username or password required to access that service. The OAuth spec describes several different grant types (or flows) that can be used to gain access to a resource server (External Web Service).

Important:  Nintex Apps does not currently support authenticating with OAuth 1.

Additional resources

OAuth Grant Type Authentication Flows

When configuring authentication providers, there are several grant types to choose from. Depending on your choice, end users will go through a different authentication flow when they attempt to use a connection.

In the Authorization Code OAuth flow, Nintex Apps uses a popup to redirect the end user to an authorization endpoint, where it provides a Client ID to identify the client requesting access on behalf of the user. The end user then enters credentials.

Because this is in a separate popup window, Nintex Apps has no access to the credentials being entered. This interaction is completely between the user and the Authorization Server. Once the end user enters credentials here—and it is determined by the authorization server that the credentials are correct— Nintex Apps receives an authorization code via a callback URL, also known as a redirect URI. Once Nintex Apps has an authorization code, it can exchange that code for an access token from an access token endpoint. Until the token expires (or is otherwise invalidated), it can be used to gain access to the resource server.

The access token has a limited lifespan, specified by expires and expires_in parameters sent to the client in the access token response. Once the access token expires, a new access token must be requested. One of the benefits of the Authorization Code grant, as opposed to the Implicit grant, is that it provides a mechanism for new access tokens to be automatically requested on the end user's behalf when access tokens expire. It does this by means of refresh tokens.

Typically, the first time an end user successfully retrieves an access token via an Authorization Code flow, the authorization server sends back a refresh token in addition to an access token. Refresh tokens functionally let an end user bypass the authorization code step and skip right to the access token request. (This is significant because it requires manual user interaction with the screen to re-authorize.) If Nintex Apps has a refresh token stored for a particular service, it can use this to perform a refresh token grant flow to request new access tokens for the user—and do it behind the scenes, as needed, when access tokens expire. This makes the combination of the Authorization Code / Refresh Token Grants a better user experience than the Implicit Grant, which does not support refresh tokens.

Key Takeaways:

  1. Keeps user credentials secret
  2. Allows new access tokens to be automatically obtained via refresh tokens

Step 1: Open a popup window at a particular URL

GET /authorize?response_type=code&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

Step 2: If authorization is successful, the popup window is redirected to a callback URL/redirect URI.

HTTP/1.1 302 Found

Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

Step 3: Using the Authorization Code received in Step 2 to request an access token

Both the Client Id and Client Secret are typically used to authenticate the client in this step.

POST /token HTTP/1.1

Copy 
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Step 4: An access token is returned

HTTP/1.1 200 OK

Copy 
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
 "example_parameter":"example_value"
}

Step 5: Using the access token, make the actual request to the resource server

This grant type uses the client ID and client secret REST API credentials for authentication, instead of individually authenticating specific end users through an authorization code or username/password credentials.

In the implicit grant, the client is issued a token directly. Since this flow is initiated from the client (i.e., the end user's web browser), it does not authenticate the client using a client secret. Only the public client Id is used.

Key Takeaways

  1. Keeps user credentials secret
  2. Does not allow refresh tokens; end users must reauthorize when access tokens expire

Step 1: Client makes a request to the authorization server

GET /authorize?response_type=token&client_id=s6BhdRkqt3&state=xyz&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1

Step 2: If authorization is successful, the client is redirected and given an access token

HTTP/1.1 302 Found

Copy 
Location: http://example.com/cb#access_token=2YotnFZFEjr1zCsicMWpAA

A JSON Web Token (JWT) is an internet standard JSON object with a variety of key-value pairs typically used for data access. When this grant type is selected, Nintex Apps sends a JWT with each connection request containing several standard claims, as well as any configured custom claims. These claims can be verified as originating from a specific site because of the use of signed certificates—with the Nintex Apps site providing a public key certificate to be uploaded to the external system.

Claims are the key-value pairs that pass along the information that is used to identify the user when they attempt to access data. You'll likely need to configure one or more custom claims depending on the data your connection expects for authentication.

One of this grant type's advantages is that there is no OAuth popup, allowing a more seamless experience when users access the page.

To utilize this grant type you must:

  1. Download a signing certificate from your Nintex Apps site by navigating to Settings > Certificates and clicking the certificate you wish to use. You may create a new certificate or use Nintex Apps's default certificate.
    • If your system requires an RSA public key as opposed to a certificate file, choose Download RSA Public Key.
  2. Configure an OAuth application in your external system.
  3. Upload the Nintex Apps site's certificate to your external system as part of the OAuth app configuration.
    • This is typically labeled something like Use digital signatures within most systems.
  4. Create an authentication provider with this grant type.
  5. Enter the OAuth app's client ID and client secret within the authentication provider.
  6. Configure the custom claims as needed for the external system.

  • Standard Claims: A set of claims that are reserved under the JWT spec for specific pieces of information. These claims are sent with every JWT and cannot be changed, regardless of settings.

  • Custom Claims: A set of additional claims that are passed along in each JWT. The values entered here vary depending on the service you're connecting to. You can append various types of claims, even arrays, using the JSON builder on the screen.

    Custom claims may contain both merge variables, such as the $User merge variable, and formula functions to allow for retrieving and transforming data you may need to pass to your service.

  • JWT Signing Algorithm: The cryptographic algorithm used to digitally sign each JWT sent by Nintex Apps.

  • Signing Certificate: The certificate used to sign each JWT.

In this grant flow, the resource trusts the client enough to give away its credentials.

Key Takeaways

  1. Stores credentials in Salesforce
  2. End users do not have to enter credentials often

Step 1: Request an access token using the username and password

POST /token HTTP/1.1

Copy 
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=password&username=johndoe&password=A3ddj3w

Step 2: If authorization is successful, the client is given an access token

HTTP/1.1 200 OK

Copy 
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
  "access_token":"2YotnFZFEjr1zCsicMWpAA",
  "token_type":"example",
  "expires_in":3600,
  "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
  "example_parameter":"example_value"
}

This authentication method allows you to use the ARN of an assumable role instead of hard-coded AWS access keys. When a Nintex Apps user makes a request using this authentication method, Nintex Apps makes a secure server-side request to assume the configured role. If this request is successful, Nintex Apps receives temporary access credentials, which Nintex Apps caches until the credentials expire after 60 minutes.

Requests made through an assumed role are traceable via the AWS console. From there, you can see both the Nintex Apps site and Nintex Apps user who initiated the request, which provides AWS administrators full visibility into who requested access credentials and from what Nintex Apps site.

Due to this method's security and ease-of-management after initial setup, we typically recommend it over the access keys method. However, it does require some technical knowledge to configure. Be sure to read all of the instructions below.

Before you begin

Nintex Apps can only access roles that have a defined path containing the string /Nintex Apps-assumable-role/ . This is different from the role's name. Role paths can only be set when first created, so it isn't possible to update an existing role with a new path.

In order to create a role with a path, you'll need to use either the AWS IAM API or the AWS CLI.

The instructions below assume you are using AWS CLI (version 2) and that you've already configured an access key ID and secret access key for use with the CLI. Ensure these credentials have the iam:CreateRole permission. Command line examples are also tailored for Linux or macOS operating systems; commands for command line programs on Windows may differ.

Finally, because IAM roles require a trust relationship policy upon creation, you'll need to save the JSON that Nintex Apps provides when creating an authentication provider. Because of this you'll need to navigate between your browser window, your computer's file explorer, as well as the command line.

In Nintex Apps

  1. From the Nintex Apps navigation bar, navigate to Connections > Authentication Providers.
  2. Click Create.
  3. Configure the authentication provider's basic properties:
    • Name: Enter a name, such as AWSAuth.
    • Authentication Method: AWS: Assume Role with ARN
  4. In the Trust Relationship Policy, click Copy to Clipboard.

This copied policy will enable your role to grant proper access to your Nintex Apps site.

Note: 

If you want this role to be assumable by multiple Nintex Apps sites —for example a staging site and a production site, make the sts:ExternalId property 's value into an array of Nintex Apps site Ids.

For example, change this key/value:

Copy 
"sts:ExternalId": "09583eba-de0e-49d3-ae42-61b3927a61b1"

Into this:

Copy 
"sts:ExternalId": [
   "09583eba-de0e-49d3-ae42-61b3927a61b1",
   "e354e60f-5a80-4024-b01a-4cae13d0948c"
]

Site IDs are accessible from Settings > Site > Profile.

On your local machine

  1. With the policy copied to your clipboard, paste the policy into a text editor.
  2. Save the file to an easily accessible directory (for example, your desktop) on your machine with a recognizable name and the JSON file extension, like trust-policy.json

In a command line interface

With the trust policy saved to your machine, you can now use the AWS CLI to create an assumable role.

  1. Open your command line program of choice and navigate to the directory containing your policy JSON file. For example, if you saved the file on your desktop:

    Copy 
    cd ~/Desktop

  2. Use the AWS CLI's iam create-role command to create the role with the proper path value and trust relationship policy:

    Copy 
    aws iam create-role --role-name Apps-S3-Access --path /skuid-assumable-role/ --assume-role-policy-document file://trust-policy.json

    Note:  While role-name can vary from this example, the path must contain /skuid-assumable-role/

    The CLI creates the role, outputting its ARN and other related metadata. Because of the configured path, your ARN should look similar to this: arn:aws:iam::1234567891011:role/Nintex Apps-assumable-role/Nintex Apps-S3-Access .

  3. Copy this created ARN, either from the command line output or the AWS console.

In Nintex Apps

  1. Return to the authentication provider window.
  2. Paste the copied ARN into the AWS Role ARN to assume field.
  3. Click Save.

This authentication method utilizes an Amazon Web Service (AWS) IAM role's access keys to authenticate to an AWS system.

If you are not the manager of your AWS services, follow along with Amazon's steps for creating access keys with your IT administrator. You'll need to do the following:

In AWS

  1. Create a new group and select the appropriate policies for that group.
    • These should align with your intended Nintex Apps use. Ensure your access policies match the services (S3, DynamoDB, or SNS) you'll be using.
  2. Create a new user in AWS Identity and Access Management (IAM) within the newly created group.
  3. Retrieve the access credentials generated for that user:
    • The secret access key is only displayed once, immediately after the access key is generated, and cannot be found later. Be sure to copy it to a safe place.

In Nintex Apps

With your access credentials handy, you can now use them to configure a Nintex Apps authentication provider that will work with all AWS connections.

  1. Navigate to Configure > Connections > Authentication Providers.
  2. Click New Authentication Provider.
  3. Configure the authentication provider's basic properties:
    • Name: Enter a name, such as AWSAuth.
    • Authentication Method: AWS: Access Keys
  4. Enter your IAM role's credential information:
    • AWS Access Key Id: The access key ID to use when authenticating.
    • AWS Secret Access Key: The secret access key to use when authenticating.
  5. Click Save.

Troubleshooting Tips for Authentication

To troubleshoot OAuth issues, you can use Nintex Apps's Javascript OAuth API to examine the OAuth response for a particular service for which authentication was requested. For instance, if you were having issues connecting to Dropbox, you could inspect the OAuth response by going into the JavaScript console and entering:

Copy 
skuid.oauth('dropbox').getAuthResponse();

This returns an object which should contain details of any errors that occurred with your OAuth flow for that service.

  • For all standard OAuth provider types, this will be accessible via skuid.oauth(provider_type) , which is usually the lowercase name of the provider type.
  • For other provider types, you will need to use the provider's name as defined on the connection record.

Removing stored OAuth access credentials

To remove stored OAuth access credentials for a particular service, call the following method:

Copy 
skuid.oauth(provider_type_or_name).logout();

Authentication Merge Variables

{{Auth.API_Key}} : A reference to the API key stored when API Key Authentication is selected for a connection. When used, Nintex Apps injects the stored value on the server-side, so users cannot see the value. For more information, see the API Key Authentication section.

{{$Auth.BasicAuth}}

{{$Auth.Username}}

{{$Auth.Password}}

{{$Auth.Response.Body}} : Contains the values returned by the authentication request's response. It's possible to target specific body parameters by appending the parameter to the end of the merge variable. For example: {{$Auth.Response.Body.access_token}} would return the access_token parameter value included in the authentication request's response.

{{$Auth.Response.Headers}} : Contains the values returned by the authentication request's response. It's possible to target specific header parameters by appending the parameter to the end of the merge variable. For example: {{$Auth.Response.Headers.Expires}} would return the Expires header value included in the authentication request's response.

{{$Api.Session_Id}}

Encryption in Nintex Apps

The following fields are stored encrypted in Nintex Apps:

  • Connection (for org-wide credentials)
    • Username
    • Password
    • API key
    • Per-profile or per-user username
    • Per-profile or per-user password
  • Authentication Provider
    • Client Id
    • Client Secret