Authentication of server-side service APIs
Endpoints
All Form Runner server-side service APIs have entry points starting with /fr/service/.
Authentication and authorization
Form Runner services are protected (authenticated and authorized) separately from Form Runner pages. One reason for this is that a human user might use form-based authentication, while a service typically doesn't. So in general, it makes sense to handle services separately from pages.
In particular, by default, when you enable <security-constraint>s in Orbeon Forms's web.xml, Form Runner services are not protected.
Instead, Form Runner services are protected as described in Authorization of Pages and Services. Specifically:
By default, any external access is prohibited.
You can optionally set up an authorizer, which authorizes access to services.
A default authorizer is provided, which can authorize requests based on servlet container configuration.
A custom authorizer has full flexibility.
It is possible to fully open access, but for development only.
Service user vs. Form Runner user
When authenticating with a service API, a single service user is used. This is unlike application pages.
Internal service calls
Form Runner often performs internal service requests. For example:
The Form Runner Summary page calls the Search API.
The Form Runner Detail page calls the CRUD API.
In such cases, the user is already authorized and authenticated (or may be anonymous) when accessing the page, and the user credentials are directly passed to the internal service call. In this case, the authorizer is not used at all.
Providing user information
[SINCE Orbeon Forms 2022.1]
Until Orbeon Forms 2021.1.x included, it was not possible to easily pass user information when calling service APIs. It was only possible by using a workaround, such as deploying another instance of Orbeon Forms configured to use header-based authentication, separately from the rest of the application. In some cases, if you were using header-based authentication, this might work as well.
With Orbeon Forms 2022.1 and newer, you can pass user information using Orbeon Forms HTTP headers:
If using individual headers
Orbeon-UsernameOrbeon-GroupOrbeon-Roles
If using a single header with JSON:
Orbeon-Credentials
These headers work as described in Header-driven method.
COMPATIBILITY NOTE: If, with earlier versions of Orbeon Forms, you were calling service APIs and passing headers, they had to match the headers configured with the header-driven method. Starting Orbeon Forms 2022.1, the headers can only be the Orbeon-* headers as specified above.
See also
Last updated