DEFINE
statement
TOKEN
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
}