Seald: documentation

# JSON Web Tokens

Par mesure de sécurité, la création d'identité et le chiffrement anonyme nécessitent des JSON Web tokens.

Cette fonctionnalité remplace les anciens User License Tokens qui sont maintenant dépréciés.

# Génération des secrets de JSON Web Token

Pour créer un JSON Web Token, il vous faut tout d'abord un JWTSecret. À chaque secret est associé un ID JWTSecretId. Vous devrez récupérer ces deux valeurs pour permettre à votre serveur de créer des JSON Web Tokens.

Chaque JWTSecret possède des permissions. Pour plus de détails, référez-vous à la section permissions.

TIP

JWTSecret est, comme son nom l'indique, secret. Veuillez prendre toutes les précautions nécessaires pour le stocker de manière sécurisée.

Au contraire, JWTSecretId n'est lui pas secret.

# Via le dashboard

Lors de la création de votre compte, un secret de JWT incluant toutes les permissions (permission : -1) est automatiquement créé. Celui si s'affiche sur la page d'accueil.

Pour générer un autre secret, connectez vous sur votre dashboard d'administration et suivez les étapes suivantes :

  • Allez dans les paramètres, onglet secret de JWT.
  • Cliquez sur créer un secret.
  • Sélectionnez les permissions souhaitées.
  • Confirmez la création du secret.

Une fois le secret créé, récupérez son ID, JWTSecretId, et sa valeur : JWTSecret.

# De manière programmatique

Afin de créer un JWTSecret, vous pouvez faire un POST /dashboardapi/v2/jwtsharedsecret/, avec dans le corps de la requête :

{
  "permissions": Array<Permission>
}

# Exemple de code

Exemple de requête pour créer un JWTSecret :

curl -X POST https://dashboard.seald.io/dashboardapi/v2/jwtsharedsecret/ \
  -H 'X-DASHBOARD-API-KEY: VOTRE_JETON_D_ACCES' \
  -H 'Content-Type: application/json' \
  --data-raw '{"permissions": [1]}'

Exemple de retour :

{
  "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>
}

# Ajout d'un userId

Il est possible d'associer un userId à une identité du SDK. Ce userId est un string qui caractérise un utilisateur de façon unique pour votre application. Vous pouvez choisir tout identifiant unique. Selon le modèle d'un utilisateur dans votre application, vous pouvez par exemple choisir : le nom d'utilisateur, son adresse email, son ID interne dans votre application, ...

Pour cela, le secret de JWT doit avoir la permission PERMISSION_ADD_CONNECTOR. Ce userId sera à spécifier par la clé connector_add du JWT.

WARNING

Le userId est stocké en clair dans notre base de données. Pour minimiser les données que Seald enregistre sur vos utilisateurs, il est donc déconseillé d'utiliser une adresse email ou toute autre donnée personnelle. La solution optimale est d'utiliser un UUID.

# Permissions des JSON Web Token

Chaque JWTSecret possède des permissions, et il peut assigner tout ou partie des permissions qu'il possède à chacun des JSON Web Token qu'il crée.

Les Permission sont des nombres entiers. Les valeurs possibles sont les suivantes :

  • PERMISSION_ALL = -1 : toutes les permissions.
  • PERMISSION_ANONYMOUS_CREATE_MESSAGE = 0 : permet de créer des JSON Web Tokens pouvant créer des messages anonymement.
  • PERMISSION_ANONYMOUS_FIND_KEYS = 1 : permet de créer des JSON Web Tokens pouvant récupérer des clés de chiffrement des destinataires.
  • PERMISSION_ANONYMOUS_FIND_SIGCHAIN = 2 : permet de créer des JSON Web Tokens pouvant récupérer la SigChain des destinataires. Non-utilisé.
  • PERMISSION_JOIN_TEAM = 3 : permet de créer des JSON Web Tokens permettant à une instance de SDK de rejoindre votre team.
  • PERMISSION_ADD_CONNECTOR = 4 : permet de créer des JSON Web Tokens permettant d'ajouter un identifiant personnalisé à une identité du SDK.

# Création d'un JSON Web Token

Le JSON Web Token, ou JWT, est créé avec le JWTSecret et son JWTSecretId : il a comme iss le JWTSecretId, et est signé avec le JWTSecret avec l'algorithme HS256.

Ses données sont :

Nom Type Domaine d'utilisation Description
iss string Général "Issuer" : le JWTSecretId
iat number Général "Issued at" : horodatage (en seconde) du moment de création du JWT. Si exp n'est pas défini, le JWT expire au bout de 10 min après création.
exp? number Général "Expire" : horodatage (en seconde) du moment où le JWT expire. Optionnel. Si non défini, le JWT expire au bout de 10 min après création.
jti? number Général "JWT ID" : nonce unique. Ne doit jamais être réutilisé. Optionnel. Si défini, ce JWT n'est utilisable qu'une seule fois. Sinon, il est utilisable jusqu'à son expiration éventuelle.
scopes? Array<Permission> Général Liste des permissions de ce JWT. Optionnel. Doit être un sous-ensemble des permissions du JWTSecret. Si défini, ce JWT est limité à ces permissions uniquement. Sinon, il possède toutes les permissions du JWTSecret créateur.
recipients? Array<string> Chiffrement anonyme Liste des sealdIds des destinataires pour qui ce JWT est autorisé à effectuer des opérations.
owner? string Chiffrement anonyme Optionnel pour la récupération de clés de destinataires. Nécessaire pour la création de message. sealdId de l'utilisateur qui sera propriétaire des messages créés.
join_team? boolean Gestion des identités Permet à l'identité de rejoindre votre team. Chaque identité ne peux être que dans une seule team à la fois.
connector_add? { value: connectorValue, type: 'AP' } Gestion des identités Permet l'ajout d'un identifiant personnalisé userId à une identité. La value doit être de la forme userId@appId

# Exemple de code

Exemple de création d'un JWT d'inscription, permettant à une identité de rejoindre votre équipe, en Node.JS :

Exemple de création d'un JWT permettant d'ajouter un userId à une identité, en Node.JS :

Exemple de création d'un JWT de chiffrement anonyme en Node.JS :

Exemple de création d'un JWT en Python :

← Serveur staging vs prod →