Access: One Framework Technical Guide

1. Introduction

This document describes the components and functionality of the Pirean Access: One identity and access management (IAM) system.

Access: One is designed to allow sophisticated, bespoke user lifecycle and single sign-on solutions to be built by combining IAM application components in different ways. Although Access: One provides a rich set of IAM functions as standard, it can also act as an orchestrator of other applications. This flexibility allows it to be effective across a range of IAM modes, business-to-consumer, business-to-partner and workforce:

Figure 1. Different IAM modes

In this document you will learn about the structure of Access: One, the operation of the core orchestration engine and the product's capabilities for identity management and SSO.

2. Product Overview

2.1 The Roles of Access: One

As described above, Access: One can be used to build IAM solutions for a variety of purposes. Typically it can be envisaged as sitting in the middle of a number of identity and access-related services:

Figure 2. Access: One’s role in an IAM solution

As the diagram indicates, Access: One performs a number of roles from its position at the heart of an IAM solution:

  1. Single sign-on SAML federated SSO and OpenId Connect SSO is built in to the product, which provides the basis for most SSO requirements, particularly for modern cloud-based applications. However, there are sometimes cases where a login target cannot support SAML or OpenId Connect federation in which case Access: One also has a custom Form-Based Single Sign-On mechanism built into the product. Access:One may also be linked to a reverse proxy (for example IBM Security Access Manager Reverse Proxy), which can inject user credentials into the HTTP requests.

  2. Multi-factor authentication Several alternative authentication mechanisms are provided as standard. The Access: One architecture allows other third party mechanisms to be plugged in as required.

  3. User provisioning lifecycle Access: One provides identity management services for creation, update and deletion of user accounts. The vehicle for this is an "IDM" layer within the Access: One framework, which defines a common set of identity management services. This is underpinned by multiple software implementations of the services, each of which addresses a different type of user registry or application target.

  4. User self-service processes Access: One includes capabilities for self-registration, forgotten password recovery and out-of-band notifications in support of identity and verification procedures.

  5. Rich user interfaces The standard Access: One Webtop user interface for workforce IDM offers a powerful and intuitive home for users to interact with the IAM system, both as a launch pad for single sign-on and by providing tools to allow the user to manage their own account, request and approve access changes and handle notifications.

  6. Publish IDM services for application consumption The framework provides a REST interface that allows bespoke web services to be created, thereby allowing applications to integrate identity operations with business logic. This interface is secured using bearer tokens and the OAUTH protocol is available to allow an application to perform requests under the identity of the logged-in user.

  7. Orchestration of other identity management applications The native Access: One user provisioning capability can handle many scenarios successfully. However, there are occasions where it is more appropriate to use the Access: One orchestration capability to drive other identity management products, either because they are already in place, or because they offer capabilities that are beyond the scope of the product (such as governance controls, separation of duties policies, or other extended policy options).

  8. Single Logout Access:One supports SP-initiated Single Logout in accordance with the Redirect Binding for Single Logout in the SAML Specification.

The following sections deal with these capabilities in more detail.

2.2 SSO functions

Access: One supports both SAML v2 and OpenID Connect for single sign-on. It can also integrate with IBM Security Access Manager (ISAM) reverse proxy for non-standard SSO scenarios.

2.2.1 SAML Support

