Authenticate API call with X-Reset-Flow header

Products

• Symantec Identity Security Platform - IDSP (formerly VIP Authentication Hub)

Issue/Introduction

When you call the /authenticate API with the X-Reset-Flow: true header to implement "Not User?" functionality, the response returns "nextaction": null. You expect the authentication policy to trigger immediately for the user, but instead, the flow appears to stop.

Environment

• Product: Symantec Identity Security Platform (formerly VIP Authentication Hub)
• Version: 4.x

Cause

This behavior is by design. When you include the X-Reset-Flow header, the system clears the existing subject from the current flow state. A null value for nextaction indicates that the identity is now unknown, and the application must prompt for a new username to continue the flow.

Resolution

You must implement a two-step process to reset the flow and start authentication for a new user. When the API returns nextaction: null, your UI should prompt the user to enter a username and then make a second /authenticate call including that subject.

Follow these steps to correctly implement the reset functionality:

1. Authorize call to generate x-flow-state

curl --location 'https://####/default/oauth2/v1/authorize?client_id=####&response_type=code&redirect_uri=####&code_challenge=####&code_challenge_method=S256&state=####&scope=openid%20offline_access'

2. Acquire Access Token

 

curl --location 'https://####/default/oauth2/v1/token' \
       --header 'Content-Type: application/x-www-form-urlencoded' \
       --header 'Authorization: Basic ####' \
       --data-urlencode 'grant_type=client_credentials' \
       --data-urlencode 'scope=urn:iam:myscopes'

3. Authenticate initial user (e.g., cmoran)

curl --location 'https://####/default/auth/v1/authenticate' \
       --header 'Content-Type: application/json' \--header 'x-flow-state: ####' \
       --data '{    
          "subject": "cmoran",
          "channel": "web",
          "ipAddress": "##.##.##.##",
          "action":"authenticate",
          "rememberMe" : true,
          "acrValues": [],
          "device": {
               "signature": {
                   "iaAuthData": "####"
               }
          }
        }'

4. Execute Authentication call with X-Reset-Flow=true (without Subject) Use this call when the user selects "Not User?".

curl --location 'https://####/default/auth/v1/authenticate' \
       --header 'Content-Type: application/json' \
       --header 'x-flow-state: ####' \
       --header 'X-Reset-Flow: true' \
       --header 'Authorization: Bearer ####' \
       --data '{
          "channel": "web",
          "ipAddress": "xx.xx.xx.xx",
          "action":"authenticate",
          "rememberMe" : true,
          "acrValues": [],
          "device": {
             "signature": {
               "iaAuthData": "####"
             }
          }
        }'

Response Payload:

{    
     "flowState": "####",
     "nextaction": null,
     "additional": {
        "privacyPolicyURL": ""
     }
}

5. Submit new Subject using the new flowState After receiving nextaction: null, prompt for the new username (e.g., nbruce) and call the API again using the flowState returned in Step 4.

curl --location 'https://####/default/auth/v1/authenticate' \
       --header 'Content-Type: application/json' \
       --header 'x-flow-state: ####' \
       --header 'Authorization: Bearer ####' \
       --data '{
         "subject": "nbruce",
         "channel": "web",
         "ipAddress": "##.##.##.##",
         "action":"authenticate",
         "rememberMe" : true,
         "acrValues": [],
         "device": {
            "signature": {
               "iaAuthData": "####"
             }
         }
      }'

The authentication flow now starts as per policy for the new user.