Configure ProcessFactorial React App

This article outlines how to configure your Customer Portal to use the Process Factorial Form forms from a custom React-based application.

Authentication Overview

The ProcessFactorial React Portal supports two authentication models depending on how your application manages user identity:

Model	When to use	How validation works
Microsoft Entra ID (AAD)	Your React app uses MSAL.js with an Azure App Registration	The JWT is validated against the Entra ID tenant's OpenID Connect metadata and signing keys (JWKS). The `iss` and `aud` claims must match your configuration.
Custom / Bespoke JWT	Your app issues its own JWTs using a self-managed signing key (RS256 or HMAC SHA256)	The JWT is validated against the public key or shared secret you provide. The `iss` and `aud` claims are validated if enabled.

Choosing a model

If you already use Microsoft Entra ID for authentication, choose the Microsoft Entra ID model — no signing key is needed.
If you have a custom identity provider or want to issue your own tokens, choose the Custom / Bespoke JWT model — you provide the public key.

Prerequisites

A ProcessFactorial Portal account with access to your customer and project.
An environment linked to your project.

Microsoft Entra ID (AAD) Prerequisites

An Azure App Registration for your React application.
The Tenant ID where the app is registered.
The Client ID (Application ID) of the App Registration — this is typically the aud claim.
The Issuer URL — typically https://login.microsoftonline.com/{TenantId}/v2.0.

Custom / Bespoke JWT Prerequisites

An RS256 or HMAC SHA256 signing key (see Creating a signing key below).
The public key (PEM format) for RS256, or the shared secret for HMAC SHA256.
The issuer (iss) and audience (aud) values your tokens will carry.

Configure the ProcessFactorial Portal

Browse to the ProcessFactorial Portal.
Navigate to your customer and project.
Click the Environments tab.
Select the environment linked to your React app (don't open it, just select the radio button).
Click the Environment Settings button on the grid.
Update the settings according to the table for your chosen authentication model.

Microsoft Entra ID (AAD) Configuration

When using MSAL.js with an Azure App Registration, the JWT is validated against Azure AD's OpenID Connect metadata. No signing key is required.

Setting Name	Description	Value
Forms Portal Auth Issuer Key	Leave empty — validation uses Azure AD's published signing keys	empty
Enable Forms Portal Auth Issuer Key Validation	Must be enabled for signed token validation	`True`
Forms Portal Auth Issuer	The JWT `iss` claim value expected from Azure AD	`https://login.microsoftonline.com/{TenantId}/v2.0`
Enable Forms Portal Auth Issuer Validation	Enable to verify the `iss` claim matches	`True`
Forms Portal Auth Audience	The JWT `aud` claim value — typically your App Registration Client ID	`{ClientId}` or `api://{ClientId}`
Enable Forms Portal Auth Audience Validation	Enable to verify the `aud` claim matches	`True`
Portal Token Algorithm	Signing algorithm used by Azure AD	`RS256`

Custom / Bespoke JWT Configuration

When your application issues its own JWTs, you configure which aspects of the token are validated. The three boolean flags — Key Validation, Issuer Validation, and Audience Validation — can be independently enabled. Their dependencies are:

Flag	Requires	Description
`Enable Forms Portal Auth Issuer Key Validation`	`Forms Portal Auth Issuer Key` + `Portal Token Algorithm`	Validates the JWT signature. Turn On for signed tokens (recommended), Off only if your tokens are unsigned.
`Enable Forms Portal Auth Issuer Validation`	`Forms Portal Auth Issuer`	Validates the `iss` (issuer) claim matches the expected value.
`Enable Forms Portal Auth Audience Validation`	`Forms Portal Auth Audience`	Validates the `aud` (audience) claim matches the expected value.

All three flags are independent — you can enable any combination. At minimum, at least one form of validation is recommended.

Setting Name	Required?	Description	Value
Forms Portal Auth Issuer Key	Required if Key Validation is enabled	Your public key in PEM format (RS256) or shared secret (HMAC SHA256). Include `-----BEGIN PUBLIC KEY-----` and `-----END PUBLIC KEY-----` delimiters	See Creating a signing key below
Enable Forms Portal Auth Issuer Key Validation	Optional	Validate the JWT signature against your key.	`True` or `False`
Forms Portal Auth Issuer	Required if Issuer Validation is enabled	Expected `iss` claim value in your JWTs	e.g. `https://your-auth-domain.com`
Enable Forms Portal Auth Issuer Validation	Optional	Verify the `iss` claim matches	`True` or `False`
Forms Portal Auth Audience	Required if Audience Validation is enabled	Expected `aud` claim value in your JWTs	e.g. `your-app-name`
Enable Forms Portal Auth Audience Validation	Optional	Verify the `aud` claim matches	`True` or `False`
Portal Token Algorithm	Required if Key Validation is enabled	Signing algorithm — must match what your tokens use	`RS256` or `HS256`

Common configurations

Full security (recommended): Enable all three — key, issuer, and audience validation.
Key + audience only: Enable key and audience validation; disable issuer validation. Useful if your issuer value varies.
Key only: Enable key validation; disable issuer and audience validation. Signs the token but doesn't check claims.
Issuer + audience only (no signing): Disable key validation; enable issuer and audience. Token is unsigned; only claims are checked. Use only in controlled environments.

Click Save & Close.

Creating a Signing Key (Custom / Bespoke JWT)

RS256 (Recommended)

Generate an RS256 key pair using OpenSSL:

# Generate a private key
openssl genrsa -out private.key 2048

# Extract the public key (PEM format)
openssl rsa -in private.key -pubout -out public.key

The public key output looks like:

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END PUBLIC KEY-----

Copy the entire public key (including the delimiters) into the Forms Portal Auth Issuer Key setting.

HMAC SHA256

Generate a shared secret:

# Generate a 256-bit (32-byte) random key
openssl rand -base64 32

Copy the base64-encoded result into the Forms Portal Auth Issuer Key setting. Set Portal Token Algorithm to HS256.

Token Requirements

Your application must provide a valid JWT in the Authorization header using the Bearer scheme. The JWT must contain:

iss (issuer) — matches your Forms Portal Auth Issuer setting
aud (audience) — matches your Forms Portal Auth Audience setting
exp (expiration) — a valid future timestamp
sub, oid, unique_name, or upn — a user identifier claim. At least one of these is required to identify the user. For custom/bespoke JWTs, oid is the recommended identifier if you don't have unique_name or upn.

Parent App Integration

If embedding forms in your React app, expose a window.pfGetJWTToken function that returns a Promise resolving to your JWT token. See Parent App Integration for details.

Troubleshooting

Symptom	Likely cause
`401 Unauthorized`	Token is expired, missing, or signature validation failed
`IDX20803: Unable to obtain configuration`	Azure AD tenant is unreachable — check network connectivity and Tenant ID
`IDX10501: Signature validation failed`	Signing key mismatch — verify the public key in settings matches the private key used to sign
`IDX10205: Issuer validation failed`	The `iss` claim doesn't match Forms Portal Auth Issuer — check both values
`IDX10503: Signature validation failed` with `The token's kid is: '...', but did not match any keys`	Misleading error. The `kid` in the JWT header is logged for reference, but the validator will try your configured key regardless of whether the `kid` matches. The real cause is almost always a key mismatch — the PEM public key in settings does not correspond to the private key that signed your JWT. Verify you're using the correct public key for the signing key pair. To regenerate a key pair: see Creating a signing key.