Orbeon Forms
  • Getting started
  • Installation
    • Logging
    • Configuration banner
    • Docker
    • Azure
    • Tomcat
    • WildFly
    • WebSphere
    • WebLogic
    • GlassFish
    • Caches
    • Replication
    • Upgrading
  • Configuration
    • Properties
      • General
        • HTTP client
      • Form Runner
        • Detail page
          • Attachments
          • Email properties
          • PDF
          • Table of contents
        • Persistence
        • Summary page
      • Form Builder
      • XForms
    • Advanced
      • Workflows
      • Session management
      • State handling
      • Client-side error handling
      • Clustering and High Availability
      • Configuring a Form Runner eXist database
      • Creating a production WAR
      • Environments
      • JavaScript and CSS assets
      • Limiter filter
      • Run modes
      • Security
        • Content-Security-Policy header
      • SAP Hybris Module
      • XForms logging
    • Troubleshooting
      • Troubleshooting with the orbeon.log
      • Memory and threads
      • Relational database logging
      • Misc
  • Form Builder
    • Form settings
      • Time window
    • Form editor
      • Form area
      • Toolbox
      • Buttons bar
      • Control settings
      • Dependent fields and sections
      • Validation
      • Choices editor
      • Publishing
      • Cut, copy and paste
      • Section and grid settings
      • Section settings
      • Grid settings
      • Quick control search
      • Repeat settings
      • Repeated grids
      • Undo and redo
      • Keyboard shortcuts
    • Formulas
      • Examples of formulas
      • Formulas inspector
      • Formulas console
    • Summary page
    • Form localization
    • Advanced
      • Edit source
      • Services and actions
        • HTTP services
        • Database services
        • Simple Actions
        • Action Syntax
        • Action Syntax examples
        • Synchronizing repeated content
      • Testing a form in web mode
      • Testing PDF production
      • Testing offline functionality
      • Email Settings dialog
      • Field-level encryption
      • Messages
      • Section templates
      • Template syntax
      • XML Schemas support
      • Extensibility
        • Extension API
        • Integration
        • Toolbox component metadata
  • Form Runner
    • Overview
      • Terminology
    • Pages
      • Landing page
      • Published Forms page
      • Forms Admin page
      • Summary page
    • Components
      • Alert dialog
      • Attachment
      • Autocomplete
      • Captcha
      • Character counter
      • Checkbox input
      • Currency
      • Date
      • Dropdown date
      • Static and dynamic dropdown
      • Error summary
      • Grid
      • Handwritten signature
      • Hidden field
      • Image
      • Image annotation
      • Image attachment
      • Number
      • Open selection
      • Repeater
      • Formatted Text / Rich Text Editor
      • Section
      • Single-selection tree
      • Source code editor
      • Time
      • US phone
      • US state
      • Video
      • Video attachment
      • Wizard
      • XForms inspector
      • Yes/No answer
    • Features
      • Automatic calculations dependencies
      • Datasets
      • Excel and XML import
      • Excel and XML export
      • Summary page Excel Export
      • Form definitions and form data Zip Export
      • Purging historical data
      • Lease
      • Localization
      • Supported languages
      • Mobile support
      • Multitenancy
      • Form Runner navigation bar
      • PDF production
        • Automatic PDF
        • Automatic PDF header and footer configuration
        • PDF templates
      • Responsive design
      • Revision history
      • S3 storage
      • Simple data migration
      • TIFF production
      • Versioning
      • Wizard view
      • Workflow stage
    • Persistence
      • Using a relational database
      • Relational database schema
      • Purging old data using SQL
      • Auditing
      • Autosave
      • Database support
      • Flat view
    • Linking and embedding
      • Linking
      • Java Embedding API
      • JavaScript Embedding API
      • Liferay full portlet
      • Liferay proxy portlet
      • Securing Form Runner access
      • Form Runner offline embedding API
      • Angular component
      • React component
    • Access control and permissions
      • Users
      • Login & Logout
      • Deployed forms
      • Form fields
      • Editing forms
      • Owner and group member
      • Organizations
      • Scenarios
      • Token-based permissions
    • Styling
      • CSS
      • Grids CSS
      • Automatic PDF styling and CSS
    • APIs
      • Authentication of server-side service APIs
      • Persistence API
        • CRUD API
        • Search API
        • List form data attachments API
        • Form Metadata API
        • Lease API
        • Reindexing API
        • Caching
        • Versioning
        • Revision History API
        • Zip Export API
        • Custom persistence providers
      • Other APIs
        • Connection context API
        • Duplicate form data API
        • File scan API
        • Form Runner JavaScript API
        • Generate XML Schema API
        • PDF API
        • Publish form definition API
        • Run form in the background API
      • Data formats
        • Form data
        • Date and time
        • Form definition
    • Architecture and integration
      • Architecture
      • Access form data
      • Integration
    • Advanced
      • Buttons and processes
        • Simple process syntax
        • Core actions
        • Form Runner actions
          • Save action
          • Send action
          • Email action
        • XForms actions
        • Predefined buttons, processes and dialogs
        • Summary page buttons and processes
      • Custom dialogs/model logic
      • Services
      • Singleton form
      • Monitoring HTTP requests
  • XForms
    • Core
      • Attribute Value Templates (AVTs)
      • Binds
      • Validation
      • Variables
      • Keyboard focus
      • XForms JavaScript API
      • Error handling
        • Detailed behavior
      • Model-Bind variables
      • XForms 2.0 support
    • Events
      • Standard support
      • UI refresh events
      • Keyboard events
      • Extension events
      • Extension context information
      • Other event extensions
    • Actions
      • Repeat, insert and delete
      • Scripting actions
      • Extensions
    • Controls
      • Label, hint, help
      • Input
      • Output
      • Text area
      • Button
      • Upload
      • Dialog
    • Submission
      • Standard support
      • JSON support
      • Asynchronous submissions
      • Caching extension
      • Other submission extensions
    • XPath
      • Type annotations
      • Expression analysis
      • Tips
      • Compatibility
      • Standard functions
      • Maps and arrays Functions
      • Extension functions
        • Core functions
        • Utility functions
        • Model functions
        • Controls functions
        • XML functions
        • JSON functions
        • HTTP functions
        • Form Runner functions
        • Other functions
        • Deprecated functions
    • XBL components
      • FAQ
      • Guide
        • XBL Tutorial
        • Bindings
        • XForms models
        • Including content
        • Event handling
        • Conventions
        • Map XBL example
        • Learning from existing components
      • Advanced topics
        • XBL Modes
        • JavaScript companion classes
        • XBL library
        • Extensions
        • Attachment controls
    • XForms tutorial
      • Introduction
      • Installation
      • The Hello application
      • The Bookcast application
        • The basic app
        • Database access
        • Polishing the app
        • Adding a feed
    • Using XForms from Java apps
  • XML Platform
    • Page Flow Controller
      • Basics
      • XML submission
      • Navigating between pages
      • Paths and matchers
      • Other configuration elements
      • Typical combinations of page model and page view
      • Examples
      • Authorizing pages and services
    • Processors
      • URL generator
      • Request generator
      • PDF to image converter
    • Resources
      • Resource managers
      • Setting up an external resources directory
    • Other
      • Binary and text documents
  • FAQ
    • Licensing
    • PE and Dev Support
    • Form Builder and Form Runner
    • Resources and support
    • Other technical questions
  • Contributors
    • Automated tests
    • Building Orbeon Forms
    • Localizing Orbeon Forms
    • Validation functions
    • Contributor License Agreement
  • Release notes
    • Orbeon Forms 2022.1.9
    • Orbeon Forms 2024.1.1
    • Orbeon Forms 2023.1.7
    • Orbeon Forms 2024.1
    • Orbeon Forms 2023.1.6
    • Orbeon Forms 2023.1.5
    • Orbeon Forms 2021.1.11
    • Orbeon Forms 2022.1.8
    • Orbeon Forms 2023.1.4
    • Orbeon Forms 2023.1.3
    • Orbeon Forms 2023.1.2
    • Orbeon Forms 2022.1.7
    • Orbeon Forms 2023.1.1
    • Orbeon Forms 2023.1
    • Orbeon Forms 2022.1.6
    • Orbeon Forms 2021.1.10
    • Orbeon Forms 2022.1.5
    • Orbeon Forms 2021.1.9
    • Orbeon Forms 2022.1.4
    • Orbeon Forms 2022.1.3
    • Orbeon Forms 2021.1.8
    • Orbeon Forms 2022.1.2
    • Orbeon Forms 2022.1.1
    • Orbeon Forms 2022.1
    • Orbeon Forms 2021.1.7
    • Orbeon Forms 2021.1.6
    • Orbeon Forms 2021.1.5
    • Orbeon Forms 2021.1.4
    • Orbeon Forms 2021.1.3
    • Orbeon Forms 2021.1.2
    • Orbeon Forms 2021.1.1
    • Orbeon Forms 2021.1
    • Orbeon Forms 2020.1.6
    • Orbeon Forms 2019.2.4
    • Orbeon Forms 2019.1.2
    • Orbeon Forms 2018.2.5
    • Orbeon Forms 2018.1.4
    • Orbeon Forms 2020.1.5
    • Orbeon Forms 2020.1.4
    • Orbeon Forms 2020.1.3
    • Orbeon Forms 2020.1.2
    • Orbeon Forms 2019.2.3
    • Orbeon Forms 2020.1.1
    • Orbeon Forms 2020.1
    • Orbeon Forms 2019.2.2
    • Orbeon Forms 2019.2.1
    • Orbeon Forms 2019.1.1
    • Orbeon Forms 2019.2
    • Orbeon Forms 2019.1
    • Orbeon Forms 2018.2.4
  • Release history
  • Use cases
  • Product roadmap
  • Index of features
