Overview

A successful response to /SecurityAdvanceAuthentication contains an Auth element specifying an authentication token for use when invoking subsequent endpoints. The server generates this unique code, and your client application must store it. The token is used to grant the client authenticated access to resources (Centrify endpoints) on behalf of the user. That is, the token provides the server with proof that each subsequent API call is being made on behalf of a user who has already been authenticated.

Note: The "Auth" attribute in the response of /Security/AdvanceAuthentication is a one time use token for service access; can be used for a single API call. The .APXAUTH cookie is a duration based token allowing multiple API calls.

Client Versus Server Token Handling

Client-Based Apps

In web applications, including Postman, the browser might retain this code as a .ASPXAUTH cookie and automatically pass it along to the server. In this case you likely won't have to manually store or handle the cookie.

Note: some browsers have a setting that prevents them from accepting third-party settings. When enabled, Centrify is seen as third party, so the browser will likely block the cookie. To get around this, Centrify must be set as a trusted site.

Server-Based Apps

Since a cookie can't be stored in browser-side code for server-based apps, a server must store the token value unaltered, and then pass it as a bearer token in subsequent API requests. In this case you will create a new header in the web request for the next API call, called Authorization, and set its value to ‘Bearer ’. For example:

Authorization: Bearer 6936714B84F54...

In order to enable this functionality you must first add your website's DNS in the Admin Portal:

1. Navigate to Infrastructure > Settings > Authentication > Security Settings.
2. Click Add.
3. Enter your website's DNS and click Add.
4. Click Save.

These elements are shown in the following screenshot:

Token Lifespan

Overview

A token has a limited lifespan that is set on the admin portal as described below. Once a token expires it cannot be refreshed, so a new token must be acquired by performing the authentication process again. A token's lifespan can also be ended by Logging Out.

Specifying the Duration of the Token

An admin specifies how long an ASPXAUTH token is valid for once issued, by navigating to Core Services > Policies > Login Policies > Centrify Portal and setting the Hours until Identity cookie expires field:

Example Usage

Consider the following example, where the client has received the authentication token. The client then invokes the /UPRest/GetUPData endpoint to obtain a list of applications that are deployed for the authenticated user.

POST https://ABC1234.mycompany.centrify.com/UPRest/GetUPData 

X-CENTRIFY-NATIVE-CLIENT:true
Content-Type: application/json
Authorization: Bearer 6936714B84F54...

{
        "Username": "mr.wright@doccraft"
}

In this example, the client includes the ASPXAUTH cookie in header called Authorization.

With this information, the client can invoke this request on behalf of the user.

To execute this request in Postman:

1. Click Cookies in the response section to verify that the response from /Security/AdvanceAuthentication contains an .ASPXAUTH cookie for your tenant. You must have this cookie before you can execute subsequent calls in Postman on behalf of the user you just authenticated:

2. Select the POST request type in the list and enter the endpoint URL:

3. Select the Headers tab and enter each header on a separate line.

4. Select the Body tab and enter the JSON.
5. Click Send to execute the request.

Try the API in Postman:
.
Click here for help with using our sample Postman collection.