Application Authentication security provider in Jitterbit App Builder

Overview

This page details how to configure the Application Authentication security provider, one of the user authentication methods supported by App Builder (see User authentication methods for an overview of them all). With Application Authentication, you build a custom login page using App Builder tools, and App Builder handles the redirect flow: when an unauthenticated user tries to access a protected page, App Builder redirects them to your login page and, after a successful authentication, returns them to the page they originally requested.

Unlike local authentication and SSO, this method provides no built-in user management capabilities, and thus requires considerably more setup. The developer is responsible for building every aspect of the authentication flow, from credential validation to user provisioning and group assignment. For details on what this involves, see the Authentication flow section. A detailed walkthrough of a hypothetical scenario is provided in the Step-by-step configuration guide section.

Use cases

Application Authentication is the best user authentication method when:

You need to validate credentials against a data source of your choice, rather than App Builder's user table.
Your application requires integration with a third-party authentication API.
You need a custom MFA flow, such as verifying a phone number with a one-time passcode (OTP).
You want to allow users to sign in semi-anonymously.

Authentication flow

Application Authentication puts the developer in full control of the sign-in process. App Builder handles redirecting users to your custom login page and back again after a successful authentication, but all logic in between must be designed and built by the developer. Understanding this flow precisely is therefore essential: it determines what components you need to build and how they fit together.

The developer is responsible for implementing the following:

Validating user credentials against a data source.
Implementing MFA or secondary authentication factors, if required.
Creating and provisioning user accounts.
Assigning users to groups and configuring permissions.
Building password reset and account recovery flows.
Enforcing password policies.

When a user attempts to sign in, the following sequence of events takes place:

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.

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

The following steps walk through the complete configuration of Application Authentication. To make the instructions more concrete, each step includes an example based on a simple scenario: a customer portal that validates user credentials against an external data source (called Customers) containing email addresses and password hashes. All authenticated customers are mapped to a single generic App Builder user account. Your implementation will differ in the specifics, but the structure and sequence of steps will be the same.

The login page is a standalone App Builder application whose only purpose is to collect and submit user credentials. It must be a separate application from your main app so that unauthenticated users can reach it before signing in.

To create the application, follow the steps in Create a new app. Once the application exists, configure its login page with the following requirements:

The page must be accessible to the Anonymous User group. This is required because unauthenticated users must be able to reach the login page before they have signed in. Without this, the challenge redirect will fail.
The page must contain a panel that runs off a table used to capture the credentials entered in the form. The Session table is the recommended choice, as it stores form values for the current session without persisting them. Alternatively, you can use a custom table (for example, a LoginAttempt table set to Add mode, so each login attempt inserts a new record). Your authentication rule reads the credentials from whichever table you choose.
The page needs one or more editable fields to capture user credentials (such as Email, User Name, or Phone Number).
(Optional) A Password field with password validation configured.
A Login button that triggers your authentication rule. This button should not link to any page; its only purpose is to run the rule.
(Optional) Links for Forgot Password or Sign up flows, if your application requires them.

For instance, the login app could be named Customer Login containing a single page named Sign In, which would have two credential fields based on the Session table: an Email field and a Password field with password validation configured. A Sign In button then triggers the authentication rule.

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, CustomerPortalAuth).
- 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.
- Sign Out Page: Select the page users are redirected to after signing out. If you want users to return to your custom login page after signing out, select that page here. The selected 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/Customer%20Login/Sign%20In
```
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, PortalUser). 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.

For instance, in the customer portal scenario, the generic user account is named PortalUser and its identity Name is set to portal.user@example.com. All customers who authenticate successfully are mapped to this account.

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 Vinyl and the Target to the Authenticate public data object.
In the rule's SQL, join your external user credentials table with the table used by your login page form (for example, the Session table) to retrieve the username and password entered by the user.

Important

Do not use App Builder's built-in User table to validate passwords. The User table does not expose the password field for security reasons, making password validation against it impossible without a custom plugin. Use an external data source to store and validate user credentials instead.
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, portal.user@example.com). This can be hard-coded or determined dynamically based on the user's credentials.

For instance, in the customer portal scenario, the rule's SQL joins the Session table with the external Customers table on the Email field. The column mappings are: AuthenticateID uses newUUID(), ProviderId is the ID of the CustomerPortalAuth provider, AppUserId is mapped to the Email field from the Session table, and Name is set to the fixed value portal.user@example.com. Note that the exact SQL for the join, including how password validation is handled, will depend on the structure of your external data source.

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.

For instance, in the customer portal scenario, set Default Authentication to CustomerPortalAuth for the Customer Portal application.

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.

User and group provisioning

Application Authentication handles only the authentication step. It does not automatically create user accounts or assign group permissions. If your application requires users to have specific access rights after signing in, you must configure this separately.

A common issue after a successful authentication is users receiving an access denied error when trying to reach the application's home page. This happens when the user account (or the generic account they are mapped to) has not been assigned to a group with the necessary application permissions.

To grant a group access to an application, see Group provisioning. You must use Manage Privileges to add the application to the group's permission set and then grant the appropriate roles.

If your flow also requires creating user accounts programmatically (for example, registering new users at sign-in time), see User and group provisioning.

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 Vinyl.
- 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.