Powered by GitBook
On this page
  • Availability
  • Rationale
  • Basic operation
  • Configuration
  • Public methods
  • Backward compatibility
  • Authorization service
  • How the authorization service works
  • A simple authorization service
  • Implementing your own service
  1. XML Platform
  2. Page Flow Controller

Authorizing pages and services

Availability

This feature is available since Orbeon Forms 4.0. Orbeon Forms 3.9 and earlier did not protect pages and services as described below.

Rationale

Orbeon Forms runs within a the servlet container. This has huge benefits, including portability. But in general, such a container is fairly inflexible. For example, you cannot match pages based on regular expressions, and you cannot specify two different forms of authentication in the same web application based on whether you're targeting a page or service (such as form-based authentication, versus basic authentication). In addition, it is not easily possible for a web application to have full access to the container's authentication and authorization mechanisms, certainly not in a pain-free and portable way.

On the other hand, Orbeon Forms would like to allow some level of configuration of this directly in a page flow. The solution chosen is a solution of delegation.

Basic operation

When a request for a page or service reaches the controller, the following takes place by default:

  1. The controller checks whether the request is an internal request, that is, a request from a local Orbeon Forms application. If that's the case, the request is allowed (this is based on a mechanism of private tokens).

  2. If the request is not internal, the controller then checks whether the request has a public method. If so, the request is allowed.

    • For pages, the public methods are GET and HEAD by default.

    • For services, there are no public methods by default.

  3. If the method is not public, the controller then delegates to an authorization service.

