Using OpenID Connect with ActiveMatrix BPM

If your ActiveMatrix BPM application is configured to use OpenID Connect, users of your application can log in using a user name and password issued by an Identity Provider (IdP) that supports OpenID Connect. Currently, only Microsoft Active Directory Federation Services (ADFS) is supported as an IdP for use with OpenID Connect.

The following describes the basic flow when someone attempts to log in to an ActiveMatrix BPM application, which is configured to use OpenID Connect, using their IdP credentials (this assumes the user is not already logged in to ActiveMatrix BPM):

  1. A user starts an ActiveMatrix BPM application that is using OpenID Connect authentication.
  2. The application tries to access the ActiveMatrix BPM server, but the ActiveMatrix Platform intercepts the login request and returns a 403 error to the application, stating that the user is not authenticated, and that authentication is being provided by OpenID Connect. The ActiveMatrix Platform also includes the URL to the IdP, as well as other information about the OpenID Connect configuration specified in the OpenID Connect shared resource.
  3. The application redirects the login request to the IdP, using the information returned by the ActiveMatrix Platform.
  4. The IdP displays their login screen, requesting the user's IdP-issued credentials.
  5. The user enters IdP-issued credentials.
  6. After validating the user, the IdP returns an ID Token — in the form of a JSON Web Token (JWT) — to indicate a successful authentication.
    Note: Using the OpenID Access Token is not currently supported in ActiveMatrix BPM. The OpenID ID Token is used to identify the user.

    The response from the IdP also includes the claims specified in the Auth Scope field of the OpenID Connect shared resource. For more information, see Configuring OpenID Connect in ActiveMatrix BPM.

    The IdP sends the ID Token and claims information to the "Redirect URI" that is specified in the OpenID Connect shared resource. For every ActiveMatrix BPM application, the Redirect URI must be: 

    http://host:port/openspace/sso/bpmssoapp.html

    where host is the DNS name or IP address of the server that hosts the ActiveMatrix BPM runtime, and port is the port used by the application.

    Although this Redirect URI is used for all ActiveMatrix BPM applications, the response from the IdP is routed to the appropriate ActiveMatrix BPM application based on an interceptor script (bpm-sso-interceptor.min.js) that is included in the application that submitted the request to the IdP (for more information about the interceptor script, see Using OpenID Connect with Custom Applications).

  7. Upon receiving the ID Token from the IdP, the application redirects the request back to the ActiveMatrix BPM server to confirm that the user is a valid ActiveMatrix BPM user before logging the user into the application. The user's email address returned in the upn claim is used to verify that the user is a valid ActiveMatrix BPM user -- for information about the upn claim, see the Auth Scope field in Using ActiveMatrix Administrator to create an OpenID Connect Shared Resource.

A cookie is also created when the user is validated by the ActiveMatrix BPM server. The cookie includes the ID Token, which is used to establish the session that is used by all other subsequent calls to the ActiveMatrix BPM server.

When an IdP-authenticated user logs out of the ActiveMatrix BPM application:

  • The browser sends the value in the LogOutPath property (which is "/bpm/logout") to the ActiveMatrix BPM server.
  • Upon receiving the log out path, the server sends a request to the IdP, using the URL specified in the SignOutURL property, to log the user out of the IdP.
  • The cookie that was created upon login is removed.