recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Using the Phorge OAuth Server
2@group developer
3
4How to use the Phorge OAuth Server.
5
6= Overview =
7
8Phorge includes an OAuth Server which supports the
9`Authorization Code Grant` flow as described in the OAuth 2.0
10specification:
11
12https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-23
13
14This functionality can allow clients to integrate with a given
15Phorge instance in a secure way with granular data access.
16For example, Phorge can be used as a central identity store for any
17clients that implement OAuth 2.0.
18
19= Vocabulary =
20
21- **Access token** - a token which allows a client to ask for data on behalf
22 of a resource owner. A given client will only be able to access data included
23 in the scope(s) the resource owner authorized that client for.
24- **Authorization code** - a short-lived code which allows an authenticated
25 client to ask for an access token on behalf of some resource owner.
26- **Client** - this is the application or system asking for data from the
27 OAuth Server on behalf of the resource owner.
28- **Resource owner** - this is the user the client and OAuth Server are
29 concerned with on a given request.
30- **Scope** - this defines a specific piece of granular data a client can
31 or can not access on behalf of a user. For example, if authorized for the
32 "whoami" scope on behalf of a given resource owner, the client can get the
33 results of Conduit.whoami for that resource owner when authenticated with
34 a valid access token.
35
36= Setup - Creating a Client =
37
38# Visit {nav Your Local Install > OAuth Server > Create OAuth Server}
39# Fill out the form
40# Profit
41
42= Obtaining an Authorization Code =
43
44POST or GET `https://phorge.example.com/oauthserver/auth/` with the
45following parameters:
46
47- Required - **client_id** - the id of the newly registered client.
48- Required - **response_type** - the desired type of authorization code
49 response. Only code is supported at this time.
50- Optional - **redirect_uri** - override the redirect_uri the client
51 registered. This redirect_uri must have the same fully-qualified domain,
52 path, port and have at least the same query parameters as the redirect_uri
53 the client registered, as well as have no fragments.
54- Optional - **scope** - specify what scope(s) the client needs access to
55 in a space-delimited list.
56- Optional - **state** - an opaque value the client can send to the server
57 for programmatic excellence. Some clients use this value to implement XSRF
58 protection or for debugging purposes.
59
60If done correctly and the resource owner has not yet authorized the client
61for the desired scope, then the resource owner will be presented with an
62interface to authorize the client for the desired scope. The OAuth Server
63will redirect to the pertinent redirect_uri with an authorization code or
64an error indicating the resource owner did not authorize the client, depending.
65
66If done correctly and the resource owner has already authorized the client for
67the desired scope, then the OAuth Server will redirect to the pertinent
68redirect_uri with a valid authorization code.
69
70If there is an error, the OAuth Server will return a descriptive error
71message. This error will be presented to the resource owner on the
72Phorge domain if there is reason to believe there is something fishy
73with the client. For example, if there is an issue with the redirect_uri.
74Otherwise, the OAuth Server will redirect to the pertinent redirect_uri
75and include the pertinent error information.
76
77= Obtaining an Access Token =
78
79POST or GET `https://phorge.example.com/oauthserver/token/`
80with the following parameters:
81
82- Required - **client_id** - the id of the client
83- Required - **client_secret** - the secret of the client.
84 This is used to authenticate the client.
85- Required - **code** - the authorization code obtained earlier.
86- Required - **grant_type** - the desired type of access grant.
87 Only token is supported at this time.
88- Optional - **redirect_uri** - should be the exact same redirect_uri as
89 the redirect_uri specified to obtain the authorization code. If no
90 redirect_uri was specified to obtain the authorization code then this
91 should not be specified.
92
93If done correctly, the OAuth Server will redirect to the pertinent
94redirect_uri with an access token.
95
96If there is an error, the OAuth Server will return a descriptive error
97message.
98
99= Using an Access Token =
100
101Simply include a query param with the key of "access_token" and the value
102as the earlier obtained access token. For example:
103
104```https://phorge.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp```
105
106If the token has expired or is otherwise invalid, the client will receive
107an error indicating as such. In these cases, the client should re-initiate
108the entire `Authorization Code Grant` flow.
109
110NOTE: See "Scopes" section below for more information on what data is
111currently exposed through the OAuth Server.
112
113Scopes
114======
115
116//This section has not been written yet.//