Configuration

Public methods

By default, the following applies for requests outside of Orbeon Forms:

  • Pages: the GET and HEAD HTTP methods are allowed and all other HTTP methods are disallowed.

  • Services: all HTTP methods are disallowed.

This matches the following default properties:

<property
  as="xs:string"
  processor-name="oxf:page-flow"
  name="page-public-methods"
  value="GET HEAD"/>

<property
  as="xs:string"
  processor-name="oxf:page-flow"
  name="service-public-methods"
  value=""/>

In your properties-local.xml you can change those defaults, for example:

<property
  as="xs:string"
  processor-name="oxf:page-flow"
  name="page-public-methods"
  value="GET HEAD POST"/>

<property
  as="xs:string"
  processor-name="oxf:page-flow"
  name="service-public-methods"
  value="GET HEAD"/>

WARNING: Changing those defaults can introduce serious security risks. Please understand the impact that doing so might have.

On a per-controller basis, the <controller> element supports two attributes, page-public-methods and service-public-methods. These override the global properties:

<controller xmlns="http://www.orbeon.com/oxf/controller"
  page-public-methods="GET HEAD POST"
  service-public-methods="GET HEAD">

Finally, the <page> and <service> elements support the public-methods attribute, which allows setting the list of public methods for a given page or service:

<page    public-methods="GET HEAD POST" view="view.xpl"/>
<service public-methods="GET HEAD"      view="view.xpl"/>

In addition to any HTTP method name, the property or attribute supports the #all token to indicate that all methods are allowed.

Backward compatibility

With previous versions of Orbeon Forms, requests were unrestricted. Although we don't recommend it, if you want to, you can enable the old behavior with the following properties:

<property
  as="xs:string"
  processor-name="oxf:page-flow"
  name="page-public-methods"
  value="GET HEAD POST PUT DELETE"/>

<property
  as="xs:string"
  processor-name="oxf:page-flow"
  name="service-public-methods"
  value="GET HEAD POST PUT DELETE"/>

Authorization service

You can configure the authorization service via a property:

<property
  as="xs:anyURI"
  processor-name="oxf:page-flow"
  name="authorizer"
  value="/orbeon-auth"/>

