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
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 |
Identifiers for LaunchKey applications will only have the application identifier. They are:
lka: | LaunchKey API |
---|
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. |
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. |
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.
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=="
}
}
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=="
}
}
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. ×