# JSON Web Tokens
As a security measure, in order to avoid misuse of your encryption quotas, your server must allow identity creation and anonymous encryptions using JSON Web tokens.
This feature replaces the now deprecated User License Tokens.
# Creating a JWTSecret
Once the JWTSecret is created, you will need to retrieve this
JWTSecret
and its JWTSecretId
to enable your server to create
JSON Web Tokens.
Each JWTSecret has permissions. For more details, see permissions.
TIP
JWTSecret
is, as the name implies, secret. Please take appropriate
measures to store it securely.
However, JWTSecretId
is not secret.
# Via the dashboard
When creating your dashboard account, a JWT secret including all permissions (permission: -1) is automatically created. This is displayed on the homepage.
To generate another JWT Secret, login to your admin dashboard and follow these steps:
- Go to the settings,
JWT secrets
tab. - Click on
create a secret
. - Select the desired permissions.
- Confirm the creation of the secret.
Once the secret is created, retrieve its ID, JWTSecretId
, and its value: JWTSecret
.
# Programmatically
To create a JSON Web Token, you first need a JWTSecret.
You can create, list, and delete JWTSecret, which allow to create JSON Web Tokens for your team, on the DashboardAPI.
In order to create a JWTSecret, you can make a
POST /dashboardapi/v2/jwtsharedsecret/
, with the request body:
{
"permissions": Array<Permission>
}
# Code example
Example request to create a JWTSecret:
curl -X POST https://dashboard.seald.io/dashboardapi/v2/jwtsharedsecret/ \
-H 'X-DASHBOARD-API-KEY: YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
--data-raw '{"permissions": [1]}'
Example response:
{
"id": "32266d8c-2085-490a-8ef5-259ea35e1501", // UUID : JWTSecretId
"created": "2021-11-09T10:49:09.490338Z", // Timestamp ISO
"shared_secret": "c9kijQo1kJgieXZ9TAHFj9R0TgHb4bgLhDnWWRgjq4TmBzUdSB5mzuOcBb0gQMSi", // String : JWTSecret
"permissions": [ 1 ] // Array<Permission>
}
# Adding a userId
You can add a userId
to a SDK identity. It is a string that specifies a user uniquely for your application.
You can choose any unique identifier. Depending on the user model in your
application, you can for example choose: the username, their email address,
their internal ID in your application, ...
WARNING
The userId
is stored in clear text in our database. In order to minimize the
data that Seald stores about your users, it is not recommended to use an email
address or any other personal identifying information. The optimal is to use a
UUID.
# JSON Web Token permissions
Each JWTSecret has permissions, and it can assign any or all of the permissions it has to each JSON Web Token it creates.
Permission
are integers. Possible values are as follows:
PERMISSION_ALL = -1
: all permissions.PERMISSION_ANONYMOUS_CREATE_MESSAGE = 0
: allows creating JSON Web Tokens which can anonymously create messages.PERMISSION_ANONYMOUS_FIND_KEYS = 1
: allows creating JSON Web Tokens which can retrieve the recipients' encryption keys.PERMISSION_ANONYMOUS_FIND_SIGCHAIN = 2
: allows creating JSON Web Tokens which can retrieve the recipients' SigChain. Unused.PERMISSION_JOIN_TEAM = 3
: allows creating JSON Web Tokens which can add an SDK identity to your team.PERMISSION_ADD_CONNECTOR = 4
: allows creating JSON Web Tokens which can add a customuserId
to an SDK identity.
# Creating a JSON Web Token
The JSON Web Token, or JWT, is created with the JWTSecret
and its
JWTSecretId
: it has the JWTSecretId
as iss
, and is signed with
the JWTSecret
with the HS256
algorithm.
Its payload is:
Name | Type | Use | Description |
---|---|---|---|
iss | string | Always | "Issuer" : the JWTSecretId |
iat? | number | Always | "Issued at" : timestamp (in seconds) of the JWT creation. Optional. If defined, the JWT expires 10 min after creation. If not, it does not expire. |
jti? | number | Always | "JWT ID" : unique nonce. Must never be re-used. Optional. If defined, the JWT is usable only once. If not, it is usable until its potential expiration. |
scopes? | Array<Permission> | Always | List of this JWT's permissions. Optional. Must be a subset of the JWTSecret 's permissions. If defined, the JWT is limited to these permissions only. If not, it has all the permissions assigned to the creating JWTSecret . |
recipients? | Array<string> | Anonymous encryption | List of sealdIds of recipients for whom this JWT is authorized to perform operations. |
owner? | string | Anonymous encryption | Optional for retrieving recipient keys. Necessary for message creation. sealdId of the user who will own the created messages. |
join_team? | boolean | Identities | Allow the identity to join your team. Each identity can only be in one team at a time. |
connector_add? | { value: connectorValue, type: 'AP' } | Identities | Allows the addition of a custom identifier to an identity. The value must be of the form custom-string@AppId . |
# Code example
Example of creating a JWT for signup in Node.JS:
Example of creating a JWT to add a custom userId
in Node.JS:
Example of creating a JWT for anonymous encryption in Node.JS:
Example of creating a JWT in Python: