Shortcuts support the use of JSON Web Tokens for authentication and exchanging information with third party services.
Please see https://jwt.io/ for more information.
Using JSON Web Tokens with Shortcuts
To add a JSON Web Token to a Shortcut, add the {{jwt}} parameter to the link URL, as shown in the example below. This would be rendered as https://www.example.com/?jwt=eyJhbzI... when a user clicks on the shortcut.
For more information about creating Shortcuts, please see this guide.
Token Structure
Beekeeper supports both JWT 1.0 and JWT 2.0 which can be configured by us, if you submit your request using the link below. The structure of both are very similar but have slightly different nature when it comes to handling user identification which I will explain in detail later.
When decoded, the payload of our default JSON Web Tokens 1.0 have the following structure:
{
"beekeeper_version": "1.0",
"beekeeper_user": {
"perms": {
"streams": [
{
"perms": [
"r",
"w"
],
"id": 5352
},
{
"perms": [
"r",
"w"
],
"id": 5351
],
"role": "member",
"groups": [
{
"perms": [
"ga"
],
"id": 101
},
{
"perms": [
"m"
],
"id": 102
}
]
},
"name": "Kevin Muller",
"avatar": "https://example.com/avatar.png"
},
"iss": "Beekeeper AG",
"beekeeper_fqdn": "example_tenant.us.beekeeper.io",
"jti": "a1b2cd34-eeff-5566-hijk-9ddd9569d1cb",
"exp": 1477657884,
"iat": 1477485084,
"nbf": 1477485084,
"sub": "kevin_muller"
}
Our example user, Kevin Muller, has read and write permissions for a stream with ID 5352, read and write permissions for a stream with ID 5353, is a group admin for group 101, and a member of group 102.
Should you wish to exclude these permissions from the JWT payload, you can use the {{jwt_without_perms}} placeholder.
JWT 1.0 vs JWT 2.0
None of the permissions structures or stream/group assignments are affected by this difference, but there is a difference when it comes to how the "sub" (or subject) parameter is defined, the presence or absence of the "beekeeper_fqdn" parameter, and the "beekeeper_version" parameter is set. There are four main use cases that revolve around the JWT version (1.0 or 2.0) and the presence or absence of a tenantuserid (or User-ID).
As the permissions aren't affected by these variations, I'll be omitting that component.
JWT 1.0 with tenantuserid
{
"beekeeper_version": "1.0",
"beekeeper_user": {...},
"iss": "Beekeeper AG",
"beekeeper_fqdn": "example.us.beekeeper.io",
"jti": "5328cce4-2045-4446-9100-c17cc83d3e71",
"exp": 1611342846,
"iat": 1611170046,
"nbf": 1611170046,
"sub": "<tenantuserid>"
}
JWT 1.0 without tenantuserid
{
"beekeeper_version": "1.0",
"beekeeper_user": {...},
"iss": "Beekeeper AG",
"beekeeper_fqdn": "example.us.beekeeper.io",
"jti": "7ad40306-4327-4142-a651-9a36be1a88d2",
"exp": 1611342555,
"iat": 1611169755,
"nbf": 1611169755,
"sub": "<profile_UUID(example: d8eb77b6-adcc-4ae5-a9da-b8481834b5b3)>"
}
JWT 2.0 with tenantuserid
{
"beekeeper_version": "2.0",
"beekeeper_user": {...},
"iss": "Beekeeper AG",
"beekeeper_fqdn": "example.us.beekeeper.io",
"jti": "f00cb481-1a53-4128-9781-2ddc2227b8ec",
"exp": 1611347094,
"iat": 1611174294,
"nbf": 1611174294,
"tenantuserid": "<tenantuserid>",
"sub": "<profile_UUID (example: d8eb77b6-adcc-4ae5-a9da-b8481834b5b3)>"
}
JWT 2.0 without tenantuserid
{
"beekeeper_version": "2.0",
"beekeeper_user": {...},
"iss": "Beekeeper AG",
"beekeeper_fqdn": "example.us.beekeeper.io",
"jti": "27ac8817-ebce-4098-b8ca-4de75cafc3a3",
"exp": 1611343331,
"iat": 1611170531,
"nbf": 1611170531,
"tenantuserid": null,
"sub": "<profile_UUID (example: d8eb77b6-adcc-4ae5-a9da-b8481834b5b3)>"
}
If you'd like to enable or confirm that you are using JWT 1.0 or 2.0 please use the link below to submit your request.
Permissions
Permissions can be translated as follows:
Permission |
Description |
a |
Global Admin |
ga |
Group Admin |
ca |
Stream Admin |
m |
Group Member |
w |
Can Create Posts |
r |
Can Read Posts |
See Permissions for more information.
JWT Public Key / Signature
The public key used to verify the JSON Web Tokens generated by Beekeeper can be found at https://your-company.beekeeper.io/api/2/extensions/jwt/public_key.
Comments
0 comments
Please sign in to leave a comment.