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
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 } }