API Guide

S4. User Token Credential Passing

The XDOC UI Service provides a mechanism for the Calling Application to pass Auto-Logon user credentials. When used, this allows XDOC User Interfaces to be launched in a “Trusted” fashion … thereby bypassing the normal XDOC Login page, and providing a tighter integration between the applications. The Auto-Logon credentials are referred to as the User Token, and are passed via parameter XUT.

The User Token is an encrypted string that contains multiple embedded data fields in XML, JSON, or form-url-encoded format. The Data Fields can consist of various User attributes and permission settings, some of which are known and required by XDOC to operate in a user context.

Note: The Security Token (XST) referenced in the next section, 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, both the User and Security attributes will be read from that token.

4.1. User Token Data Fields

Data Field DataType Required Notes
UserName String Yes User logon name.
Display String User display name.
Email String Yes User’s email address. Required
Profile String Yes* The User’s primary role in the Integrated Application. * Can actually be empty, but generally should be set.
ExtId String The id of the user object in the Integrated Application.
ExtRef Extra ref of the user object defined by the Integrated Application
ExtData String Extra data of the user object defined by the Integrated Application.
ExtFlags Integer Extra flags of the user object defined by the Integration Application.

Additional Data Field Notes:

  • If Profile is not set, the profile will be set to the last Security Profile assigned to the User in the XDOC system. If no profile is set for the User, the Default External Profile setting for the Project will be used.

4.2 Token JSON String Example

{
    "UserName":"admin",
    "Display":"System Admin",
    "Email":"noreply@gmail.com",
    "Profile":"SysAdmin",
    "ExtId":"234892", 
    "ExtData":""
}

4.3. Token XML String Example

<UserToken>
    <UserName>admin</UserName>
    <Display>System Admin</Display>
    <Email>noreply@gmail.com</Email>
    <Profile>SysAdmin</Profile>
    <ExtId>234892</ExtId>
    <ExtData></ExtData>
</UserToken>

4.4. Token Form-Url Encoded String Example

UserName=admin&Display=System%20Admin&Email=noreply%40gmail.com&Profile=SysAdmin&ExtId=234892&ExtData=

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 XUT 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.

Setting Allowable Values Sample Value Notes
Encryption Key Axac0r3! Keys less than 32 characters will be right padded with the null character (0x00).
Key Size 128, 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 }