API Guide

HTTP Server Services API S4. Security Token Authentication

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.