SAML V2 is supported for federated single sign-on in the following modes:

  1. As an Identity Provider (IDP), it can handle SP-initiated authorization requests and generate SAML v2 assertions. These assertions are signed and may include additional attributes (the orchestration engine can use the logged-in user's identity details, enriched with data for business systems or other sources, as a source of attribute data). Attributes may also be encrypted, if required by the receiving site. The IDP function supports authorization requests using the HTTP Redirect binding and can send assertions using the HTTP POST binding.

  2. As a Service Provider (SP), it can receive and process signed assertions through the HTTP POST binding method.

2.2.2. OpenID Connect

Access: One supports OpenID Connect 1.0 using the Authorization Code flow. In this mode, Access: One plays the authorisation server role, in which it verifies a user's identity and creates a one-time authorization code, using which a relying party ("client application", in OIDC terms) can request:

  • An identity token, which securely asserts the identity of the logged-in user
  • An access token, which can be used to request services from Access: One, executed in the persona of the logged-in user

2.3. Multi-factor authentication

Access: One internally tracks the logged-in user's Level of Assertion (LoA). This is a value based on the NIST SP-800 publication that seeks to quantify the strength of a user's authentication credentials:

  • 0.0 - unauthenticated

  • 1.0 - authenticated using a replayable method - for example a username and password

  • 2.0 - authenticated using a non-replayable method, for example a one-time code or challenge-based mechanism

  • 3.0 - two factor, based on a combination of replayable and non-replayable methods

  • 4.0 - PKI-based authentication

Access: One also introduces a special LoA of 0.5, which is used to indicate a user who has not logged in, but whose ID has been recalled using an opaque tracking cookie.

The product currently offers, as standard, the following authentication options:

  • Username and password, verified against an LDAP server or Active Directory

  • One-time passcode, sent via SMS

  • Google authenticator (TOTP generator)

  • Gemalto TOTP and one-time code

  • QRyptologin challenge (this is a smartphone app that receives a challenge in the form of a QR barcode and generates a one-time PIN from it)

  • Challenge for characters from a memorable word or phrase

  • Secure PIN digit challenge

  • Voice-Recognition Login mechanism, achieved through integration with ArmorVox for Voice recognition and Voxeo for interactive voice response.

Other mechanisms can be added through the plugin framework.

2.4. User provisioning

The identity management (IDM) subsystem in Access: One is designed to allow multiple user registry targets be represented in a common way within the framework. The operation of this interface is described in more detail later in this document.

The list of IDM implementations is growing all the time, but the currently-supported targets include:

  • LDAP
  • Active Directory
  • Google
  • Office365 / Azure
  • Salesforce
  • IBM SAM
  • MaaS 360
  • Slack
  • ExpenSys

2.5 User self-service processes

Self-service processes are an aspect of identity management that can encompass a lot of variation. For example, it may be suitable for a low-sensitivity customer application to only require that a user clicks a one-time link in an email to reset their password, whereas a more sensitive application may demand that the user provides more rigorous proof of identity and even requires that third-party approval is obtained.

The correlation engine allows any such processes to be created, customised for the specific customer requirement. The "out of the box" workforce offering includes self-registration, a self-service dialog for users to update their own details, and uses a memorable phrase challenge for the password reset function.

2.6 User interfaces

The user interfaces of Access: One implementations fall into two categories:

  • Conventional guided user journeys. These use simple HTML pages, where the user's progress through the application is controlled by the orchestration engine.

  • Single-page applications. The home page for these is delivered in the same way as the conventional journey, but from that point the user experience is controlled by client-side logic, usually implemented using AngularJS. In this case, the client-side code communicates with the server through REST requests.

In both cases, the templates from which the HTML pages are constructed are Thymeleaf views. This technology has the advantage that the templates are valid HTML, meaning that they can be viewed in local, isolated, mode; without the Access: One server at the back end.

Any web page published by Access: One can be internationalised, presented in the language selected by the end user, by referencing translated message catalogs. Any dialog can be presented using different themes (the CSS and images used) to project the brand(s) required by the customer.

2.7 REST services

In addition to browser dialogs, Access: One offers a REST-style web service interface. This allows applications to consume identity management services directly, which  can often be a more efficient process than more traditional propagation through the user lifecycle.

Authentication for the REST services varies, depending on the context:

  • Client code executed from within a browser inherits the session context of the browser session

  • Application services can use the OAUTH protocol to obtain an authentication token that asserts the identity of the logged-in user

  • Alternatively, application services may be issued with a long term authentication token which confers special privileges

In the later two cases, the token is passed to Access: One in the form of an Authorisation "Bearer" header.

3. Product Structure

Access: One comprises of three main servers, each of which is a JEE application. The applications run in either IBM WebSphere Application Server or Apache TomEE middleware.

The servers are as follows:

The Login Server (A1Login). This is the service that contains the orchestration engine and handles all requests made by an end user (both browser dialog and REST). The orchestration engine executes workflows, which are sequences of instructions that specify the functions to be executed. The job of A1Login is therefore to create the context within which the request will execute, map the request to the workflow that implements it, and then pass control to the workflow dispatcher function for processing. More detail of this is in the next section.

The Console Server (A1Console). This is an administration service that provides a graphical UI to create and manage orchestration workflows.

The Metadata Server. This provides access to the metadata database, which is used to track the relationships between users and the accounts they own and also contains notification, approval, device and access information.

The following diagram illustrates how these components are related:

Figure 3. Access: One framework components

Note

Login Server instances are typically duplicated for reasons of resilience and capacity. A load balancing capability is required to distribute sessions across the servers, which must support state-full ("sticky") sessions for browser interactions. 

The Console Server is only required when changing the Access: One configuration, not for normal operations, so it does not need to be replicated. Configurations are stored in a dedicated configuration database.

For the databases, DB2, Oracle or MySQL are supported

All security-relevant operations are audited to the Audit database. This database is also used for other purposes, such as short-term persistence of user state data.

3.1. Configuration Objects

The Access: One login server is a framework. It does nothing unless a configuration is built to tell it what to do. The configuration is held in a database and is built using the A1Console application. Existing configurations can be exported using the console and imported into other systems.

The main elements of a configuration are:

  • Tenants
  • Services
  • Mapping Rules
  • Federation
  • Policy Rules
  • Idm Configurations
  • Workflows
  • Themes

The most important of these are the workflows, because that is where the real work is done. Workflows will be covered in detail in the next section. The other elements are dealt with below.

3.2. Tenants, Services and Workflows

Figure 4. Access:One Console

Every request that is sent to A1Login has to be resolved into a trio of elements: a Tenant, a Service and a Workflow. A Tenant is a container for Services, and Services are containers for workflows. A Tenant and Service/Workflow pair is associated with a request based on Mapping Rules. See Mapping Rules for more information about how requests are matched to to a Tenant and Service/Workflow pair.

Figure 5. Tenant Federation

At the Tenant Level, the following configuration is defined:

  • Mapping Rules are defined for associating http requests to the tenant.
  • Idm Configurations are defined which contain environment-specific properties related to user provisioning.
  • Policy Rules are defined which allow a structured way to handle complex lifecycle logic.
  • Federation is defined (shown in the screenshot above). At the tenant level, Federation contains information related to Access:One as a SAML Identity provider, for example the IDP Entity Id** - This information is used when creating and signing SAML assertions and is needed when integrating with SAML service providers. SAML metadata can be generated from the A1:Console which contains the public key needed by service providers to verify SAML assertions signed by Access:One.
  • Services are defined.

A Service contains:

  • Workflows, which encapsulate the steps to execute business logic.
  • The Theme to use. The Theme is only meaningful for browser dialog type requests. It is a reference to a set of folders in which the HTML and CSS elements to use are found. A workflow can be paired with any Service, so by assigning a different theme to different Service, the same function can be executed, but using different UI branding.
  • SAML Service-Provider Federation details are also defined at the Service level. 2 types of Federation can be set up: Federation where A1 is playing the role of an Identity Provider, or Federation where A1 is playing the role of a Service Provider. In the common case where A1 is playing the role of an Identity Provider, the Service Federation will contain information such as the Assertion Consumer URL for a SAML Service Provider where SAML Assertions should be sent, and the Sp Issuer value which is normally placed in the Audience field of a SAML Assertion. The workflow for handling Single Sign-On for a particular service-provider is also defined here. In the rarer case when A1 is playing the role of a Service Provider, the Service Federation will contain information about the IDP being used to single sign-on into A1.
  • A Service must have an alias which is a unique identifier for the Service which can be used to match a http request to the Service. See user provisioning for more details).