The value of this property is either an absolute URL or an absolute path. If it is an absolute path, it is resolved against the host receiving the request. For example, if your servlet container is deployed on http://localhost:8080/, the path above resolves to http://localhost:8080/orbeon-auth.

This means that the authorization service can reside within the same container as Orbeon Forms, or in a completely different location.

How the authorization service works

It's pretty simple: Orbeon Forms forwards the incoming request to that service. This includes: HTTP method, headers, and requested path. Note, that even in the case of a POST or PUT, the request body is not forwarded. The requested path is appended to the path of the authorization service. For example, if the request was for the following service:

/fr/service/exist/crud/acme/gaga/form/form.xhtml

with the settings above, the following URL would be called:

http://localhost:8080/orbeon-auth/fr/service/exist/crud/acme/gaga/form/form.xhtml

This allows the authorization service to discriminate between different types of pages and services.

[SINCE Orbeon Forms 2016.3]

An additional header, Orbeon-Remote-Address, is passed, with the value of the incoming request's remote address, if any. This allows the authorizer to filter on the remote IP without the need for a separate IP filter.

A simple authorization service

Orbeon Forms ships with a very simple WAR file: orbeon-auth.war. This war file contains a dummy servlet and a web.xml with stub to configure BASIC authentication. You typically deploy this WAR file within the same servlet container as the main Orbeon Forms WAR file. This means that you can set the property above to /orbeon-auth. Here is the default content of the web.xml:

<web-app version="2.4"
         xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/j2ee">
    <display-name>Optional authorizer for Orbeon Forms</display-name>
    <description>
        See "Authorization of pages and services" in the Orbeon Forms doc:
        https://doc.orbeon.com/xml-platform/controller/authorization-of-pages-and-services.html
    </description>
    <servlet>
        <servlet-name>orbeon-authorizer-servlet</servlet-name>
        <servlet-class>org.orbeon.oxf.controller.AuthorizerServlet</servlet-class>
    </servlet>
    <!-- The authorizer servlet handles any request -->
    <servlet-mapping>
        <servlet-name>orbeon-authorizer-servlet</servlet-name>
        <url-pattern>/*</url-pattern>
    </servlet-mapping>
    <!-- Example: require that all external requests to Form Runner services are
         authenticated with BASIC authentication and have the orbeon-service role.
         Block any other request. -->
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Form Runner services</web-resource-name>
            <url-pattern>/fr/service/*</url-pattern>
        </web-resource-collection>
        <auth-constraint>
            <role-name>orbeon-service</role-name>
        </auth-constraint>
    </security-constraint>
    <security-constraint>
        <web-resource-collection>
            <web-resource-name>Everything else</web-resource-name>
            <url-pattern>/*</url-pattern>
        </web-resource-collection>
        <!-- Make sure there is an empty auth-constraint to require authentication.
             But since there are no constraints specified, authentication will always
             fail. -->
        <auth-constraint/>
    </security-constraint>
    <login-config>
        <auth-method>BASIC</auth-method>
    </login-config>
    <security-role>
        <role-name>orbeon-service</role-name>
    </security-role>
</web-app>

With this setup, a request for an Orbeon Forms page or service is forwarded to this authorization service. If the request comes with appropriate credentials for BASIC authentication which translates into a user with the given role, the servlet returns a successful response, and the request is authorized. Otherwise, the request is denied, and the request to the page or service is rejected.

Note that this example is just about the simplest way that you can implement the authorization service. But you most likely will want to do some more advanced configuration. Also, note that you are not limited to BASIC authentication. You could for example fully delegate authorization to your own servlet.

Implementing your own service

You don't have to use the WAR provided to implement your service. You can implement your own servlet, or in fact implement your own service which can reside on any server and be written with any technology you like.

Just make sure that your service responds with a successful HTTP return code when the request is authorized, and a non-successful HTTP return code when the request is not authorized (such as 401 or 403).

It is very important to validate services independently from logged in users. This is because in general, human users of the application must not be able to access services directly!

PreviousExamplesNextProcessors

Last updated 1 year ago

By default, this configuration enables BASIC auth and only authorizes requests with a role called orbeon-service. This role is arbitrary. You can configure your servlet container to handle any role. If you are using Tomcat, you can for example configure users and roles in the .

If you are using Orbeon Forms 2023.1 or newer, and are running a servlet container that uses the Jakarta Servlet API (e.g. Tomcat 10+, WildFly 27+), you need to use the org.orbeon.oxf.controller.JakartaAuthorizerServlet servlet class instead of org.orbeon.oxf.controller.AuthorizerServlet.

tomcat-users.xml file
[SINCE Orbeon Forms 2023.1]