Application Authentication security provider in Jitterbit App Builder

Introduction

App Builder supports Application Authentication as a security provider, which lets you build your own login forms and authenticate clients using a custom approach. Instead of redirecting clients to a third-party Identity Provider (IdP), clients are redirected to an App Builder page that you create. (This provider is used to sign users into App Builder; it cannot be used to authorize users who are already signed in.)

You may want to use a custom login flow in situations such as these:

Allowing clients to maintain their own user accounts.
Validating credentials against a third-party service via an API.
Verifying a phone number by texting a One-time Passcode (OTP).
Letting clients sign in semi-anonymously.

This page explains how the authentication flow works and how to configure it.

How it works: the authentication flow

Understanding the Application Authentication flow is key to implementing it correctly, especially when directing users to a page that requires a login. This is known as a "challenge".

The challenge and redirect process

Here is the typical user journey when trying to access a protected page:

Initial request: An unauthenticated user attempts to access a "deep link" to a page inside your app that requires a login. The link can even contain URL parameters.
Example URL
```
https://<your-domain>/app/MyApp/MyProtectedPage?orderId=123
```
Authentication challenge: App Builder determines that the user is not logged in and that the page requires authentication. It initiates a "challenge".
Redirect to login page: App Builder redirects the user to the custom login page defined in your Application Authentication security provider's LoginPath property.
Important

For this to happen automatically, you must do the following:
- Set this security provider as the Default Authentication provider for your application. (This overrides any system-wide default that may be set in IDE > Security Providers > Configuration > Default Authentication.)
- Enable the Redirect On Challenge option.
User logs in: The user enters their credentials on your custom login page and submits the form.
Authentication rule runs: Your custom authentication rule runs, verifies the credentials, and logs the user into App Builder.
Redirect to original page: After a successful login, App Builder automatically redirects the user back to the page they originally tried to access, including all of the original URL parameters.

This seamless flow ensures that users land exactly where they intended to go after logging in, without losing any context from the original link they followed.

Configuration overview

To configure Application Authentication, you need to set up several components in your environment and within your application.

Environment configuration

The following must be configured in each environment (for example, Dev, QA, and Production):

Login page application: A separate, standalone App Builder application that serves as your login form.
Application authentication security provider: The security provider that defines the custom login behavior.
Generic user accounts: One or more user accounts in App Builder that authenticated users are mapped to.

Application configuration

You must configure these items in your main application:

Authentication rule: A business rule that contains the logic to verify user credentials.
(Optional) Supporting tables: Tables to manage user sessions, passwords, and application-specific user data.

Step-by-step configuration guide

You should configure the login page as a standalone application. This app exists only to authenticate users. These are the requirements for it:

The page must be accessible to the Anonymous User group.
It should contain a panel that runs off the Session table.
It needs one or more editable fields to capture user credentials (such as a User Name, Email, or Phone Number).
(Optional) A Password field (with password validation configured).
It needs a Login button that triggers your authentication rule. This button should not link to any page; its only purpose is to run the rule.
You can optionally include Forgot Password or Sign up links.

2. Create the Application Authentication security provider

To create the Application Authentication security provider, follow these steps:

Select IDE > Security Providers.
Under the User Authentication panel, click + User Authentication.
On the Provider page, set the following:
- Name: A name for your provider (for example, MyAppAuthentication).
- Type: Select Application Authentication.
- Enabled: Leave this disabled until all configuration is complete.
- Show on Login Form: Check this box.
- Default Page: Select the default landing page a user should see after logging in, if they did not originally try to access a specific deep link page. The page must be marked as Public in its Edge Case settings.
Click Save.
Under Properties, click + Property.
In the Properties popup, set the values as follows:
- Parameter: Select LoginPath.
- Value: Enter the root-relative path to your login page app. The path must be URL-encoded and start with a /.
  Example
```
/app/Login%20App/Login%20Page
```
Save the properties and close the popup.

3. Configure a generic user account

App Builder provides two main approaches for handling user accounts with Application Authentication:

Mapping to a generic user account: This involves creating one or more pre-existing user accounts in App Builder that authenticated external users are mapped to. This is particularly useful for scenarios like semi-anonymous access (for example, using a phone number and OTP) where all external users might share a low-privilege account.
Dynamic user provisioning: This more advanced approach involves creating individual user accounts in App Builder on the fly during the sign-in process.

This section focuses on the first approach: mapping to a generic user account. To do this, follow these steps:

Select IDE > User Management and create a new user account (for example, MyAppUser). This is the account that provides the permissions inside the app.
Assign the user to the Groups that grant the necessary roles for your application.
Under Identities, click + Identity to create an identity for this user with the following settings:
- Name: Enter the value that your application will use to identify the person, such as their username or email address. This must be unique for each user. App Builder will use this to find the correct user account, unless you also provide a value for Identifier.
- Identifier (optional but recommended): Enter a permanent, unique ID for this user. This is the most reliable way for App Builder to recognize a user, even if their email address or username changes. If you provide this, App Builder always uses it first to find the user.

4. Create the authentication rule

You need a business rule to handle the actual authentication logic. To set one up, follow these steps:

Create a CRUD XP Business Rule that performs an Insert action.
Set the Target Data Source to App Builder and the Target to the Authenticate public data object.
In the rule's SQL, join your user credentials table with the Session table to get the username and password entered by the user.
Map the following four required columns to the Authenticate target:
- AuthenticateID: A new GUID. Use newUUID().
- ProviderId: The ID of your Application Authentication security provider.
- AppUserId: An identifier for the end-user who is logging in (such as their email or username). This is used for auditing via the who('appuserid') function.
- Name: The name of the generic user's Identity to map to (for example, MyAppUser). This can be hard-coded or determined dynamically based on the user's credentials.

5. Enable automatic redirect on challenge

To ensure users are automatically sent to your custom login page when they access a protected page, you must enable these two settings:

Configure the default authentication provider:

(The default authentication provider can be set system-wide or at the application level. The application-level setting overrides the system-wide option.)

To configure the application-level default, follow these steps:
1. Select IDE > Security Providers.
2. Under User Authentication, select More > Manage Applications.
3. Click the Edit icon for your application.
4. Set Default Authentication to the Application Authentication provider you created.
5. Click Proceed and close the popup.
Configure redirect on challenge:
1. On the Security Providers page, click the Open record icon for your Application Authentication provider.
2. Under Provider, click Edit.
3. Check the Redirect On Challenge option.
4. Click Save.

6. Enable and test

Once all the above steps are complete, go back to your Application Authentication security provider in the IDE and enable it. You can now test the entire login flow.

Advanced topics

Link to an authenticated app with URL parameters

One of the most powerful features of this flow is the ability to send a user a link to a specific record or filtered view within your app. Because App Builder preserves the originally requested URL (including all query parameters) through the authentication process, you can construct deep links without any special formatting. For example, you can send a user a link to a specific order: https://<your-domain>/app/MyApp/Orders?Orders.OrderId=5011 When the unauthenticated user clicks this link, they are taken to your login page and, after logging in, are redirected to the Orders page with order 5011 automatically loaded.

Manually trigger a challenge

While App Builder automatically challenges unauthenticated users when they access a protected page, you can also manually trigger this process from your application's logic. This is useful for scenarios like a user's session expiring, or for providing a dedicated Login button in your application's header.

To do this, you create a simple business rule that inserts a record into the Challenge public data object. You can then attach this rule to an event, such as a button click.

Create a Business Rule: Create a new CRUD XP Business Rule and give it a descriptive name, such as Manual Login Challenge.
Configure the Rule Target:
- Set the Target Data Source to App Builder.
- Set the Target to the Challenge public data object.
- Set the Action to Insert.
Map the Provider ID: In the rule's design, you only need to map one column. Map the ID of your Application Authentication security provider to the ProviderId column on the Challenge target. You can find this ID on the Security Providers page in the IDE.
Trigger the Rule: Attach this new business rule to an event. For example, you could add a Login button to your application's header and configure its on-click event to run the Manual Login Challenge rule.

When this rule runs, App Builder immediately redirects the user to the login page defined in your security provider's LoginPath, preserving the user's current page so they can be returned to it after a successful login.