Figure 6. Example workflow

A workflow (example shown above) consists of a series of plugin steps. When a workflow is executed, each plugin is executed one-by-one until the workflow completes and a response is generated. Next-Step Rules are used to control the flow of execution in a workflow by branching to different steps in a workflow depending on the result of a condition, such as the output of a particular plugin. A workflow can also be assigned a minimum LOA (level of assurance) and a re-authentication workflow, so a workflow will only be allowed to execute if the user in the current session is authenticated to the required level. Workflows allow bespoke business logic to be quickly and securely built by putting together plugins. See Orchestration Engine for more details.

3.3. Access: One URLs and Mapping rules

When A1Login receives a HTTP request, it must decide what operation to execute by determining:

  • which Tenant a request is associated with
  • which service/workflow pair to execute
  • whether the request is a browser dialog or a REST request

The Tenant a request is associated with is determined using a Tenant Mapping Rule

The Service/Workflow Pair to execute and the request mode (dialog or REST) is determined using either:

3.4 Tenant Mapping Rules

Figure 7. Tenant mapping rule

Tenant Mapping Rule's can be configured in the Access:One Console (shown in the screenshot above). They consist of a URL host pattern, a URL path pattern and mapping patterns (optional). Configuring Tenant Mapping Rules is only available when there is a multi-tenant configuration. If a configuration contains only one tenant, all requests will be mapped to that tenant.

The host pattern is a pattern which is compared against the host part of an incoming request URL. For example: [hostpattern: ] will match any hostname, whilst [hostpattern: customer1] will only match URL's which start with https://customer1/

The path pattern is a pattern which is compared against the URI after the hostname of an incoming request URL. For example: [pathpattern: ] will match any URI. [pathpattern: /users] will match https://hostname/Login/users but will not match https://hostname/Login/notusers/etc [pathpattern: */users] will match https://hostname/Login/xyz/users

Mapping Patterns are used to match against request parameters. For example: [ uid=* ] will match incoming request URL's with a uid request parameter, such as https://hostname/Login/users?uid=man If there are no parameter mapping patterns, the implication is that any parameters are accepted.

A few complete examples are listed below:

hostpattern: foo, pathpattern:* , mappingPatterns: (none) Will match: https://www.football.com/Login/users

Will not match: https://cricket.com/Login/users

hostpattern: * , pathpattern: /users, mappingPatterns: (uid= * ) Will match: https://hostname/Login/users?uid=123 https://hostname/Login/users?uid=123&username=joeuser

Will not match: https://hostname/Login/xyz/users https://hostname/Login/users/id/99

When a request is received by A1Login, the Tenant Mapping Rules will be searched in order. If a Tenant Mapping Rule is found with a host pattern, path pattern and mapping pattern that matches the incoming request, the Tenant associated with the matched Tenant Mapping Rule will be selected as the Tenant associated with the request. Once a Tenant has been selected, the A1 Framework can then proceed to determine what Service/Workflow pair within the Tenant should be executed. If no Tenant Mapping Rule matches the incoming request, an error is returned.

3.5 Standard form URLs

The standard URLs for Access: One operations take the following form:

<a href="https://hostname/Login/{dialog|rest}/appl/{svcalias}/wflow/{wflowalias}">https://hostname/Login/{dialog|rest}/appl/{svcalias}/wflow/{wflowalias}</a>

Note

"Login" is the default context root for Access: One; it may be modified during installation.

The "dialog" or "rest" element defines which type of request is being made. Dialog requests result in a page (view) being returned from a workflow, whilst REST requests result in JSON being returned from the executed workflow.

The {svcalias} element defines the alias of the Service under which the request is to run.

The {wflowalias} element defines the alias of the workflow to run.

So for example, the following URL:

<a href="https://hostname/Login/dialog/appl/Login/wflow/showLoginPage">https://hostname/Login/dialog/appl/Login/wflow/showLoginPage</a>

Will execute the workflow with alias showLoginPage in the Service with alias Login in the Tenant which a Tenant Mapping Rule that matches the URL. The workflow is dialog so will return a page.

For Services, defining an alias is mandatory, but for Workflows an alias is optional. This allows workflows to be created that are only accessed by being branched-to from other workflows, or from mapping rules.

In addition, when creating a REST request, the following HTTP headers should be present:

Content-type: application/json

