API Guide

S5. Security Token and Security Considerations

XDOC can pass a Security Token to the External System that can be used to ensure that the Request is Trusted. The Security Token can use the same structure and encryption as the Security Token in the XDOC Container Provider Service and other XDOC Services, or it can be defined by the External System as either a static string or some other dynamically generated algorithm.

The use of a Security Token is optional for Service invocations from trusted applications. It is merely provided as an additional security measure. Implementing security can always be handled using standard Firewall and Webs Server based mechanism that are outside of either Application, such as:

  • Firewall restrictions based on the Invoking Application’s IP Address.
  • Certificates required in the Invoking Application’s HTTP Request.

The SecurityToken is an encrypted string that contains multiple embedded data fields in either XML or JSON 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.

5.1. Security Token Data Fields

Data Field Data Type Required Notes
AppId String Yes Id of the calling application. Configurable.
AppKey String Yes Pass key of the calling application. Configurable.
GenDT DateTime (UTC) Yes Date and Time the SecurityToken was generated in UTC format.
Client String IP address or other identification of the client computer.

5.2. Token JSON String Example

{
    "AppId": "Integrated App",
    "AppKey": "some-password",
    "GenDT": "20100301T103256",
    "Client": "60.1.1.49", 
}

5.3. Token XML String Example

<token>
    <AppId>XDOC</AppId>
    <AppKey>some-password</AppKey>
    <GenDT>20100301T103256</GenDT>
    <Client>60.1.1.49</Client>
</token>

5.4. 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 this final base64 encoded value. The AES encryption generation settings are configurable in XDOC and must be set in sync with the same values used by the Integrated Application.

Setting Allowable Values Sample Value Notes
Pass Phrase xdoclos
Initialization Vector @1B2c3D4e5F6g7H8 Must be 16 characters
Cipher Mode ECB ECB For .NET, see the CipherMode Enum.
Padding Mode ANSIX923 ANSIX923 For .NET, see the PaddingMode Enum.
  • The Values for Cipher Mode and Padding Mode show above are proven to work in conjunction with Java Encryption libraries.
  • Padding Mode ANSIX923 is also compatible with ISO10126. Padding Mode ISO10126 is an older implementation and should not be used.

5.5. Additional Security Checks

  • The XDOC configuration allows the specification of an Expiration Time in minutes. If specified, the Integrated Application could only allow the token to be valid for a specified amount of time, thus ensuring it cannot be reused.
  • The Integrated Application Service configuration can use basic Firewall type restrictions to restrict invocation of the Service to specific IP addresses where the XDOC servers reside.
  • The Integrated Application should restrict invocation of the Service to the HTTPS protocol only.