Authentication & authorisation

By default, a Flow requires authentication. Authentication is normally handled by a trusted SAML identity provider, and authorisation can then be based on role information from the incoming SAML assertion.

How authentication is connected

Forms must be connected to a SAML SP authenticator. The SAML SP and Forms module need to share the same first URI segment so that login, callback, and Flow URLs are routed correctly.

For example, if the Forms module uses /forms as its HTTP context, the SAML SP can use /forms/authn.

Forms module configuration:

{
  "http_context": "/forms",
  "http_auth_redirect_url": "/forms/authn/login"
}

SAML SP configuration:

{
  "http_context": "/forms/authn",
  "success_location": "/forms/"
}

After authentication, data from the incoming SAML assertion is added to the session. NameID becomes the user's login identifier. Other SAML attributes are also stored in the session. Multi-valued attributes are merged into comma-separated values.

Session values can then be used in Flow, Step, and Control configuration with expressions such as:

• ${session.id}
• ${session.trace_id}
• {{session.subject}}
• {{session.username}}

Public Flows

Set public to true when a Flow should be available without authentication.

{
  "name": "external-registration",
  "public": true,
  "steps": "@include:steps/*.json"
}

Use public Flows only when the process is designed for unauthenticated users, such as selected self-registration scenarios.

Role-based access

When a Flow is authenticated, access can be restricted with role requirements. The roles are read from the incoming assertion and stored in the session.

Use one of these properties, not both:

Property	Access rule
requires_any_role	The user must have at least one of the listed roles
requires_all_roles	The user must have all listed roles

Example using requires_any_role:

{
  "name": "manage-users",
  "requires_any_role": [
    "manager",
    "service-desk",
    "user-admin"
  ],
  "steps": "@include:steps/*.json"
}

Example using requires_all_roles:

{
  "name": "privileged-user-review",
  "requires_all_roles": [
    "security-reviewer",
    "privileged-access-admin"
  ],
  "steps": "@include:steps/*.json"
}