Accept: application/json

3.6. Service/Workflow Mapping rules

Figure 8. Tenant mapping rule

Service/Workflow Mapping Rules are defined in the Access:One Console at the tenant level. Like Tenant Mapping Rules, they contain a host pattern, path pattern and mapping patterns for matching a URL. However, they also contain a dropdown for selecting a Service and Workflow and a flag to set whether the request is dialog or restful.

Once a Tenant has been associated with a request, if the incoming URL has a Standard form URLs, the Service and Workflow to execute will be determined based on the service alias and workflow alias in the URL. If the request does not have a standard URL format, the A1 Framework will search through the Service/Workflow Mapping Rules defined for the Tenant and execute the Service/Workflow pair defined in the first Mapping Rule which matches the incoming request.

For example, based on the screenshot above, the url https://hostname/Login/google will result in the Change Primary Email workflow in the Google Service being executed.

3.7. Mapping rules (R3)

Mapping Rules in Release 3 of the A1Framework take the form:

    <a href="https://hostname/Login/router.do?var=val[&var2=val2]...">https://hostname/Login/router.do?var=val[&var2=val2]...</a>

URLs in this form work only for browser dialog type requests, not for REST. To set up a mapping rule, the process is:

  • Create a new mapping rule in the console

  • Add a set of pattern mappings to the rule to match the parameters in the request. Patterns name-value pairs, where the "name" part is the name of an HTTP request parameter (such as "var" in the above example) and the "value" part is a pattern that the parameter must match, using asterisks as wildcards (a pattern of "va*" would match the example). If multiple patterns are defined, the URL must match all of them.

  • Open the Application to which you want the mapping rule to be attached and define the mapping rule/workflow pair, so that the whole thing forms a triple of the form: "rule X maps to Application Y workflow Z".

3.8. Dialog continuation URLs

When Access: One is orchestrating a user journey, each page in the journey simply needs to return control to the server, at which point the orchestration engine will decide what to do next. To specify this, the page should GET or POST a URL of the form:

https://hostname/Login/(anything...)/next

A1Login treats this as a request to "continue with the currently-executing workflow".

4. The Orchestration Engine and Plugin Model

The orchestration engine is the core of Access: One's functionality. It is the means by which IAM applications are constructed, both for user dialogs (where the engine dictates the journey taken by the user) and for REST services (where the engine is used to construct the logic required by the request).

The engine consists of a workflow dispatcher, which executes specified workflows on demand.

So what is a "workflow"?:

A workflow is a series of plugin instances, which are executed in sequence, unless a next-step rule is triggered

The job of the workflow builder, therefore, is to work out the sequence of plugins needed to (a) retrieve any data required, (b) process the data appropriately and (c) publish the result of the workflow in the form expected by the caller.

As each plugin instance is added to the workflow, it must be configured to do the job that is required of it, by setting Parameters, Input Mappings, Output Mappings and UDS settings. The following screen shot shows the add plugin dialog.

Figure 9. Add Plugin Dialog, showing facets to be configured

In the following sections we explore these concepts in more detail.

4.1. Plugins

An Access: One plugin is a small piece of code that performs a single IAM or utility function. The scope of the kind of things that a plugin can do is unlimited, but as a basic rule they should be very simple: the whole concept of the orchestration engine is that complex, customised operations can be constructed by joining together sequences of plugins in new and interesting ways.

In programming terms, a plugin is an implementation of a java interface. The key method it must implement is called execute() which will receive an input data object (class PluginInput) and must return an output data object (class PluginOutput). The following diagram shows the constituent parts of the input and output:

Figure 10. Plugin inputs and outputs

We explore these inputs and outputs in some more detail in the following sections.

4.2 Plugin state

A plugin signals what should happen next to the workflow dispatcher by means of a plugin state output. This field can have one of the following values:

COMPLETE This signals to the workflow dispatcher that the plugin has completed its processing and the next plugin instance in the sequence should be executed

NOT_COMPLETE This declares to the workflow dispatcher that this plugin has not finished its work yet and should be re-executed when the next response is received from the user. NOT_COMPLETE applies only to browser dialog workflows, not REST workflows.

WORKFLOW_COMPLETE This signals to the workflow dispatcher that processing is complete for this workflow and if there are further plugins they should not be executed.

When running through a workflow, if the last plugin in sequence signals COMPLETE, it is treated as WORKFLOW_COMPLETE.

4.3 Workflow Fields

Within a workflow, each plugin can emit data in the form of output fields and can receive data that has been emitted by previous plugins in the form of input fields. The type of data contained in these fields is not restricted so complex objects can be inputted and outputted by plugins, although in most cases they are simple strings.

The workflow dispatcher holds the data emitted by all the plugins in the workflow in memory (referred to as workflow fields). When constructing a workflow, the builder adds a plugin instance and must then set up input mappings to convert workflow fields that are in the workflow context into input fields to be consumed by the plugin. The thought process for building a workflow therefore sometimes works in reverse - review what inputs are required by a key plugin and then work out what sequence of plugins will be required to get the data to it.

Note

Workflow field names are always stored in lower case, regardless of the case specified when they were output by a plugin.

Input mappings also allow other data sources to be brought in as workflow input fields, such as user context data and other fields. We will explore these so-called dotted names later. Output fields can also be mapped, but this is not commonly necessary. The only reason for doing so is if an output field needs to be renamed to avoid a clash (for example: a number of plugins return a data structure describing a user named idmuser; if the workflow logic called for two sets of user details to be present, it would be possible to map idmuser to "anotheridmuser", for example, to allow the dispatcher to hold both items).

