Best Practice for Token Management

The Policy Agent requires you to use a token in order to allow you to access the Real-Time system. Access is provided through HTTP web request, and there are two methods for obtaining a token:

Using Single Sign-on Login

Using Manual Login

Once you receive the token using one of these methods, proceed to Invoking the RTServer WebService.

When the token expires, you will need to follow the explanation in Handling Token Expirations to obtain a new token.

Obtaining a Token Using Single Sign-on (SSO) Login

The SSO Login method delegates the process of generating the token to the operating system via the Kerberos protocol. The username and password that will be used in this login method are those of the currently logged-in Windows user.

To acquire the token:

1. Send an HTTP web request in the following way:
a. Set the request PreAuthenticate to TRUE.
b. Set AllowAutoRedirect to TRUE.
c. Set the request Accept to "*/*".
d. Set the request Method to POST.
e. Set the request ContentType to "text/xml;charset=UTF-8".
f. Set the request URL to OpenAM (for example: http://apollo-13.e-glue.com:1911/openam/UI/Login?module=WinSSO).
g. Set the request Credentials to CredentialCache.DefaultCredentials.
2. When you receive the HTTP web response, extract the token from the response by searching in the CookieContainer for a cookie with the name: "iPlanetDirectoryPro" (the value is the token itself).

When using the SSO method, if the HTTP web request is set correctly to the CredentialCache.DefaultCredentials in .NET, the Kerberos protocol will use the Windows credentials of the currently logged-in user for authentication purposes.

Obtaining a Token Using Manual Login

Manual login enables you to obtain the token using any approved username and password.

To acquire the token:

1. Send an HTTP web request in the following way:
a. Set the request PreAuthenticate to TRUE.
b. Set AllowAutoRedirect to TRUE.
c. Set the request Accept to "*/*".
d. Set the request Method to POST.
e. Set the request ContentType and MediaType to "application/json".
f. Set the request URL to OpenAM (for example: http://apollo-13.e-glue.com:1911/openam/json/authenticate).
g. Set the request Headers in the following way:
a. Add the Header key "X-OpenAM-Username" and the value USERNAME - without the domain (for example: “gl0”).
b. Add the Header key "X-OpenAM-Password" and the value PASSWORD.
h. In the request body, enter "{}".
2. When you receive the HTTP web response, extract the token from the response by searching in the response body for a key with name: "tokenId" (the value is the token itself).

Invoking the RTServer WebService

To add the token to the SOAP request:

1. Add the token you received (through SSO Login or Manual Login) to the SOAP request.
2. Add the following to the Header key: "Cookie" with the value "iPlanetDirectoryPro=" and the acquired token.

Handling Token Expirations

If you receive a web response containing a Header with the key "Location" , which redirects you to the OpenAM Login URL, this indicates that you need to acquire an updated token.

To obtain an updated token:

1. Log in using SSO or manual login.
2. Obtain the resulting token and add the new token to the SOAP request (see Invoking the RTServer WebService).