Auth
The following sections describes how the authentication and authorization works for Cedalio's GraphQL gateway and explains the core concepts behind them
Cedalio's authentication system is built upon three essential components: Authentication, Authorization and Data ownership model. These components use a Smart Contract (EVM Compatible) to effectively store and execute the access control layer.
A high level illustration of how the authentication and authorization flow works
Authentication is implemented by proving wallet ownership. All operations sent to the GraphQL gateway must be associated with a wallet. This is a key design decision in Cedalio's architecture because each database is paired with a smart-contract where all the rules that govern the access to it live.
The basic way of authenticating requires obtaining a JSON Web Token (JWT) by signing a nonce with a wallet's private key. This is a common "web3" login mechanism where you sign a message with a wallet, e.g: MetaMask. You can also use other auth provider, more info here.
Once you obtain a valid gateway JWT you can deploy a new database and send GraphQL operations to it. Every-time the gateway receives a request it validates the authenticity of the JWT and extracts the sender's wallet public address from it. Because generating a JWT requires proving that the user owns the wallet and because the JWT is also signed by the gateway, we know that a JWT is valid.
JWT are short-lived, currently for 30 minutes. They can be thought as having a 30 minutes session. After the JWT expires, the session expires and a new JWT must be obtained.
JWT MUST not be shared because (as long as it hasn't expire) they allow to operate on-behalf of a wallet owner without having to sign individual transactions.
There are two main actors, the
owner and the delegate . As mentioned before, each database has a smart-contract associated with it where all the access rule live. The smart-contract owner is the wallet that created or deployed the database. Databases can be created by calling the project's deploy endpoint (https://$PROJECT_ID.gtw.cedalio.io/deploy) or by accessing the Cedalio Studio and clicking on DEPLOY SCHEMA in a project's detail page. Both methods require "connecting a Wallet" either by obtaining a JWT or by linking a wallet via the UI. The "connected" wallet is the one set as the database owner, which means that the smart-contract is effectively owned that such wallet. The owner is the only one that can set who the delegate is and has full read and write access to the entire database. It can also configure database access rules in the smart-contract (more on that below).
The delegate is set when the smart-contract associated with the newly created database is deployed. The delegate is a wallet controlled by Cedalio that is generated and securely stored when a project is created. This wallet is the one that signs all the transactions, on behalf of the operation sender address, and therefore paying for all transactions fees. The delegate has also full read and write access but it cannot set who the owner or delegate is. It can also set database access rules.
Authorization occurs in two moments. First after the GraphQL gateway verifies the authenticity of the JWT, after that it checks that the current signed-in user (identified by its associated wallet within the JWT) has the right capabilities to access the target resource or endpoint. For example, if a user is trying to deploy a database by calling the
https://$PROJECT_ID.gtw.cedalio.io/deploy endpoint, they should have the capability to deploy databases.Secondly, when a GraphQL operation request is sent to access a database, the GraphQL gateway checks with the smart-contract associated with the database that the operation sender's wallet address (extracted from the JWT) is allowed to execute such operation.
The process of verifying that an operation sender is allowed to execute a GraphQL operation, involves parsing the operation and transform it into a call to the
isOperationAllowed smart-contract method. Which basically checks if there is an access rule defined to the operation sender and if the rule allows the operation to be executed.Rules can be thought as statement of the form:
Address can [ CREATE | UPDATE | READ | DELETE ] OBJECT (fields*)Which means that for each address whitelisted in the access rules, the type of operation can be specified (create, update, read or delete) and also the subject or object type (including which fields can be accessed).
For example let's say that we have the following GraphQL schema:
type Todo @model{
title: String!
description: String
priority: Int!
tags: [String!]
status: Status
}
The following are possible valid access rules:
- Allow address
0x0ABC01to create and read ToDo objects - Allow address
0x0XYZ02to read ToDo objects but only fields title and status - Allow address
0x0ABC02to read and update the ToDo's status field
If you want to know how to implement the authentication flow for your application check the Authentication flow section.
If you want to know which auth provider are natively supported by Cedalio check the Providers section.
If you want to know about the high level project and databases access modes check the Access modes section.
Last modified 4mo ago