4.4. HTTP request and response data

All of the details of the current HTTP request are present in the PluginInput class:

  • URL and request parameters (whether received as query string parameters in a GET request or as request body parameters in a POST, PUT or PATCH)

  • Cookies

  • HTTP headers

  • Where the workflow is invoked by a REST request, the JSON body of the request is parsed and made available as a hash set

Note that these fields are available to all plugins in a workflow, but it is common practice when building a workflow for the initial plugin to capture the required fields from the request so that they are then available to be mapped as input fields in all subsequent steps. There is a built-in plugin ("Workflow - Populate Fields"), which provides this capability. For example the following console screen shot shows a very typical REST workflow:

Figure 11. Workflow example

The purpose of the workflow is to perform a user update action. The first two steps marshal the data required into workflow fields (the Workflow - Populate Fields Plugin is used to read the details from the HTTP request, followed by the Get User plugin to get details of the user to update). If no user is found by the Get User Plugin, the next step rule immediately branches to 'Return User Not Found'. Otherwise, the next step performs the actual update, using input data mapped from the workflow fields. The final step feeds the result of the update back to the caller.

As you would expect, plugins can define the HTTP response to be sent back to the requester. Indeed, the above example shows how this is done for a REST request - using the RESTful Return built-in plugin to set the HTTP status and JSON output to be returned. For browser dialog workflows, plugins need to return the next page to be shown and any "model" data required by the page. These pages are normally returned in the form of Thymeleaf templates, however Apache Velocity views are also supported as a page template format. Velocity is deprecated, though, because the views cannot be treated as plain HTML and therefore are difficult to work with when doing offline UI development. To distinguish between the two, Thymeleaf templates are specified as full file names, including a '.html" extension, whereas Velocity views are specified by the filename only, without the ".vm" extension. When in browser dialog mode, it is mandatory that a plugin should return a template or view if it exits with either the NOT_COMPLETE or WORKFLOW_COMPLETE state.

4.5. UDS and user principals

As described previously, Access: One has a number of ways to perform user authentication and expresses the strength of this authentication through the "Level of Assertion" value. Each of the authentication methods is actually implemented by a plugin (and further authentication methods can be added by writing further such plugins). Having performed the authentication, the A1Login server needs to remember the result.

The way that the Access: One framework does this is by means of a user data store (UDS). This is a data structure that is used to track the current user context. The following diagram shows the structure of the UDS:

Figure 12. UDS contents

As the diagram shows, the UDS is a collection of other objects: Principals, Attributes, Credentials and a Subject. When an initial connection is made to Access: One, the user gets a default, mostly empty, UDS with a Subject Name of "anonymous" and an LoA of 0.0. This UDS will be provided in the plugin input of every plugin that gets executed.

Imagine now that a workflow is executed containing a plugin instance that performs usernamepassword authentication. As part of its output, this plugin can assert a Principal in the UDS, which would have a username (in the Value field), and a Type of "password". The updated UDS containing this information will be available to any subsequent plugin in the workflow. However the LoA will still be 0.0 and the user will not be considered to have logged in. The reason for this is that the workflow builder must also indicate to the workflow dispatcher that the UDS subject must be updated. This is done by defining in the plugin configuration the workflow field containing the username that is to be placed in the UDS Subject. The following screenshot shows how this is done:

Figure 13. Setting the UDS subject in an authentication workflow

Once the UDS Subject name has been defined, Access: One automatically calculates the LoA from the Principal entries in the UDS, based on their Type values (so in the case of a single password type authentication, the value would be 1.0).

The UDS contains other information in addition to the Principals and Subject:

  • User Context is automatically populated with information about the user session - client address, device details, etc.

  • User Attributes may be populated by specifying the UDS as an target when defining output mappings

  • The Credential Vault can be populated with passwords collected during normal authentication or self-service operations. The password will be automatically encrypted.

4.6. Next-step rules

To change the order in which workflow steps are executed, next-step rules may be defined. These are defined within a plugin instance, but they actually execute after the plugin has completed its processing (after the execute() method has returned). Next-step rules are simple if-then branch statements that link a condition to an action.

The condition

Next-step rule conditions are made up of four elements:

  1. The plugin state returned by the plugin. This can be expressed as any of the three normal states (COMPLETE, NOT_COMPLETE and WORKFLOW_COMPLETE) plus the special ALL state, meaning: we don't care.

  2. The workflow field to be tested.

  3. The comparator to be used when testing the field. This is one of: Always, Simple match, Regex match, Exists, Does not Exist, Starts with, Ends with, Contains, Equal to, Not Equal to, Greater than, Less than, Greater than or equal to, Less than or equal to.

  4. The pattern or value to test the field against. It may contain asterisks to indicate any sequence of characters. The value may also take the form of a variable: ${fieldname} where "fieldname" is the name of a workflow field. In this way, one workflow field may be tested against another.

Note that the Exists and Does not exist condition do not need a pattern to be provided and the Always condition does not need either a workflow field or a pattern.

The action

Next -step rules can either branch to another step in the same workflow or to the first step of a different workflow. The branched-to workflow receives the same workflow fields as the branched-from workflow and processes through to its end in the normal way. However, if the last plugin exits with state COMPLETE, control returns to the branched-from workflow, at the step immediately after the branch.

