Custom frontend

Authenticators that present a user interface serve it as plain static files, separate from the authentication logic. This means the built-in frontend of a single authenticator can be replaced with your own, without changing code or rebuilding Fortified ID Access.

Choosing an approach

Replacing the whole frontend is the most far-reaching of three supported options. Pick the least invasive one that solves the problem.

Approach	What you control	When to use it
Branding overlay	Logos, colors, titles, translations. The built-in application is still used.	The default flow is right, but it must match your visual identity. See User interface.
Custom frontend	The complete user interface of one authenticator, including markup, layout, and interaction.	You need a different user experience, your own frontend framework, or integration with an existing design system. Described on this page.
ExternalFlow	An entire step, hosted as a separate service on another host or domain.	The user interface is owned by another system, or must run outside Fortified ID Access. See ExternalFlow.

Note

A custom frontend replaces the view only. The authentication logic, session handling, and event logging of the authenticator are unchanged.

How a view is served

An authenticator with a user interface is bound to a single context path that serves two roles. The HTTP method decides which one applies.

Method	Condition	Handled as
GET	Any request	View request. The view is served as a static file from the configured web root.
PUT	Header Content-Type: application/json	API request. The message is routed to the authenticator using the type property in the request body. See Web Authenticator API.

A view request is completed in three steps:

1. If the request path does not end with /, the browser is redirected to the same path with a trailing slash. This is what makes relative paths inside the view resolve correctly.
2. The request is rerouted to view_path in the authenticator web root. The default is index.html.
3. Static resources below the path are served from the overlay directories first, then from the web root. A resource that exists in both is served from the overlay.

Caution

The view and the API share the same URL. A custom frontend must therefore send its API requests to the directory URL that the page itself was loaded from, not to a separate API path.

Configuration

Each authenticator type supplies a default web root, which is why webroot_dir can be left out of a standard configuration. Setting it explicitly replaces the built-in frontend for that authenticator instance only. Two instances of the same type can use two different frontends.

Properties

Name	Description	Default	Mandatory
webroot_dir	Path to the directory serving as authenticator web root. Point it at your own build output to replace the built-in frontend.	Supplied by the authenticator type. See Authenticators with a replaceable view.	false
view_path	Entry point served for a view request, relative to the web root.	index.html	false
overlay_dir	Directory searched before the web root. Applies to a custom frontend as well, so keep it empty unless you intend to override your own files.	${system.customer_home}/overlay	false
enable_precompression	Serve precompressed .br or .gz variants from the web root when the browser accepts them.	false	false
enable_precompression_overlay	Serve precompressed variants from the overlay directories.	false	false

Example

{
  "id": "validate_otp",
  "type": "OTPValidator",
  "config": {
    "base_path": "${globals.default_login_suffix}",
    "pipe_id": "otp_validation",
    "webroot_dir": "${system.customer_home}/frontend/otp",
    "enable_precompression": true
  }
}

Note

Common properties such as base_path, context_path, and the redirect locations are described in Common configuration.

Requirements for a custom frontend

The frontend is free in every other respect, but it has to meet the following requirements to work inside an authentication flow.

Requirement	Why
Build with relative asset paths.	The application is served from the authenticator context path, not from the web server root. Absolute paths such as /assets/main.js will not resolve.
Send API requests to the directory URL of the current page.	The view and the API share one URL. Deriving the base URL from the page location keeps the frontend independent of where the authenticator is mounted.
Use PUT with Content-Type: application/json.	Any other method is treated as a view request and returns the page instead of a JSON response.
Send cookies with every API request.	The authentication state is held in the session identified by the session cookie.
Follow data.location when present.	Responses of type complete and cancel return the location the browser must be sent to in order to continue the flow.
Display data.message when present.	The message carries information intended for the user. When both a message and a location are supplied, show the message first and redirect once it is confirmed.
Implement the message protocol of the authenticator.	Message types and payloads differ per authenticator type. The protocol is documented on the page for each authenticator.
Provide your own translations and configuration.	The translation keys and overlay files used by the built-in applications are part of those applications. A custom frontend owns its own localization.

Every authenticator supports the common cancel request and the common complete, cancel, and failure responses. A minimal custom frontend therefore needs to handle at least those, plus the authenticator-specific request types, usually state and start.

Authenticators with a replaceable view

The table lists the authenticator types that serve a view, together with the web root used when webroot_dir is not configured. Paths are relative to the installation directory.

Authenticator type	Default web root
Selector, Select	web/authenticator/selector
Impersonate, ImpersonateWithSearch	web/authenticator/impersonate_selector
UserNameAndPassword	web/authenticator/username_password
UserLookup	web/authenticator/user_lookup
OTPValidator, OTP, OTPAuthenticator	web/authenticator/otp_validation
Passkey	web/authenticator/webauthn
Eid	web/authenticator/eid
BidOnMobileDevice	web/authenticator/bankid/omd
BidOnOtherDevice	web/authenticator/bankid/osd
FrejaWithQRCode	web/authenticator/freja/freja_qr_or_appswitch
FrejaWithUserInput	web/authenticator/freja/freja_with_user_input
SithsWithQr, SithsWithQrAndAppSwitch	web/authenticator/siths_qr_or_appswitch
NiasOnSameDevice	web/authenticator/nias/niasomd
NiasOnOtherDevice	web/authenticator/nias/niasood
DeviceUserCode, OIDCDeviceUserCode	web/authenticator/device_user_code

Authenticators that do not appear in the table have no view to replace. This includes header-based and Integrated Windows authenticators, which never involve the browser in a dialogue, the protocol managers for SAML and OIDC, and ExternalFlow, which delegates the entire step to another service.

Note

A few authenticators, such as the sign message display used in signing flows, serve a view but supply no default web root. For those, webroot_dir is required before any view is served.

Deployment

Place a custom frontend outside the built-in web directory. The directory web/authenticator is part of the product installation and its contents are replaced when Fortified ID Access is upgraded.

1. Build the frontend with relative asset paths and an index.html entry point.
2. Copy the build output to a directory of your own, for example <installation path>/customer/frontend/<name>.
3. Set webroot_dir in the authenticator configuration to that directory.
4. Restart the service and request the authenticator context path in a browser.

If the page loads but the flow stalls, the cause is usually one of the following:

Symptom	Likely cause
Assets return 404.	The build uses absolute asset paths, or the entry point is not named index.html and view_path is not set.
API requests return the HTML page instead of JSON.	The request is not a PUT, or the Content-Type header is missing.
Every API request starts a new authentication.	Cookies are not sent, typically because the request is issued cross-origin.
Old files are still served after a deploy.	An overlay directory still contains resources that take precedence over the web root, or a cached response is being reused.

Related pages

• Web Authenticator API — message format and common message types
• Common configuration — configuration shared by all authenticators
• User interface — branding the built-in applications
• ExternalFlow — delegating a step to an external service