meta.sr.ht offers an OAuth 2.0-compatible (RFC 6749) authorization process for access to the sr.ht GraphQL APIs. This document explains the sr.ht-specific details of our RFC 6749 implementation and is intended to be accompanied by a reading of the RFC.
Our OAuth 2.0 implementation has the following caveats:
In the use-case of a native application, where the public client type specified in RFC 6749 is preferred, the application must either provide a web server component which completes the confidential authentication process and shares the access token with the application; or the application should ask the user to provide a personal access token, which can be generated at meta.sr.ht/oauth2. In the latter case, the application should inform the user of the grant string which supports only the minimum access level required to use the application's features.
OAuth 2.0 clients using sr.ht must specify explicitly the list of features they wish to be granted permission to use.
The format of the scope string, per section 3.3 is a
space-delineated list of grants. Each grant has three components: service,
scope, and access kind; and is formatted as
The service is the name of the service the access grant applies to, such as "meta.sr.ht".
The scope is the specific feature of that service which the grant applies to,
such as "SSH_KEYS". The list of access scopes available for each API is
documented in the GraphQL schema for that API in the
enum AccessScope type.
The access kind is either
RW; respectively referring to read-only or
read/write access to that scope.
meta.sr.ht/PROFILE:RO meta.sr.ht/SSH_KEYS:RW git.sr.ht/REPOS:RO
The scopes necessary to use each GraphQL resolver are also indicated in the
GraphQL schema with the
OAuth 2.0 clients may be registered at meta.sr.ht/oauth2. You will be issued a client ID and secret per sections 2.2 & 2.3. The client ID is a UUID, and the secret is 64-byte random string, base64 encoded. It is not necessary to interpret them; they are passed verbatim to our OAuth 2.0 endpoints.
The authorization endpoint (see section 4.1.1) is
https://meta.sr.ht/oauth2/authorize. Note that meta.sr.ht differs from the
specification in that it REQUIRES the scope parameter to be provided; per
section 3.3 meta.sr.ht interprets the absence of the scope
parameter as an invalid scope and will cause the request to fail.
The redirect_uri parameter is prohibited by meta.sr.ht, and MUST NOT be included in the authorization endpoint URL. The only supported redirect URI is the one provided during client registration. If request-specific state is required, utilize the state parameter.
The authorization code issued is a 16 character hexadecimal string, and it must be used within 5 minutes.
The access token endpoint (see section 4.1.3) is
request_uri parameter MUST NOT
be provided by the client. HTTP Basic authentication is also recommended per
section 2.3.1. Our access token response will always set the
token type to "bearer".
commit 5e3b25c91b85507d152f17800921ae9179516247 Author: Vlad-Stefan Harbuz <email@example.com> Date: 2022-11-14T09:16:47+00:00 hacking: add examples for clarity Signed-off-by: Vlad-Stefan Harbuz <firstname.lastname@example.org>