4.7 Dotted names" in input maps and next-step rules

When mapping data into plugin inputs, or defining the field to test in next-step rules, the simplest case is if the field to be mapped or tested is a simple workflow field. So for example, the condition in the next-step shown below says explicity: get the workflow field named "searchresult" and check if it is not equal to the value "success"

Figure 14. Next Step Rule Example

However, there is other useful information that we may want to map into plugin inputs. This is defined by special extended field names, referred to as "dotted names". The following table describes the different types of dotted names that may be used:

Dotted name root Meaning and Example
user These fields are extracted for the UDS. Useful examples are: user.subject.name is the name of the UDS Subject, user.subject.loa is the current LoA, user.subject.attributes.xxx.values is the value of attribute named "xxx" which has been added to the UDS in an earlier workflow or step.
request These fields contain information about the current request. Useful examples are: request.applalias is the alias of the application under which the application is currently running, request.method is the HTTP method (GET, POST, etc) of the current request.
global These are fields defined in an external properties file, named global.settings. It is used to set environment-specific properties, which is useful as it means that the same workflow configuration can be used in different environments.The names are simply in the form: global.propertyname. The global setting  file is held in folder A1HOME/properties/tenant/default.
idmuser These are attributes extracted from an IDM user object. They will be described in the IDM section.
server These are fields defined in an external properties file and relate to the current login server (the server where workflow actions are run). The fields come in the form server.xxx, where "xxx" is a particular attribute of the server. For example, to get the name of the server, you would use the dotted name server.name.

4.8. Literal values in input maps

