API Guide

S4. Security Token Authentication

The Service Framework provide a mechanism for the Invoking Application to pass an encrypted Security Token with the Service Method request which will be used to “Authenticate” the Invoking Application, and “Validate” that the request is allowed.

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 authorization fields, as well as network and computer information related fields that are used in conjunction to perform the authentication and validation.

4.1. Security Token Data Fields

Data Field Type Required Description
Context String Yes Must match the Security Context (XSC parameter).
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 one of the values in the Token App Key(s) list defined for in the Axacore Server. If no App Keys are defined, then this check is ignored.
GenDT DateTime 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.

Note: A Security Token is valid by default for 15 minutes from the timestamp identified by the GenDT token field. So, when processing several Method calls repeatedly in a block of code, it can be re-used for each call.

4.2. Token JSON String Example

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

4.3. Token XML String Example

    <SecurityToken>
    <Context>axws</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=axws&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 SecurityToken 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 for the Security Context.

Setting Allowable Values Sample Value Notes
Encryption Key Up to 32 characters Axac0r3! Keys less than 32 characters will be right padded with the null character (0x00).
Key Size 128, 192, 256 256 256 bits (32 bytes) is the preferred industry standard.
Cipher Mode CBC, ECB CBC CBC is the preferred industry standard.
Padding Mode Zeros,PKCS7,None PKCS7 Provides compatibility across most development languages.
Initialization Vector @1B2c3D4e5F6g7H8 Must be exactly 16 characters.
  • The Sample Values shown above for Key Size, Cipher Mode, and Padding Mode are known to work across .NET, Java, PHP, OpenSSL, and most other toolkits and libraries.
  • If the Initialization Vector is blank, the standard AES/CBC initialization vector bytes will be used:
    • { 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x0E, 0x0F }

4.6. Token and Request Validation The following settings are defined on the Axacore Server. They control the various checks and logic performed to validate the Security Token and Http Request.

Http Request Validation Settings

Setting Sample Value Notes
Remote IP ACL List 74.125.224.147,
10.6.1.
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

Setting Sample Value 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 Expiration time in Seconds for the Token relative to the GenDT token field. 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.