Getting a Token

To get a token, send a request to the TokenManagerService web service on the Spectrum OnDemand server. You can access the TokenManagerService WSDL here:

http://server:port/security/TokenManagerService?wsdl

This web service uses Basic authentication so you must include a valid Spectrum OnDemand user name and password in the request.

The TokenManagerService web service can issue two types of tokens. The token types are:

  • Session token
  • Open token

Getting a Session Token

A session token is tied to a user session and can only be used by the computer that requested the token. Since it is tied to a session, the token will become invalid if the session is inactive for 30 minutes. A session token is the most secure type of token and is the recommended token type to use to authenticate to Spectrum OnDemand.

TokenManagerService has two SOAP operations for getting a session token.

Operation Description

getAccessExpiringToken

Use this operation if you want to specify an expiration time for the token. Here is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tok="http://token.security.common.server.platform.spectrum.precisely.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tok:getAccessExpiringToken>
         <tokenLifeInMinutes>60</tokenLifeInMinutes>
      </tok:getAccessExpiringToken>
   </soapenv:Body>
</soapenv:Envelope>

The element <tokenLifeInMinutes> specifies the number of minutes until the token expires, also known as the token time-to-live. In this example the token will expire in 60 minutes.

Here is a sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getAccessExpiringTokenResponse
       xmlns:ns2="http://token.security.common.server.platform.spectrum.precisely.com/">
         <return>
            <session>ebd7904b-07f6-15c9-82e4-71589131eb01</session>
            <token>eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..2pZB3qgpdC96xfOIPg9</token>
            <username>simon0897</username>
         </return>
      </ns2:getAccessExpiringTokenResponse>
   </soap:Body>
</soap:Envelope>

getAccessSessionToken

Use this operation if you want to get a token that will not expire. Note that the token will still become invalid if the session is inactive for 30 minutes, even if the token has not expired.

Here is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tok="http://token.security.common.server.platform.spectrum.precisely.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tok:getAccessSessionToken/>
   </soapenv:Body>
</soapenv:Envelope>

Here is a sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getAccessSessionTokenResponse
      xmlns:ns2="http://token.security.common.server.platform.spectrum.precisely.com/">
         <return>
            <session>65822c9b-362e-2e0e-a02a-a50a1a761323</session>
            <token>eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..CEE-C1VjKTha</token>
            <username>simon0897</username>
         </return>
      </ns2:getAccessSessionTokenResponse>
   </soap:Body>
</soap:Envelope>

The response contains these elements:

token
The security token.
session
The session ID of the session that the token is tied to. The token will only be accepted if this session ID is included in the request. If running with a JavaScript application, you must include a withCredentials: true web request header to ensure the session ID is passed back and forth on all requests.
username
The Spectrum OnDemand user name used to obtain the token. The user name is returned for informational purposes only and is not needed when you use the token.

Getting an Open Token

An open token is not tied to either a user or a specific computer. It is the least-secure token type.

Important: Avoid using open tokens that do not expire. If an open token is obtained by an unauthorized third party, the token could be used indefinitely, and from any computer, to gain access to your Spectrum OnDemand server.

TokenManagerService has one SOAP operation for getting an open token.

Operation Description

getAccessToken

Use this operation to get an open token. Here is a sample request:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:tok="http://token.security.common.server.platform.spectrum.precisely.com/">
   <soapenv:Header/>
   <soapenv:Body>
      <tok:getAccessToken/>
   </soapenv:Body>
</soapenv:Envelope>

Here is a sample response:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getAccessTokenResponse
      xmlns:ns2="http://token.security.common.server.platform.spectrum.precisely.com/">
         <return>
            <token>eyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiZGlyIn0..f4JwHB4qPs0l</token>
            <username>paul1234</username>
         </return>
      </ns2:getAccessTokenResponse>
   </soap:Body>
</soap:Envelope>

The response contains these elements:

token
The security token.
username
The Spectrum OnDemand user name used to obtain the token. The user name is returned for informational purposes only and is not needed when you use the token.