Generating Authentication Cookies

Most calls to the API require authentication — for these calls, you (the client) must establish that the user on whose behalf you are making the call has been authenticated by Identity Platform for your tenant. Identity Platform uses cookies for authentication, as follows:

  1. The client calls the API to log in the user (see Saving and passing authentication cookies for coding details).
  2. The server authenticates the user and does the following:
    • Generates an access token that uniquely identifies the user's session.
    • Stores the access token and keeps it until the user logs out.
    • Attaches the access token to an authentication  cookie (.ASPXAUTH ) that it returns to the client in the HTTP header of the API authentication call.
      Note that the server generates additional cookies that it returns to the client as well.
  3. The client must do the following:
    • Save the cookies that are returned by the server.
    • Pass them in the HTTP header of subsequent calls to the API.
  4. The server validates the user session for each call to the API by inspecting the token passed by the client in the HTTP header cookie, and verifying that it is identical to the token that the server generated and saved in step 2.
  5. When the user logs out, the server removes the cookies for that user.

Saving and passing authentication cookies

As noted, the server generates cookies as part of the authentication process. Identity Platform implements a multi-part authentication process with two API calls:

  • /Security/StartAuthentication
    The client calls /Security/StartAuthentication and passes parameters to uniquely identify the user to authenticate. In most cases, the server returns a package that includes one or more security challenges for the user to answer.  
  • /Security/AdvanceAuthentication
    The client calls /Security/AdvanceAuthentication one or more times to respond to the security challenges. When the server successfully authenticates the user, it returns the authentication cookies to the client in the HTTP header of the /Security/AdvanceAuthentication call. The client must save the cookies so they are available to pass to subsequent calls for the authenticated user.

Although the typical authentication process requires a call to /Security/StartAuthentication followed by one to /Security/AdvanceAuthentication, a call to /Security/StartAuthentication may result in successful authentication. Therefore, the client should always save the cookies returned by /Security/StartAuthentication as well as those returned by /Security/AdvanceAuthentication.

One way to save the cookies is to dump them to a file when calling /Security/StartAuthentication and /Security/AdvanceAuthentication. You can then pass the file containing the cookies for each subsequent call to the API. The following example shows how to do this with cURL.

To start the authentication process, call  /Security/StartAuthentication and specify the user to authenticate and the version of the function that you are calling. Save the cookies to a file by specifying the --dump-header parameter. Note that TenantId is optional if the host name contains a tenant-specific URL or the user name has a known alias that enables the server to identify the tenant.

.\curl -H "X-CENTRIFY-NATIVE-CLIENT:1" -H "Content-type: application/json"
-d "{
     User: 'qa1@qa.test',
     Version: '1.0',
     TenantId: 'ABC1234'
     --dump-header headers.txt 

The call returns an MFA package that includes one or more security challenges. The actual challenges that the server returns depend on a number of factors, including the security settings for the user, whether the user is logging in from a known device or an unknown device, whether the IP address is within the corporate network, etc. The purpose of this example is to show how to save the authentication cookies, so it shows a simple case with one challenge mechanism:

Single challenge mechanism

To respond to this authentication challenge, call /Security/AdvanceAuthentication. In the call, save the authentication cookies by dumping them to a file; for example, in cURL, use the --dump-header parameter:

.\curl -H "Content-type: application/json"
       -d "{
         "TenantId": "AB123",
         "SessionId": "81c60352-ee50-422c-b5c9-e73b55b8f314",
         "MechanismId": "3f2478af-24ef-4ca6-981a-b54c3aef118d",
         "Action": "Answer",
         "Answer": "Pass1234"
       --dump-header headers.txt 

 For successful authentication, the server returns a response similar to the following:

LoginSuccess response

The Summary field value: "LoginSuccess" indicates that the user has been authenticated, which means that the server returned an authentication cookie. The --dump-header parameter that you passed with the call saved the cookies to the headers.txt file. You can now pass these cookies to subsequent calls on behalf of this user by using the -b parameter to pass the headers.txt file to the call. For example, after authenticating a user, you could retrieve information for the user with these calls:

.\curl -H "X-CENTRIFY-NATIVE-CLIENT:1" -H "Content-type: application/json"
       -d "{UUID:'c2c7bcc6-9560-44e0-8dff-5be221cd37ee'}"
        -b headers.txt 


.\curl -H "X-CENTRIFY-NATIVE-CLIENT:1" -H "Content-type: application/json"
       -d "{UUID:'c2c7bcc6-9560-44e0-8dff-5be221cd37ee'}"
       -b headers.txt 
See Also