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

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
9.0.6.0.
A
PolicyId
is a
URN, with a prefix unique to the authentication service. An example of a policy ID is:

In this screenshot we can see the 'identifier', the policyId is:
urn:ibm:security:authentication:asf:password
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:
HTTP GET https://www.myidp.ibm.com/isam/sps/authsvc?PolicyId=urn:ibm:security:authentication:asf:password
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:
HTTP GET https://www.myidp.ibm.com/isam/sps/authsvc/policy/password
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:
https://www.myidp.ibm.com/mga/sps/authsvc/policy/password?StateId=ZCChWWN7NvtxM....
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.