Authorization and Validation¶

The LaunchKey API uses a JSON Web Token (JWT) as the basis for providing authorization credentials as well as verify request and response validity. JWT was selected as it simply extends JSON Web Signature (JWS) with a known data structure called a claims set. The claims set is extensible with "private" claims. This would allow for providing validation items for the request or response with the existing "registered" claims. As there are claims in the JWT that are request and response specific, the LaunchKey API's use of JWT diverges from similar protocols which use it as a bearer token. That differentiation is made obvious by not using the Bearer authentication scheme but using a custom scheme name of IOV-JWT.

Here is an example request with an Authorization header for an organization using an abbreviated JWT:

POST /service/v3/auths HTTP/1.1 Content-Type: application/jwe Content-Length: 112 Authorization: IOV-JWT eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF

eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkEyNTZ.Ppd6dIAkGwcfIelfqOrj3rkw.71lYoW6jBJymhM-QLBQAWA.t-4rRH6GsoXt0.1DGC4k

Entity Identifiers¶

Whenever an entity identifier is required, the value will be comprised of two segments. The first segment is the entity type abbreviation. The second part is the ID of the entity. The two segments are separated bu a colon (:). The entity type abbreviations are:

org:	Organization
dir:	Directory
svc:	Service

Application Identifiers¶

Identifiers for LaunchKey applications will only have the application identifier. They are:

lka:	LaunchKey API

JWT Claims¶

Registered Claims¶

iss:	string The identifier for the entity that owns the Pubic Key specified in JWT.
sub:	string The identifier for the entity for whom the message was made. This claim is optional if the issuer and subject would be the same value.
aud:	string The identifier for the entity of the target audience of the message.
jti:	string Globally unique identifier for your JWT. The LaunchKey API will return this value as the `jti` of any response to every request that contains a JWT. As such, it can be utilized to prevent Man in the Middle attacks by verifying the `jti` for a response matched the `jti` sent in the request.
iat:	number Timestamp at which the JWT was issued/created. Must not be before the current timestamp.
nbf:	number Timestamp at which the JWT will become valid. Must not be before the current timestamp.
exp:	number Timestamp at which the token will expire. Must be after the current timestamp.

Private Claims¶

request:	object Claims which are used to verify the authenticity of a request
response:	object Claims which are used to verify the authenticity of a response
hash:	string Base64 encoded hash of the HTTP message body which is used to verify the integrity of the HTTP message body. This claim will be an attribute of a `request` or `response` claim object. It must be included when there is message body. It must not be included when there is not message body.
func:	string Hashing algorithm being used in regards to the `hash` value. This claim will be an attribute of a `request` or `response` claim object. It is required if there is a `hash` claim. See Keys and Algorithms for valid algorithm identifiers.
meth:	string Method of the HTTP request message in uppercase per the HTTP specification. This claim will be an attribute of a `request` claim. It is always required.
path:	string Absolute Path portion of the `Request-URI` of the HTTP request message. This claim will be an attribute of a `request` claim. It is always required.
query:	string Query portion of the `Request-URI` of the HTTP request message. This claim will be an attribute of a `request` claim. It only required if the `Request-URI` has .
status:	number Status code of the HTTP response message. This claim will be an attribute of a `response` claim. It is always required.
location:	string Value of the `Location` header of the HTTP response message. This claim will be an attribute of a `response` claim. It is only required if there is a `Location` header.
cache:	string Value of the `Cache-Control` header of the HTTP response message. This claim will be an attribute of a `response` claim. It is only required if there is a `Cache-Control` header.

JWT Examples¶

The following examples do not use actual JWT or JWE values as they would be too large to be readable. The HTTP Messages will have the correct number of segments but those segments will not be able to be decoded to JSON.

POST Request¶

The following are examples of a JWT header and payload based on a Service Auths request made to the LaunchKey API at 2:00:00 PM UTC on Jan 1, 2017 which is 1483279200 as a timestamp. The JWT ID of the request is 2501e859-d6f4-11e7-b28d-0469f8dc10a5. The JWT issuer is a Directory with the ID b77bfa0f-d6f2-11e7-b35b-0469f8dc10a5 and the JWT subject is one of Directory's Services with the ID cafe9f38-d6f3-11e7-a951-0469f8dc10a5. The JWT audience in the LaunchKey API. The JWT is signed using RSA with a SHA-512 with a Private Key belonging to the issuing Directory whose Public Key ID is 27:96:7b:d5:a4:04:ab:41:ee:d3:34:65:19:93:6e:09. The request body is hashed with a SHA-512 hash.

HTTP Message:

POST /service/v3/auths HTTP/1.1
Content-Type: application/jwe
Content-Length: 112
Authorization: IOV-JWT eyJhbGciOiJSU0EtT0FFUCIsIm.VuYyI6IkEyNTZHQ00ifQ.OKOawDo13gRp2ojaHV7LF

eyJhbGciOiAiUlNBLU9BRVAiLCAiZW5jIjogIkEyNTZ.Ppd6dIAkGwcfIelfqOrj3rkw.71lYoW6jBJymhM-QLBQAWA.t-4rRH6GsoXt0.1DGC4k

JWT Header:

{
    "typ": "JWT",
    "alg": "RS512",
    "kid": "27:96:7b:d5:a4:04:ab:41:ee:d3:34:65:19:93:6e:09"
}

JWT Payload:

{
    "iss": "dir:b77bfa0f-d6f2-11e7-b35b-0469f8dc10a5",
    "sub": "svc:cafe9f38-d6f3-11e7-a951-0469f8dc10a5",
    "aud": "lka",
    "jti": "2501e859-d6f4-11e7-b28d-0469f8dc10a5",
    "iat": 1483279200,
    "nbf": 1483279200,
    "exp": 1483279205,
    "request": {
        "path": "/service/v3/auths",
        "meth": "POST",
        "func": "S512",
        "hash": "1l8UlcxqVVjPVRuYU85Z6DyaU4+0RDTB+MPU2K98PMaKmqAaWIx2QxUNUl6fGrDlGK5PEh1SUtR4XT6JzCSRRQ=="
    }
}

Response with Content¶

The following are examples of a JWT header and payload based on a Service Auths response from the LaunchKey API at 2:00:00 PM UTC on Jan 1, 2017 which is 1483279200 as a timestamp. The JWT ID of the request is the same as the original request and is 2501e859-d6f4-11e7-b28d-0469f8dc10a5. The JWT issuer is the LaunchKey API. The JWT subject is the subject of the request and one of the audience Directory's Services with the ID cafe9f38-d6f3-11e7-a951-0469f8dc10a5. The JWT audience is the Directory that issued the request with the ID b77bfa0f-d6f2-11e7-b35b-0469f8dc10a5 . The JWT is signed using RSA with a SHA-512 with a Private Key belonging to the issuing Directory whose Public Key ID is 27:96:7b:d5:a4:04:ab:41:ee:d3:34:65:19:93:6e:09. The request body is hashed with a SHA-512 hash.