About

Virtru uses a modified version of the Java Web Token (JWT), referred to as a Virtru Java Web Token (VJWT), authentication scheme to authenticate the request. The tokens will be signed using organization wide API keys generated by Virtru upon request.

Jump to:

• Details
• Example
• Usage 

Details

The JWT fields that must be signed are as follows:

• iat - The current timestamp (seconds)
• iss - the issuer (in this case which client made the request)
• sub - this is the tokenId which is the identifier to the secret used to store the HMAC secret on the server
• rqps - is a comma separated list of query params
• rhds - Optional field that contains a comma separated list of headers to sign
• rsha - Base64UrlEncode of SHA256 hash of the Method + host + path + query params + headers.
  • This field should not have Base64 padding
  • The query params are added to the hash in the order defined in the rqps field by combining the key and value of the query params in the form query_param_key=query_param_value. So ?a=1 becomes a=1 for signing.
  • The headers are added to the hash in the order defined in the rhds field by combining the lowercase header name and value in the form header_name=header_value. So Content-Type: application/json becomescontent-type=application/json
• jti - nonce used for the request
• exp - expiration of the token in seconds 

Example

Original Request

{
  method: 'POST',
  pathname: '/some/path',
  host: 'virtru.com',
  headers: {
    'content-type': 'application/json'
  },
  query: {
    a: 1
  }
}

Encoded VJWT

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzb21lLWFwaS10b2tlbiIsImlhdCI6MTUyNTk2NTI0NywianRpIjoicHdTYVNpYkdRNzZhWUZiSWJka1dMUS8wIiwicnNoYSI6InBoYU5QQ0hxNHBTUWY4aEFhTUlIOTB6dWxlay1ZSW9iN0Z5RWtRa3ZqcE0iLCJycXBzIjoiYSIsImV4cCI6MTUyNTk2NTU0N30.JsnDtiYyVIt76ZmDkeFnWYX3FSUPSFL9kH60MzPzuTk

Decoded VJWT Content

// Header
{
  "alg": "HS256",
  "typ": "JWT"
}

// Payload
{
  "sub": "some-api-token",
  "iat": 1525965247,
  "jti": "pwSaSibGQ76aYFbIbdkWLQ/0",
  "rsha": "phaNPCHq4pSQf8hAaMIH90zulek-YIob7FyEkQkvjpM",
  "rqps": "a",
  "exp": 1525965547
}

Usage

The Audit API uses the authorization header to authenticate usage against the API to retrieve the audit data.

• This method requires the following structure for the header
  • Authorization: VJWT[VJWT_VERSION] [JWT]
• This method requires the following query parameters to be appended to the URL
  • auth-xport=header - Tells the server that it should authorize the request using the authorization header

Example request with VJWT using the Authorization Header

{
  method: 'POST',
  pathname: '/some/path',
  host: 'virtru.com',
  headers: {
    'content-type': 'application/json',
    authorization: 'VJWTv1.0.0 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzb21lLWFwaS10b2tlbiIsImlhdCI6MTUyNTk2NTI0NywianRpIjoicHdTYVNpYkdRNzZhWUZiSWJka1dMUS8wIiwicnNoYSI6InBoYU5QQ0hxNHBTUWY4aEFhTUlIOTB6dWxlay1ZSW9iN0Z5RWtRa3ZqcE0iLCJycXBzIjoiYSIsImV4cCI6MTUyNTk2NTU0N30.JsnDtiYyVIt76ZmDkeFnWYX3FSUPSFL9kH60MzPzuTk',
  },
  query: {
    ‘auth-xport’: ‘header’
    a: 1
  }
}