S4. Security Token and Security Considerations


The XDOC UI Service provides a mechanism for the Calling Application to pass an additional Security Token that can be used to ensure that the Request is Trusted. The Security Token is similar in concept to the User Token from the previous section. The Security Token is passed via parameter XST.

The Security Token is an encrypted string that contains multiple embedded data fields in JSON, XML, or form-url-encoded format. The Data Fields consist of Application level credentials that can be used to ensure the Calling Application is Trusted. The values of the Data Fields embedded in the Security Token are configurable in XDOC at a Project Level, and must be kept in sync with the Integrated Application appropriately.

Note: The Security Token (XST) and the User Token (XUT) can be combined together. The XDOC User Interface Service will check for the existence of both tokens. If only 1 token is present, then both the User and Security attributes will be read from that token.

4.1. Security Token Data Fields

Data Field Data Type Required Notes
Context String Yes Must match the value of the XSC parameter, and the Security Context defined in the Axacore Server..
AppId String Yes Name / identifier of the Invoking Application. Can be any value, but must be set. Used for debugging / tracing the request back to the application that made the request.
AppKey String Must match a value in the Token App Key(s) defined in the Axacore Server. If no App Keys are defined, this check is ignored.
GenDT DateTime (UTC) Yes Date and Time the Security Token was generated in standard web service UTC date format: yyyy-MM-ddTHH24:mi:ssZ
Client String IP address or other identification of the computer initiating the request. Used for debugging / tracing the request back to the specific computer / web server where the request originated.

4.2. Token JSON String Example

{
    "Context": "axui", 
    "AppId": "MyApp",
    "AppKey": "MyPassKey",
    "GenDT": "2010-03-01T10:32:56Z",
    "Client": "127.0.0.1" 
}

4.3. Token XML String Example

<SecurityToken>
    <Context>axui</Context>
    <AppId>MyApp</AppId>
    <AppKey>MyPassKey</AppKey>
    <GenDT>2010-03-01T10:32:56Z</GenDT>
    <Client>127.0.0.1</Client>
</SecurityToken>

4.4. Token Form-Url Encoded String Example

Context=axui&AppId=MyApp&AppKey=MyPassKey&GenDT=2010-03-01T10:32:56Z&Client=127.0.0.1&

4.5. Token Encryption The Token string must be encrypted using industry standard AES encryption (Rijndael algorithm), and then base64 encoded. The value sent to the Service via the XST parameter is the final base64 encoded value. The AES encryption generation settings are configurable in the Axacore Server and must be kept in sync with the same values used by the Invoking Application. The set of AES encryption settings effectively define a Private Key.

4.6. Validating the Security Token XDOC allows configuration of the following options at the System Level and Project Level in order to check that the Security Token is valid.

Http Request Validation Settings

Configuration Option Sample Notes
Remote IP ACL List 74.125.224.147, List of allowable IP address of the Remote Application making the Request. This is validated against the actual Http protocol information. The IP address of the Remote Application will normally be the public facing IP address of the firewall.

Security Token Validation Settings

Configuration Option Sample Notes
Require Security Token True Indicates if a Security Token (XST) is required for Service invocation. This is generally always True to ensure security, except when testing or troubleshooting.
Token App Keys MyPassKey List of allowable values for the AppKey token field. Usually, there is only 1 value. This is essentially a “password(s)”, and can be changed easily if compromised (versus changing encryption settings).
Token Expire Time (sec) 900 Token expiration ensures that a generated Token is only valid for a specified length of time. The default is 15 minutes. This is rarely ever changed