TABLE OF CONTENTS

• App Auth Configuration
  • Step 1: Enable App Authentication
  • Step 2: Set Up the Authentication Data Source
  • Step 3: Create a Login Page
  • Step 4: Configure Page Access Modes
  • Step 5: Add a Log Out Option
• Advanced Configuration
  • App Auth State Monitoring
  • Using App Auth Token in External Requests
  • Configuring SSO-Style Authentication
  • Configuring Authentication for Specific Data Sources
  • Configuring Logout on Page Refresh
  • Enabling Refresh Token Flow

App Authentication (App Auth) allows you to protect access to your App using a custom authentication flow that runs separately from CafeX's built-in authentication.

App Auth Configuration

The following steps walk you through the process of configuring App Auth in your App.

Step 1: Enable App Authentication

To get started, enable the App Auth toggle in your App settings:

1. In the Explorer section, click App.
2. In the Appearance and Configuration panel, go to the Configuration tab.
3. Under App auth, enable the Enable app auth toggle.
   

Note:

• If public access is disabled, users will need to log in twice: first into CafeX and then through the App Auth flow.
• If public access is enabled, users will only be prompted for App-level authentication. They will be treated as guests by CafeX.

Step 2: Set Up the Authentication Data Source

Next, create an external data source to handle user login and return an authentication token.

To create the Authentication Data source:

1. Go to the External data source tab ().
2. Click Add data source.
3. Complete the configuration form. For Configuration, you need to specify a POST request with an appAuth value of true and an optional appAuthConfig block, for example:

   {  "url": "https://myauthservice.com/auth",  "method": "POST",  "appAuth": true,  "appAuthConfig": {    "tokenPath": "tokenDetails.token",    "expiryPath": "tokenDetails.expiry",    "defaultTokenExpiryMillis": 600000   },  "payload": {    "contentType": "application/json",    "fields": [       { "name": "username", "type": "text" }, { "name": "password", "type": "text" }     ]   } }

   
   In this example, a POST request is sent to the authentication service using the provided username and password. A JSON response is returned which is used as the auth token. Important: Make sure to update the example values to match your own authentication service.
   
   Configuration fields:

   Field	Description
   appAuth	Marks the data source as an authentication source. Must be set to true.
   tokenPath	Path in the response body where the auth token is located. The token is stored encrypted and can later be included in request headers. Note: This value is stripped from the client response for privacy reasons.
   expiryPath	Path in the response body where the token's expiration time is located (in milliseconds).
   defaultTokenExpiryMillis	Used when expiryPath is missing or if the time calculated from defaultTokenExpiryMillis is earlier than the value found in expiryPath. Defaults to 12 hours if not specified.

Step 3: Create a Login Page

When App Auth is enabled, a new Login page type becomes available. This page will be redirected to when a user without a valid app auth token is viewing the App. 

To add a login page:

1. In the Explorer section, right-click App and select Add login page.
   
2. The login page will be added to your App and can be configured like any other page in App Studio.
3. Optionally, configure the Login Form. Although not strictly required, the most common setup is to:
   • Add a Form component to the login page.
   • Connect the form to the App Auth data source you created in Step 2.

Step 4: Configure Page Access Modes

Each page in your App can be configured with an Access Mode to control who can view it based on their authentication state. 

To configure Access Mode:

1. Select the page in the Explorer.
2. Go to Configuration > App auth.
   
3. Choose one of the following Access Mode options:
   1. Only available to logged-in users: Users must be logged in to view this page.
   2. Only available to logged-out users: Only users who are not logged in can access this page.
   3. Available to all users: The page is available to any user regardless of whether the user is logged in or not.

Step 5: Add a Log Out Option

You can allow users to log out of App Auth by adding a Log Out action to a component, typically a button. 

To add a Log Out option:

1. Drag and drop User interaction > Button onto the canvas.
2. Select the component and go to Configuration > Event handlers.
3. Click New event handler.
4. Configure the event handler with the following parameters:
   

   Name	Specify the name of the handler, for example, Log out.
   Event type	Click
   Action	App auth logout

   
    

When triggered, this action redirects users to the login page if one exists; otherwise, they are redirected to the first page of the App.

Advanced Configuration

This section covers advanced App Auth configuration options, such as: 

• App Auth state monitoring 
• Using app auth token in external requests 
• Configuring SSO-style authentication 
• Configuring authentication for specific data sources 
• Configuring logout on page refresh 
• Enabling refresh token flow

App Auth State Monitoring

The system provides a data set that allows you to track the App Auth status of the current user. This is useful for conditionally showing UI elements, such as a “Welcome, username” message, content visible only to logged-in users, or for displaying login errors when authentication fails.

Available fields:

You can use these fields in mustache expressions.

Using App Auth Token in External Requests

If App Auth is enabled for your App, you can configure non-authentication data sources to reuse the stored App Auth token by including it in the Authorization header.

This allows secure, token-authenticated requests to external APIs, without exposing the token to the client.

Example configuration:

• The {{appAuth.token}} expression tells CafeX to use the previously stored token from the App Auth login.
• CafeX automatically inserts the token into the header:
  
  Authorization: Bearer <your_token>.
  
  
• The front end does not need to handle the App Auth token and it’s not exposed to the client.
  
  

Configuring SSO-Style Authentication

You can enable a Single Sign-On (SSO)-style authentication flow by configuring an App Auth data source with SSO-specific options.

In this flow, the user is authenticated automatically based on a token passed in the URL. If the SSO authentication is successful, the App continues as though the App Auth process has completed successfully.

Example configuration:

Configuration fields:

In the example above, if a user visits the App using a URL like https://app.cafex.com/apps/APP_ID...?token=abcdef,

1. The App extracts the token=abcdef query parameter.
2. It sends a request to the SSO auth data source with the following body: {"exchangeToken": "abcdef"}.
3. If the response is successful, the token is stored, and the user is authenticated just like with a standard login form.

Configuring Authentication for Specific Data Sources

In Apps with App Auth enabled, you can flag certain data sources to require a valid App Auth token to execute.

To do this, add the following property to the data source configuration:

"requireAppAuth": true

• This is a top-level flag which defaults to false.
• When set to true, the data source will only execute if the user is logged in with a valid App Auth token.

Note: If a data source uses {{appAuth.token}} in the authorization header, it will only be evaluated when the user is logged in. In this case, setting requireAppAuth: true is redundant, as authentication is already enforced through the token usage.

Configuring Logout on Page Refresh

You can enable the Logout on page refresh setting. When enabled, reloading or reopening the App will require the user to log in again.

To configure logout on page refresh:

1. Go to the App’s Configuration panel.
2. Enable the Logout on page refresh option.
   

Enabling Refresh Token Flow

You can configure App Auth to support a refresh token mechanism. This allows the system to request a new authentication token on the server side when the original token is expired.

Step 1: Include a Refresh Token in the Login Response

In your App Auth data source configuration, include the refreshTokenPath field inside the appAuthConfig block. This tells the App where to find and store the refresh token.

Example configuration:

Step 2: Configure a Refresh Token Data Source

Next, define a refresh data source that uses the server-side stored refresh token to retrieve a new access token.

Key attributes:

• tokenRefresh: true enables refresh mode.
• refreshTokenOutput defines the name of the request field to receive the stored refresh token.

Example configuration:

In this example:

• The stored refreshToken is automatically inserted into the r field.
• The request returns a new access token and optional new expiration.