Advance the authentication to obtain a token

After your client receives the Challenges and Mechanisms and presents the user interface, the user enters credentials and indicates readiness to advance by clicking a login button.

Your client must then advance the authentication process, meaning it must retrieve the credentials entered by the user in response to the challenge and send those credentials to the server for authentication. The client application does this by invoking the /Security/AdvanceAuthentication endpoint.

The body of the request that your client sends must include the SessionId returned from /Security/StartAuthentication, which identifies the web communications sessions, and the MechanismId returned from /Security/StartAuthentication. The server uses the MechanismId to look up the challenge type and determine the result to expect when that user authenticates against the tenant identified by the TenantId. For some types of challenges, you must include additional fields in the client’s request.

The following example shows a client’s request to advance authentication for a password mechanism. The Action element specifies that Answer is to be used for authentication. That means the user must enter a password. The Answer element must contain the password that the user entered in the UI.

To execute this request in Postman:

The following example illustrates single factor authentication with Password as the authentication mechanism. See Supported authentication mechanisms for more information about other authentication mechanisms.

  1. Select the POST request type in the list and enter the endpoint URI.

    Advance Authentication API:
  2. Select the Headers tab and enter each header on a separate line.

    Headers of Advance Authentication:

    Content-Type: application/json
  3. Select the Body tab and enter the JSON:

    Payload for Advance Authentication:

    	"SessionId": "1e5214e4-0921-4e9e-8ada-3ef2970f7c1f",
    	"MechanismId": "4a23390d-dee9-4ead-aa33-2bacd93f81fa",
    	"Action": "Answer",
    	"Answer": "Pass1234"
  4. Click Send to execute the request.

    Upon receiving this request from your client, the server performs the authentication. If the authentication is successful, the server returns a response containing a success field indicating true and a Result element containing information about the user.

    	"success": true,
    		"AuthLevel": "Normal",
    		"DisplayName": "MRWright",
    		"Auth": "6936714B84F54...",
    		"UserId": "9eca6451-c13e-4e38-8dd1-30c4115dd966",
    		"EmailAddress": "",
    		"UserDirectory": "CDS",
    		"PodFqdn": "",
    		"User": "mr.wright@doccraft",
    		"CustomerID": "ABC1234",
    		"SystemID": "ABC1234",
    		"SourceDsType": "CDS",
    		"Summary": "LoginSuccess"
    	},  "Message": null, "MessageID": null, "Exception": null,  "ErrorID": null, "ErrorCode": null, "InnerExceptions": null

The most important element of a successful response to /Security/AdvanceAuthentication is the .ASPXAUTH cookie, which contains an authentication token. For more information about the ASPXAUTH token, see Using the Authentication Token.