IBM Security Verify

 View Only

ISAM: Path based authentication service kickoff

By Leo Farrell posted Sun May 26, 2019 08:27 PM


The ISAM authentication service performs initial and step-up authentication by either browser or API.

A screenshot of the authentication service UI

When using the authentication service it is invoked with one of three parameters to identify the request context, both when starting a new authentication event, or continuing one:

  • TransactionId - Which is used when a context based access policy triggers an authentication service transaction.
  • PolicyId - Used to initiate a new authentication service transaction with a selected policy
  • StateId - Used to continue an already initiated authentication service transaction.

The focus of this blog is initiation of authentication service policy via a PolicyId and some changes which were made in

A PolicyId is a URN, with a prefix unique to the authentication service. An example of a policy ID is:

A screenshot of the ISAM LMI showing a policyId
In this screenshot we can see the 'identifier', the policyId is:

This initiates the out of the box username & password authentication mechanism. All policy IDs have the prefix urn:ibm:security:authenitcation:asf, with the final portion being unique to the policy.

An example of initiating a authentication service flow using the above PolicyId is:

Prior to 9060 the only way which a policy could be presented to the authentication service was via the post or query string parameter PolicyId. This is of note as the PolicyId is not part of the web object, but is instead just a parameter to the authentication service. This makes attaching an ACL or POP to a given policy not possible without using DynURL

In 9060 a new capability to the authentication service was added. A third way to present a PolicyId was added. This takes the form of a new path and a path parameter based off the configured identifier.

This lets the same policy password policy'urn:ibm:security:authentication:asf:password be invoked with the following request instead:

This is a shorter, and more discrete URL. Further more the policy identifier is provided as a path parameter, meaning an ACL or POP can easily be attached to the endpoint in the traditional manner. This offers finer granularity to which parts of the authentication service are available depending on whether or not the user is authenticated, or what groups they are a member of. 

This capability is enabled via an advanced configuration option, sps.authService.policyKickoffMethod. This configuration can be set to one of 3 values which allows for different modes of operation:

  • parameter - The prior to 9060 function, does not enable this enhancement. This is the default value.
  • path - Enables the new kickoff method and does not allow a PolicyId to be presented via parameter
  • both - Allows for operation of both methods, which is useful when migrating. 

When using the authentication service with this new feature, there are a few things to be aware of: 

  •  The path parameter is under a new object "policy"
  •  The PolicyId is shortened, its no longer a URN and is instead just the unique portion of the policy identifier is used.
  •  The web object being accessed is at a different location, so relative URLs in HTML templates may need to be adjusted. This can impact images, CSS and JavaScript on the application. 
When working through a given policy, the URL will remain the policy URI, but will be accessed with a StateId for the current phase of the flow. An example of this is:

This means that in the event of a session timing out, or an invalid StateId error occurring, the URL still contains the initial policy invoked, allowing JavaScript in the browser to re-invoke the policy if desired.

Most of the use cases for this feature are highly practical, consider a policy which you only want to enable users of a certain group to invoke, by attaching a group-based ACL to the policy endpoint access to that policy is now restricted. 

Consider this feature when deploying the authentication service and take a stricter security posture by only allowing users to invoke the policies they need access to.