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.

HTTP Message:

HTTP/1.1 201 Created
Date: Sun, 01 Jan 2017 14:00:00 GMT
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Server: api.launchkey.com
Status: 200 OK
Cache-Control: no-cache
X-IOV-JWT

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

JWT Header:

{
    "typ": "JWT",
    "alg": "RS512",
    "kid": "d2:8e:16:91:39:5b:9d:24:73:0e:36:0a:9a:ef:7e:de"
}

JWT Payload:

{
    "iss": "lka",
    "sub": "svc:cafe9f38-d6f3-11e7-a951-0469f8dc10a5",
    "aud": "dir:b77bfa0f-d6f2-11e7-b35b-0469f8dc10a5",
    "jti": "2501e859-d6f4-11e7-b28d-0469f8dc10a5",
    "iat": 1483279200,
    "nbf": 1483279200,
    "exp": 1483279205,
    "response": {
        "status": 201,
        "cache": "no-cache",
        "func": "S512",
        "hash": "1l8UlcxqVVjPVRuYU85Z6DyaU4+0RDTB+MPU2K98PMaKmqAaWIx2QxUNUl6fGrDlGK5PEh1SUtR4XT6JzCSRRQ=="
    }
}

User Contributed

LaunchKey links to user contributed code as a resource to its community. LaunchKey does not in any way guarantee or warrant the quality and security of these code bases. User contributed code is supported by the creators. If you do find a link from the site to user contributed code that is malicious or inappropriate in any way, please report that link to LaunchKey immediately and we will investigate the claim. Submit any issue to LaunchKey support at https://launchkey.com./support. ×