Use request parameters as input to authentication mechanisms

Consider using client supplied parameters as input to authentication mechanisms. This configuration helps to reduce the dependency on sessions and cookies to maintain state attributes that are frequently the source of mechanism input parameters such as the user name to be authenticated.

Most authentication mechanisms support a set of input parameters as part of their execution. The source of values for these parameters can be the internal Authentication Service Framework context, the inbound HTTP request, or the HTTP session. Most of the default policies that are supplied within the Authentication Services Framework use the internal context as the source of mechanism parameters. Except for the Username Password mechanism, the username to be "authenticated" is assumed to be available to mechanisms within an already authenticated context. This situation is suited to step up with second factor type use cases. It is possible for a requesting client to invoke authentication mechanisms and policies (for example, OTP) without a pre-established authenticated session. It is achieved by using an alternative input source for parameter values supported by most mechanisms.

The following example illustrates how the requesting client can specify the "username" to validate their TOTP credential. A custom authentication policy is created which references the TOTP mechanism as its only step. The mechanism is configured to obtain its user name input parameter from a client request JSON data parameter.

1. Create a custom authentication policy in the local management interface by going to Access Control > Authentication > New Authentication Policy (the plus icon). Set the policy Identifier value as "urn:ibm:security:authentication:asf:mytotp".
2. Add the TOTP One Time Password mechanism as the only step on the policy.
3. Click Parameters next to the mechanism to show the Modify Parameters dialog.
4. Select the Pass checkbox on the username row.
5. Select Request as the source.
6. Enter myuid as the request name and urn:ibm:security:asf:request:parameters as its namespace.
7. Click OK.
8. Click Save.

The policy is now available to service and respond to client requests. REST clients can specify "myuid" within their request JSON data to indicate which user is being authenticated for TOTP. Assume the users have previously initialized their TOTP authenticator applications with their shared secret. A REST client can send requests similar to that shown as follows to initiate the new custom policy and TOTP mechanism. For more information about the Authentication Services REST API, see REST API documentation.

An example request is shown as follows:

curl -k -v -c cookies.txt -b cookies.txt -X POST -H "Content-Type:application/json" 
-H "Accept: application/json" --data "{'myuid':'testuser1'}" "https://<isva address>
/mgaapi/sps/apiauthsvc?PolicyId=urn:ibm:security:authentication:asf:mytotp"

An example response is shown as follows:

{
"mechanism": "urn:ibm:security:authentication:asf:mechanism:totp",
"message": "",
"state": "9b5286e25a9340f989e3b77b24775602",
"location": "/mga/sps/apiauthsvc?StateId=9b5286e25a9340f989e3b77b24775602",
"execptionMsg": "NA"
}

Next, the REST client can verify the user's OTP by sending a request as shown in the following example, using the StateId parameter returned from the previous response:

curl ­k ­v ­c cookies.txt ­b cookies.txt ­X PUT ­H "Content-Type: application/json" ­H "Accept: 
application/json" ­­data "{'otp': '987352'}"
"https://<isva address>/mgaapi/sps/apiauthsvc?StateId=9b5286e2­5a93­40f9­89e3­b77b24775602"

A successfully verified TOTP is indicated to the client with an HTTP 204 response code.

Parent topic: Authentication Service Framework for REST API clients