Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Alias is a decentralized protocol to implement data portability between services. It empowers the users to choose their own data storage they trust to store their (GDPR, CCPA, ...) data dumps from their services, and to choose its own "data bank" (an authorization server) to let third-parties access its data.
Third-parties implement an Alias client to request and receive the user's data. They can add a "Login with Alias" button on their website.
The Alias protocol is greatly inspired from the OAuth 2.0 protocol. Like it, the protocol happens between 5 parties:
- An User, which owns data and is globally identified by an alias, formed like an email address. Its authentication is protected by a private key only known by themselves;
- A Client, willing to access data of a user with their consent. The data to be sent are described by a list of scopes the client gives to the authorization server;
- An Authorization server, acting as a trusted proxy between the client and the resource servers storing the user's data. It displays the client's contract to the user and wait for their approval;
- An Resource server, storing the user's data.
- An User-agent, being the user's front-end to interact with the client and their autorization server;
Like OAuth 2.0, the grant is represented by a token given to the client by the authorization server. Unlike common OAuth 2.0 implementation, the token is a value similar to a JSON Web Token signed with the user's private key, therefore prooving the consent of the user.
Because the protocol is decentralized, there is no client registration process. A contract, serialized as a JSON object, is generated by the client setting every data necessary for a authorization server to identity it, and what data the client is willing to access.
For a client to request user's data, it must first creates a contract describing its intent. This contract is serialized as a JSON object, storing:
- a list of metadata about the client (name, description, URL, redirection endpoints, ...), signed with its private key;
- a list of scopes to describe the data needed by the user, under what legal base the scopes are, and a human description of how it will be used;
- a list of human-readable legal information necessary to make the contract equivalent to a GDPR/CCPA contract.
When this contract is ready, it can be serialized with anychain and
send as a
GET argument to the authorization server's redirection endpoint (by
/alias/request/). The user-agent is redirected to the authorization
server which will authenticate the user.
When authenticated, the user is then displayed a request window which describes the contract they are about to agree or deny. If certain scopes are opt-out, they may enable them.
If the user denies, the user-agent is redirected to the client's callback endpoint (defined in its contract) with the appropriate error (see OAuth2).
If the user agrees, the user creates a JSON object storing the contract and the
agreed scopes, signs it with their private key. The authorization server is sent
a signed copy, and the user-agent is redirected to the client's callback
endpoint with the
code set to the just-signed object
serialized with anychain.
code is the "grant token", which proves the client has been granted by
the user to access data described in the token.
Now the client has a grant token, it can request data from the authorization server.
To do so, it will perform a HTTP
POST request to the authorization server's
/alias/process with parameter
code the grant token. The
authorization server will respond to this request when the transfer has
finished, or an error occured.
In the Alias protocol, the authorization server performs HTTP requests to the client to send the requested data. The data is pushed by the authorization server to the client.
The authorization will first calculate
grant_hash, the root hash of the grant
token with anychain. From this hash, the base endpoint where to push data
for this grant can be generated as follow:
performs a HTTP request
PUT on this endpoint to notify the client a new
transfer will happen and it must delete previous data received on this grant.
# Request PUT /alias/push/%grant_hash%/ # Response 200 OK
Then, the authorization server will spawn the necessary processors to process
the user's data. Multiple data archives might be generated, each of them
uploaded separately to the client. To do so, it will perform multiple partial
PUT requests to the client to stream the file's data to the client.
# Request PUT /alias/push/%grant_hash%/%filename% Range: %start byte%-%end byte% Content-Length: %length% %data chunk% #Response 206 Partial Range
POST on the same endpoint will notify the client the file is finished and now
# Request POST /alias/push/%grant_hash%/%filename% # Response 200 OK
Finally, a final HTTP request
POST on the grant upload endpoint
/alias/push/%grant_hash%/ will notify the client the transfer of every files
is now finished.