Handle authentication
Since SurrealDB is a database that is designed to be used in a distributed environment, it is important to secure the database and the data that is stored in it. SurrealDB provides a number of methods for authenticating users and securing the database.
In your SurrealDB database, you can create authentication login using the DEFINE ACCESS statement which supports JWT and Record Access methods.
The access method used will inform the input for Access in the .SignUp() and .SignIn() methods.
If you are not on Version v3.0.2 of SurrealDB, you will use the Scope property instead of Access.
Defining access in your application
The .NET SDK has a .Query() method which allows you to write secure SurrealQL statements from within your application. Using this method, you can define access for your users and securely manage authentication. See the code example below:
await db.Query(
$"""
DEFINE ACCESS account ON DATABASE TYPE RECORD
SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) )
DURATION FOR TOKEN 15m, FOR SESSION 12h;
"""
);
await db.Query(
$"""
DEFINE SCOPE user SESSION 24h
SIGNUP ( CREATE user SET email = $email, pass = crypto::argon2::generate($pass) )
SIGNIN ( SELECT * FROM user WHERE email = $email AND crypto::argon2::compare(pass, $pass) );
"""
);
Depending on the connection protocol you choose, authentication tokens and sessions lifetime work differently. Refer to the connection options documentation for more information.
User authentication
After you have defined your authentication login, you can use the following methods to authenticate users:
.SignUp()
Signs up to a specific authentication scope / access method.
Method Syntax
await db.SignUp(credentials)
Arguments
| Arguments | Description |
|---|
credentials required | Credentials to sign up as a scoped user. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var authParams = new AuthParams
{
Namespace = "test",
Database = "test",
Access = "user",
Email = "info@surrealdb.com",
Password = "123456"
};
Jwt jwt = await db.SignUp(authParams);
public class AuthParams : ScopeAuth
{
public string? Username { get; set; }
public string? Email { get; set; }
public string? Password { get; set; }
}
var authParams = new AuthParams
{
Namespace = "test",
Database = "test",
Scope = "user",
Email = "info@surrealdb.com",
Password = "123456"
};
Jwt jwt = await db.SignUp(authParams);
public class AuthParams : ScopeAuth
{
public string? Username { get; set; }
public string? Email { get; set; }
public string? Password { get; set; }
}
.SignIn()
Signs in to a root, namespace, database or scope user.
Method Syntax
await db.SignIn(credentials)
Arguments
| Arguments | Description |
|---|
credentials required | Variables used in a signin query. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await db.SignIn(new RootAuth { Username = "root", Password = "secret" });
await db.SignIn(
new NamespaceAuth
{
Namespace = "test",
Username = "johndoe",
Password = "password123"
}
);
await db.SignIn(
new DatabaseAuth
{
Namespace = "test",
Database = "test",
Username = "johndoe",
Password = "password123"
}
);
var authParams = new AuthParams
{
Namespace = "test",
Database = "test",
Access = "user",
Email = "info@surrealdb.com",
Password = "123456"
};
Jwt jwt = await db.SignIn(authParams);
public class AuthParams : ScopeAuth
{
public string? Username { get; set; }
public string? Email { get; set; }
public string? Password { get; set; }
}
var authParams = new AuthParams
{
Namespace = "test",
Database = "test",
Scope = "user",
Email = "info@surrealdb.com",
Password = "123456"
};
Jwt jwt = await db.SignIn(authParams);
public class AuthParams : ScopeAuth
{
public string? Username { get; set; }
public string? Email { get; set; }
public string? Password { get; set; }
}
.Authenticate()
Authenticates the current connection with a JWT token.
Method Syntax
await db.Authenticate(jwt)
Arguments
| Arguments | Description |
|---|
jwt required | The JWT object holder of the authentication token. |
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
var jwt = new Jwt("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJTdXJyZWFsREIiLCJpYXQiOjE1MTYyMzkwMjIsIm5iZiI6MTUxNjIzOTAyMiwiZXhwIjoxODM2NDM5MDIyLCJOUyI6InRlc3QiLCJEQiI6InRlc3QiLCJTQyI6InVzZXIiLCJJRCI6InVzZXI6dG9iaWUifQ.N22Gp9ze0rdR06McGj1G-h2vu6a6n9IVqUbMFJlOxxA");
await db.Authenticate(jwt);
.Invalidate()
Invalidates the authentication for the current connection.
Method Syntax
await db.Invalidate()
Arguments
| Properties | Description |
|---|
cancellationToken optional | The cancellationToken enables graceful cancellation of asynchronous operations. |
Example usage
await db.Invalidate();
