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:

The client calls the API to log in the user. (For coding details, see Starts a user authentication session.)
The server authenticates the user and does the following:
a. Generates an access token that uniquely identifies the user's session.
b. Stores the access token and keeps it until the user logs out.
c. 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.)
d. Attaches and returns a CCSID cookie in the HTTP header of the API authentication. Centrify uses this when evaluating policy rules, to determine if the client device that is executing the endpoints has been used before. For more information see here.
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.

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.
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: '[email protected]',
     Version: '1.0',
     TenantId: 'ABC1234'
     }"
     --dump-header headers.txt 
'https://pod1.centrify.com/Security/StartAuthentication'

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:

{
    "ClientHints": 
        {
        "PersistDefault": False,
        "AllowPersist": True,
        "AllowForgotPassword": False
        },
    "Version": "V1",
    "SessionId": "81c60352-ee50-422c-b5c9-e73b55b8f314",
    "Challenges": [
        {
        "Mechanisms": [{
            "AnswerType": "Text",
            "Name": "UP",
            "MechanismId": "3f2478af-24ef-4ca6-981a-b54c3aef118d"
            }]},
        {
        "Mechanisms": ""
        }]
        "Summary": "NewPackage",
        "TenantId": "ABC1234"
}

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 
 
https://pod1.centrify.com/security/AdvanceAuthentication

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

{
    "SystemID": "AB123",
    "DisplayName": "QA1",
    "EmailAddress": "[email protected]",
    "PasswordExpDate": "Fri, 31 Dec 9999 15:59:59 GMT-08:00",
    "CustomerID": "AB123",
    "AuthLevel": "Normal",
    "PodFqdn": "pod1.centrify.com",
    "Auth": "C85562A8A3B425095981BFFD7D92F...",
    "User": "[email protected]",
    "UserDirectory": "CDS",
    "Summary": "LoginSuccess",
    "UserId": "c2c7bcc6-9560-44e0-8dff-5be221cd37ee",
    "SourceDsType": "CDS"
}

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 
https://pod1.centrify.com/UserMgmt/GetUserInfo

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

Saving and Passing Authentication Cookies

See Also