Configuring authentication

One of the first things you need to do when embedding Weavy into your application is configuring authentication. This is done by passing a JSON Web Token (JWT) from your backend system to Weavy.

JWT is an open standard RFC 7519 for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed. JWTs can be signed using a shared secret or a public/private key pair . When tokens are signed using public/private key pairs, the signature also certifies that only the party holding the private key is the one that signed it. You can read more about JSON Web Tokens at jwt.io.

Getting or creating the JWT

Depending on your application setup and technology you might already have a way to get a JWT for your signed in users, in that case you can usually pass your existing JWT along to Weavy. If not, there are numerous libraries to help you with the creation of a JWT.

There are only a couple of required claims that must be included in the JWT.

  • iss - A name or id that uniquely identifies your application.
  • sub - A unique identifier for the user in your application, usually the user id.
  • exp - The expiration time of the token.

Additionally, Weavy will automatically map some "well known" claims to corresponding properties on the Weavy User object as explained below.

  • dir - Id or name of user directory where the user belongs.
  • email - Primary email address.
  • family_name - Family name (surname or last name).
  • given_name - Given name (first name).
  • middle_name - Middle name.
  • name - Display name (including including all name parts, titles and suffixes).
  • nickname - Nickname.
  • phone_number - Phone number.
  • picture - User profile picture. Either an URL to an image that is publicly accessible or a base64 encoded data URL (data:image/...).
  • preferred_username - Preferred username.
  • username - Preferred username.

Other than the claims described above, your JWT can contain any number of additional claims.

Passing the JWT to Weavy

Depending on use-case, the JWT can be passed to Weavy in slightly different ways. See for instance Drop-in UI authentication on how to pass the JWT using the drop-in UI.

Validating the JWT

For the JWT to be accepted, Weavy must be able to verify the digital signature of the token (Weavy supports JWTs signed with HS256, HS384, HS512, RS256, RS384, RS512, PS256, PS384, PS512, ES256, ES384, and ES512).

To do that you have to configure an IdentityProvider that matches the Issuer (iss) of your token. The identity provider can be your app or an identity management service like Azure AD, Auth0, Okta or similar. Depending on the algorithm used to sign the JWT you should specify either a Secret or PublicKey as shown in the examples below:

"IdentityProviders": [
  {
    "Issuer": "value of the iss claim in your JWT",
    "Secret": "the secret used to sign your token"
  }          
]

Public keys should be PEM-encoded, prefixed with -----BEGIN PUBLIC KEY-----, and postfixed with -----END PUBLIC KEY-----.

"IdentityProviders": [  
  {
    "Issuer": "value of the iss claim in your JWT",
    "PublicKey": "-----BEGIN PUBLIC KEY-----MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEEVs/o5+uQbTjL3chynL4wXgUg2R9q9UU8I5mEovUf86QZ7kOBIjJwqnzD1omageEHWwHdBO6B+dFabmdT9POxg==-----END PUBLIC KEY-----"
  }          
]

If your Issuer (identity provider) supports the OpenID Connect protocol you don't have to specify a Secret or PublicKey as Weavy can automatically fetch the public signing keys via the metadata document located at the /.well-known/openid-configuration path.

"IdentityProviders": [  
  {
    "Issuer": "https://your.openidconnectprovider.com"
  }          
]
Weavy Docs