DEFINE TOKEN statement

SurrealDB can work with third-party OAuth providers. Let's say that your provider issues your service a JWT once it's authenticated. By using the DEFINE TOKEN statement, you can set the public key needed to verify a JWT's authenticity.

You can specify what TYPE of cryptographic signature algorithm your token uses. The following algorithms are supported:
EDDSA, ES256, ES384, ES512, HS256, HS384, HS512, PS256, PS384, PS512, RS256, RS384, RS512.

If not specified the default algorithm used is HS512.

Requirements

• To DEFINE TOKEN ... ON NAMESPACE ... you must have root or namespace level access.
• To DEFINE TOKEN ... ON DATABASE ... you must have root, namespace, or database level access.
• To DEFINE TOKEN ... ON SCOPE ... you must have root, namespace, or database level access.
• You must select your namespace and/or database before you can use the DEFINE DATABASE statement for database or namespace tokens.

Statement syntax

DEFINE TOKEN @name ON [ NAMESPACE | DATABASE | SCOPE @scope ] TYPE @type VALUE @value

Example usage

The following example shows how you could use the DEFINE TOKEN statement.

-- Specify the namespace and database for the token
USE NS abcum DB app_vitalsense;

-- Set the name of the token
DEFINE TOKEN token_name
  -- Use this OAuth provider for database authorization
  ON DATABASE
  -- Specify the cryptographic signature algorithm used to sign the token
  TYPE HS512
  -- Specify the public key so we can verify the authenticity of the token
  VALUE "sNSYneezcr8kqphfOC6NwwraUHJCVAt0XjsRSNmssBaBRh3WyMa9TRfq8ST7fsU2H2kGiOpU4GbAF1bCiXmM1b3JGgleBzz7rsrz6VvYEM4q3CLkcO8CMBIlhwhzWmy8"
;

Using Tokens

The DEFINE TOKEN statement lets you specify the amount of permission granting authority you want to give to an OAuth provider. You're able to specify if the provider can grant namespace, database, or scope level access to token holders. For this to work, the issued tokens must contain specific fields to specify what namespace, database or scope or the token bearer is authorized to act on.

Namespace

The following example shows how this would work for a token to grant authorization on a namespace.

-- Specify the namespace for the token
USE NS abcum;

-- Set the name of the token
DEFINE TOKEN token_name
  -- Use this OAuth provider for namespace authorization
  ON NAMESPACE
  -- Specify the cryptographic signature algorithm used to sign the token
  TYPE HS512
  -- Specify the public key so we can verify the authenticity of the token
  VALUE "sNSYneezcr8kqphfOC6NwwraUHJCVAt0XjsRSNmssBaBRh3WyMa9TRfq8ST7fsU2H2kGiOpU4GbAF1bCiXmM1b3JGgleBzz7rsrz6VvYEM4q3CLkcO8CMBIlhwhzWmy8"
;

When a token is issued by your OAuth provider, the payload should contain the following field when used to authenticate with SurrealDB.

{
  "NS": "abcum",
  // Other data
}

Database

The following example shows how this would work for a token to grant authorization on a database.

-- Specify the namespace and database for the token
USE NS abcum DB app_vitalsense;

-- Set the name of the token
DEFINE TOKEN token_name
  -- Use this OAuth provider for database authorization
  ON DATABASE
  -- Specify the cryptographic signature algorithm used to sign the token
  TYPE HS512
  -- Specify the public key so we can verify the authenticity of the token
  VALUE "sNSYneezcr8kqphfOC6NwwraUHJCVAt0XjsRSNmssBaBRh3WyMa9TRfq8ST7fsU2H2kGiOpU4GbAF1bCiXmM1b3JGgleBzz7rsrz6VvYEM4q3CLkcO8CMBIlhwhzWmy8"
;

{
  "NS": "abcum",
  "DB": "app_vitalsense",
  // Other data
}

Scope

The following example shows how this would work for a token to grant authorization on a scope.

-- Specify the namespace for the token
USE NS abcum DB app_vitalsense;

-- Define the scope
DEFINE SCOPE account;

-- Set the name of the token
DEFINE TOKEN token_name
  -- Use this OAuth provider for scope authorization
  ON SCOPE account
  -- Specify the cryptographic signature algorithm used to sign the token
  TYPE HS512
  -- Specify the public key so we can verify the authenticity of the token
  VALUE "sNSYneezcr8kqphfOC6NwwraUHJCVAt0XjsRSNmssBaBRh3WyMa9TRfq8ST7fsU2H2kGiOpU4GbAF1bCiXmM1b3JGgleBzz7rsrz6VvYEM4q3CLkcO8CMBIlhwhzWmy8"
;

{
  "NS": "abcum",
  "DB": "app_vitalsense",
  "SC": "account",
  // Other data
}