- Implementation Owner: @eldadfux
- Start Date: 26-12-2020
- Target Date: Unknown
- Appwrite Issue: appwrite/appwrite#511
JSON Web Tokens are an open, industry-standard RFC 7519 method for representing claims securely between two parties. By adding support for JWT authentication, Appwrite developers will be able to use their APIs in the user scope. APIs that are currently restricted to the client-side could be useful on the server-side as well. This will allow developers to create interesting new use-cases for Appwrite.
What problem are you trying to solve?
Appwrite Server API is limited and can't access the different services in the user scope and perform an action on his/her behalf. The only current way to use the server API is in admin mode combined with an API key that has relevant permissions scopes. This is limiting the usage in Account, Database, Storage, and other Appwrite APIs.
What is the context or background in which this problem exists?
The current implementation of server API scopes functionality and flexibility is limited. The server API is especially limited when trying to integrate with a custom server or 3rd party databases.
Once the proposal is implemented, how will the system change?
A new authentication method will be introduced to the Appwrite server API. The new authentication method will allow developers to act as a user from their own servers.
Create a new API endpoint called 'createJWT' POST /v1/account/jwt. The new endpoint should be available to an authenticated user. The number of API calls should be limited and protected by the abuse object. We can use adhocore/php-jwt for token creation and validation. Include the UserID and SessionId as part of the JWT payload.
According to Hasura, the best practice for the expiry value of the JWT is around 15 minutes. This, combined with the fact the JWT auth is dependent on a valid auth session, should give a good level of security for the Appwrite project users.
Create a new JWT response model to be returned by the new API endpoint. New model should be located at: src/Appwrite/Utopia/Response/Model.
Allow a new auth method using a header that will contain the JWT secret. If valid, the API will allow the server to perform all actions under the relevant user. The server will also grant access to any resources (files, documents, etc...) belonging to the user. Verify the sessionId and userId are valid when verifying the JWT auth header.
Add all missing API that used to be relevant only for client integrations. Add a new method for attaching JWT secret to the SDK HTTP client.
List all the new server endpoints that are now available on the server API. Add a JWT as a new authentication method for all the relevant API endpoints.
Create a short tutorial that explains how to generate a new JWT on the Web/Flutter/both. Create a server example for consuming the API (Node/Python/PHP/Ruby/Deno) and authenticating a user, and making actions on his behalf.
Not sure what header name we should use for the new authentication method. I would probably go for X-Appwrite-JWT, although Authorization', "Bearer $token" seems to be the go-to option doe most public APIs. The idea to use a custom header is because we have multiple authentication methods (api-key,session,jwt). As far as I can tell, there is no standard way to distinguish between them on the server-side. I would avoid making any wrong usage in a common header that will force us to make API breaking changes.
This feature will create a lot of new use-cases and will probably force us to make the API even more flexible, and new ideas come from the community.