It is also possible to map literal strings into input maps, simply by surrounding the value to be mapped in with double quotes (").

Furthermore, literals can be combined with field names, by presenting the field name as ${fieldname} within the quoted string. Some examples:

"${lastname}, ${firstname}" "${global.myproperty_${request.applalias}}"

The last example uses recursive resolution, so that the application alias is first resolved and then substituted into the name of the global setting to be retrieved.

4.9. Plugin collections

Plugins are organised into collections of related functions which are shipped in the form of a zip file, containing the plugin configuration, jar file, pre-requisite jar files and supporting data (for example, sample page templates and message catalogs). By externalising function in plugins in this way, each Access: One installation need only have the plugins it needs for the particular solution it implements, rather than installing all of them. Two plugin collections "BuiltIn" and "IDM" are not handled this way, however. These are always required and are always present within the Access: One framework.

4.10. The Built-in plugin collection

This collection contains plugins that provide the glue for any orchestration workflow. Full Details of all the Built-in Plugins can be found at: link:../WorkflowGuide/PluginReference/Built-in/built_in_plugins.adoc[Built-in Plugins]. The following table contains summaries of some of the most important Built-in plugins:

Plugin Name Plugin Description
Assert Principal This allows you to create an authenticated user context without having executed a conventional authentication plugin. The kind of scenario where this is useful is a password reset operation where the user is emailed a one-time link. At the end of that process it is often a requirement that the user is automatically logged-in, which is facilitated by this plugin
Display Webpage This is the work-horse for browser dialog type workflows. It takes the name of the Thymeleaf template or Velocity view to display as a parameter. It also allows the resulting plugin state (COMPLETE or WORKFLOW_COMPLETE) to be configured
Drop Session This terminates an authenticated user context (i.e. it performs a logout)
Generate JWT Access: One uses Java Web Tokens as portable credentials for RESTful service requests and as part of the OAUTH protocol. This plugin allows a JWT to be generated for subsequent authentication purposes
NoOp This plugin does nothing special, which may not seem like a very useful capability, but in fact it is extremely useful when working with next-step rules, as it allows a place within the workflow where a rule can be defined that does not have any other purpose
Password Generator This plugin generates random strings of data, based on a template pattern. As the name suggests, it is useful for creating random passwords, but it has many other uses, notably when creating one-time codes for self-service operations
Persistent data (4 plugins) The persistent data store is a table within the audit database that is useful as a "scratch pad" of user-related data. There are four plugins that allow you to save workflow field values in the store, retrieve them, increment them and delete them. Persistent data entries are used for creating processes that require temporary data to be stored, such as state information and one-time codes
Redirect This is used in browser dialog workflows to generate a 302 Moved temporarily response to redirect the user to another site
RESTful Return This plugin is used at the end of a REST workflow to marshall the fields that should be in the response sent to the client
Send Email This plugin sends an email, using a Velocity view to format the email contents and populating it with data from workflow fields
Workflow - Populate field This plugin, as described previously is used to import data from the HTTP request into the workflow fields
Write audit record Most plugins that need to set an audit record will do so automatically. However, there may be specific requirements for auditing that are not covered in that way. This plugin allows a customer audit record to be fashioned and stored

4.11. Other plugin collections

Full details of other available plugin collections are available at: link:../WorkflowGuide/WorkflowGuide.adoc[Plugin Collections]. The following table contains a short summary of the other available plugin collections:

Plugin Collection Plugin Description
DelayedWorkflowTriggerPlugin Implements a method for workflows to be executed asynchronously. Useful when integrating long-running processes with time-critical dialogs, for example.
Google Authenticator Back-end integration for the Google Authenticator TOTP app
Google recaptcha Back-end integration for the Google reCaptcha widget
IDM The identity management plugins. Described in the next section
ISAM EAI implementation for the IBM Security Access Manager reverse proxy and ISAM user registry CRUD operations
ISIM Plugins that allow execution of IBM Security Manager operations
JMS Plugins for publish/subscribe processing
LDAP Generic plugins for LDAP operations (mostly superceded by the IDM implementation for LDAP)
Memorable phrase Plugins for implementing challenge-based authentication using a pre-recorded word or phrase
Metadata Plugins that interface to the Access: One metadata service
OAUTH Plugin that implements OAUTH clients for popular social media sites and OAUTH servers to allow applications to obtain user authentication tokens
Others Only one plugin in here, but it is an important one: the Input Validation Plugin provides filters to scan input fields for patterns that they should - and should not - contain
Pinshuffle An authentication method that combines a memorized PIN challenge with a Captcha-style test
QRyptologin A Pirean-developed authentication scheme in which an app on the user’s smart phone is paired with their account and uses strong encryption to derive a passcode from a challenge contained in a QR barcode
SAML Implementations of SAML v2 IDP and SP
SMS One-time code authentication and notifications using text messages
Webtop The server side of the Access: One Webtop launch panel for workforce IAM

4.12. Workflow operations

4.13. Dialog vs REST

The main differences between browser dialog workflows and REST workflows are as follows:

  • REST workflows are atomic: the workflow executes from beginning to end and the result of the last step is passed back to the client. By contrast, browser dialog workflows can remain in progress across a number interactions between the client and server.

  • Dialog workflows are required to return an HTML template for display by the browser, with optional model data. With REST workflows, any fields outputted by the final workflow step are converted into a JSON response.

  • Internal errors are reported to the browser by an error page for dialog workflows - for REST requests the server simply responds with a 500 HTTP status.

4.14. Workflow session behaviour - browser based sessions

In common with most Java applications, the browser based session is tied to the JEE server session cookie - JSESSIONID.

Workflow data fields remains in the session until the workflow terminates, at which point they are discarded. This means, for example, that in a browser dialog workflow which presents a sequence of pages to the user, the workflow fields stored by the first request to the server will still be available to plugins when the last request is being processed.

When a REST request is made within the context of a browser session (i.e. a Javascript application running in the browser and interacting with the server through REST calls) it receives a clone of the workflow data fields. This means it inherits any fields that have been set in the browser workflow, but it can only make changes to its own copy of those fields, not to the original version.

The UDS, however, is handled differently. It remains in the session beyond the end of the workflow, until the session times out or a "Drop session" plugin is executed. This means that once a user has authenticated, there is no need to re-authenticate while the JEE session remains intact and the LoA and other UDS-contained fields will continue to be available.

4.15. Workflow session behaviour - stateless sessions

If no session can be established from the JEE session, Access: One will look for a bearer header containing a Java Web Token (JWT). It will look something like this:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInRÉ

If the JWT has not expired and has been signed by the server's JWT signing key, it will be used to create an authenticated session context, which will last for the duration of the workflow.

JWTs are portable, signed credentials with a fixed life span that assert a user ID and LoA. They have the advantage that, where the A1Login servers are clustered, the JWT can be consumed by any of the servers so long as they share the same signing key.

Use of bearer tokens should be limited to cases where the client is trusted (for example, where it is executing on a server or within a trusted mobile device app). It is not good practice to place a JWT in a browser, for example, because the browser may have been compromised and unlike session cookies, the JWT does not expire if the user logs out or restarts the browser.

4.16. Restricting workflow execution to authenticated requests

When a workflow is defined, a minimum LoA can be defined, to prevent it from being executed by an unauthenticated user. This option is found under the "Advanced options" section of the workflow definition.

In this section it is also possible to optionally define a reauthentication workflow. This is a workflow that will be executed, once, at the point where the workflow dispatcher discovers that the current session does not have the required minimum LoA. After the re-authentication workflow has completed, the original request is attempted again.

This is useful when creating dialogs that must be executed by a logged-in user. By defining a generic login dialog as the re-authentication workflow, the user will be presented with a login form instead of the page they asked for, but once they have completed the form successfully they are returned to the requested page.

4.17. IDM and the Metadata Layer

The orchestration engine offers a great deal of flexibility when designing IAM processes and by creating plugin collections it is clear that additional targets for identity management can be easily created. However, when we consider the requirements for provisioning accounts into a new service, they can be categorized quite easily:

  • Always: CRUD operations for user accounts (create, read, update, delete)

  • In most cases: Password update operations and account lock/unlock, assign/remove roles

  • In some cases: Operations for password and account recovery and account lifecycle

The Access: One IDM interface is a definition of a set of modules that implement these identity management processes, over which are provided a standard set of plugins. For any service target that provides an API for account management, it is possible to create an implementation of the IDM interface, which will allow a standard set of Access: One workflows to perform account management on the target system. The following diagram illustrates the principle:

Figure 15. IDM component diagram

Pirean provide a number of IDM implementations "out of the box" and the range is extending constantly. In the following sections we will explore the functions of IDM and the use of the Access: One metadata service to link IDM user definitions together.

4.18. IDM configuration files

A key part of each IDM implementation is the configuration file. This is an XML file that defines everything about the particular service whose accounts are to be managed, such as:

  • Connection details and credentials for the service

  • Definition of where to locate new users and what object class to assign to them (where different user types are supported)

  • Rules for generation of user IDs and passwords

  • Rules for unique attribute restrictions

  • Rules for password reset challenges

Clearly, much of the content will be specific to the service type being defined, whereas other items may be more generic. The configuration file syntax is designed to allow extensibility to support this. As an example, the following snippet is the start of an IDM configuration for an LDAP implementation:

<A1IDMConfig name="A1IDMConfig" type="LDAP">

      <A1IDMParameters>

            <A1IDMparameter name="maxsearchresults">

                  <Value>1000000</Value>

            </A1IDMparameter>

            <A1IDMparameter name="readonlypool">

                  <Value>ldap://127.0.0.1:33390</Value>

            </A1IDMparameter>

            <A1IDMparameter name="readwritepool">

                  <Value>ldap://127.0.0.1:33390</Value>

            </A1IDMparameter>

            <A1IDMparameter name="bindid">

                  <Value>dc=com</Value>

            ...

When adding any IDM plugin to a workflow, it has a parameter that specifies the IDM configuration to use, so that when the workflow is loaded, an instance of the appropriate IDM instance is created, configured using the settings in the file.

4.19. IDM plugins

The standard set of IDM plugins covers all aspects of identity management.

Basic CRUD operations:

  • IdmRegistrationPlugin. Registers a new user using data from plugin input fields, generating userID and password if required

  • IdmGetUserPlugin. Gets user details

  • IdmUserSearchPlugin. Searches for users based on criteria passed as input fields

  • IdmUserUpdatePlugin. Updates a user's details

  • IdmUserDeletePlugin. Deletes a user

Authentication:

  • IdmAuthenticationPlugin. Performs a login for a given user, using an ID and password passed in as input fields

  • IdmTokenLoginPlugin. Logs in with an access token (if the target service supports such a thing)

Password management:

  • IdmChangePasswordPlugin. Update password given current and new password as input fields

  • IdmGetPasswordStrengthPlugin. Returns an assessment of the strength of a given password

User lifecycle:

  • IdmChangeStatusPlugin. Sets an account to locked or unlocked and clears login failure counters

  • IdmSetLifecycleStatePlugin. Changes the lifecycle state of a user (see below)

Password reset

  • IdmCheckSecurityQuestionsPlugin. Challenge the user to provide answers to security question(s) and verify the answers

  • IdmCRResetPwdPlugin. Use a security question challenge to reset a user's password

  • IdmSetCRPlugin. Store questions and responses for password reset challenges  

Auxiliary objects

In addition to the normal "user" record, the IDM service defines a class of object called auxiliary objects, which are "owned by" a user, but each of which defines a separate data object, with multiple attributes. A typical example would be postal addresses, which is a multi-line data object that a user could be associated with more than one of (home and work, for example). The list of permissible auxiliary object types is listed in the IDM configuration file.

  • IdmAddAuxiliaryObjectPlugin.

  • IdmGetAuxiliaryObjectsPlugin.

  • IdmModifyAuxiliaryObjectPlugin

  • IdmRemoveAuxiliaryObjectPlugin

4.20. IDM user lifecycle

The IDM service implements a simple user lifecycle state mechanism, illustrated in the following diagram:

Figure 16. IDM user lifecycle states

4.21. The IDM User object

IDM plugins do not always input and output individual user attributes, but instead use a compound object that represents the whole user. In plugin input and output fields this is usually called idmuser.

Although the IDM plugins themselves can handle this object, it is usually necessary to extract individual attributes from it to pass into other plugins or test in next-step rules. The idmuser object supports a "dotted name" syntax to allow this to happen. The basic syntax is as follows:

idmuser.attributes.{attributename}

There is, however, a further twist to this syntax; in order to keep the IDM plugins as independent as possible from a specific underlying implementation, they make use of the System for Cross-identity Management (SCIM) core schema for key elements, as documented in RFC7643. The following table summaries the attributes that are handled using their SCIM names and the dotted name used to access them. The LDAP inetorgperson attribute equivalent is also listed for comparison:

SCIM name

Access: One dotted name

LDAP equivalent

userName 

idmuser.attributes.username

uid

name.familyName

idmuser.attributes.name.familyname

sn

name.givenName

idmuser.attributes.name.givenname

givenname

emails

idmuser.attributes.emails

mail

phoneNumbers{"type": "work"}

idmuser.attributes.phonenumbers.work

phonenumber

phoneNumbers{"type": "mobile"}

idmuser.attributes.phonenumbers.mobile

mobile

The following screen shot shows an example of input mapping using idmuser-derived fields:

Figure 17. Mapping fields out of the idmuser object

4.22. The Metadata layer

The IDM subsystem does a good job of implementing a mechanism that allows the accounts on multiple services to be treated in a common way. However, in a typical workforce identity management environment, there will normally be a "master account", where the full details of the user are held, plus a number of "slave accounts" that are on different services that belong to the same person.

In the ideal world, the username could be used to link accounts, but in reality user naming conventions are not that well enforced. To facilitate the linking of accounts, Access: One metadata server maintains a database of relationships between master and slave user accounts, so that the whole picture of a user's accesses can be established. The diagram below illustrates this:

Figure 18. Metadata concept

Access: One workflows can interact with the metadata server, through the metadata plugin collection, and use it to maintain and query relationships between accounts. In fact, the metadata layer provides a repository of user interconnection information on a broader scale than just linking accounts together. It holds a range of other information about user lifecycle actions and relationships. The full list of data types is:

  • Master references
  • Slave references
  • Applications
  • Roles
  • Devices
  • Approvals
  • Notifications