Changeset View
Changeset View
Standalone View
Standalone View
src/docs/contributor/using_oauthserver.diviner
| @title Using the Phabricator OAuth Server | @title Using the Phorge OAuth Server | ||||
| @group developer | @group developer | ||||
| How to use the Phabricator OAuth Server. | How to use the Phorge OAuth Server. | ||||
| = Overview = | = Overview = | ||||
| Phabricator includes an OAuth Server which supports the | Phorge includes an OAuth Server which supports the | ||||
| `Authorization Code Grant` flow as described in the OAuth 2.0 | `Authorization Code Grant` flow as described in the OAuth 2.0 | ||||
| specification: | specification: | ||||
| http://tools.ietf.org/html/draft-ietf-oauth-v2-23 | http://tools.ietf.org/html/draft-ietf-oauth-v2-23 | ||||
| This functionality can allow clients to integrate with a given | This functionality can allow clients to integrate with a given | ||||
| Phabricator instance in a secure way with granular data access. | Phorge instance in a secure way with granular data access. | ||||
| For example, Phabricator can be used as a central identity store for any | For example, Phorge can be used as a central identity store for any | ||||
| clients that implement OAuth 2.0. | clients that implement OAuth 2.0. | ||||
| = Vocabulary = | = Vocabulary = | ||||
| - **Access token** - a token which allows a client to ask for data on behalf | - **Access token** - a token which allows a client to ask for data on behalf | ||||
| of a resource owner. A given client will only be able to access data included | of a resource owner. A given client will only be able to access data included | ||||
| in the scope(s) the resource owner authorized that client for. | in the scope(s) the resource owner authorized that client for. | ||||
| - **Authorization code** - a short-lived code which allows an authenticated | - **Authorization code** - a short-lived code which allows an authenticated | ||||
| Show All 11 Lines | |||||
| = Setup - Creating a Client = | = Setup - Creating a Client = | ||||
| # Visit {nav Your Local Install > OAuth Server > Create Application} | # Visit {nav Your Local Install > OAuth Server > Create Application} | ||||
| # Fill out the form | # Fill out the form | ||||
| # Profit | # Profit | ||||
| = Obtaining an Authorization Code = | = Obtaining an Authorization Code = | ||||
| POST or GET `https://phabricator.example.com/oauthserver/auth/` with the | POST or GET `https://phorge.example.com/oauthserver/auth/` with the | ||||
| following parameters: | following parameters: | ||||
| - Required - **client_id** - the id of the newly registered client. | - Required - **client_id** - the id of the newly registered client. | ||||
| - Required - **response_type** - the desired type of authorization code | - Required - **response_type** - the desired type of authorization code | ||||
| response. Only code is supported at this time. | response. Only code is supported at this time. | ||||
| - Optional - **redirect_uri** - override the redirect_uri the client | - Optional - **redirect_uri** - override the redirect_uri the client | ||||
| registered. This redirect_uri must have the same fully-qualified domain, | registered. This redirect_uri must have the same fully-qualified domain, | ||||
| path, port and have at least the same query parameters as the redirect_uri | path, port and have at least the same query parameters as the redirect_uri | ||||
| Show All 11 Lines | |||||
| an error indicating the resource owner did not authorize the client, depending. | an error indicating the resource owner did not authorize the client, depending. | ||||
| If done correctly and the resource owner has already authorized the client for | If done correctly and the resource owner has already authorized the client for | ||||
| the desired scope, then the OAuth Server will redirect to the pertinent | the desired scope, then the OAuth Server will redirect to the pertinent | ||||
| redirect_uri with a valid authorization code. | redirect_uri with a valid authorization code. | ||||
| If there is an error, the OAuth Server will return a descriptive error | If there is an error, the OAuth Server will return a descriptive error | ||||
| message. This error will be presented to the resource owner on the | message. This error will be presented to the resource owner on the | ||||
| Phabricator domain if there is reason to believe there is something fishy | Phorge domain if there is reason to believe there is something fishy | ||||
| with the client. For example, if there is an issue with the redirect_uri. | with the client. For example, if there is an issue with the redirect_uri. | ||||
| Otherwise, the OAuth Server will redirect to the pertinent redirect_uri | Otherwise, the OAuth Server will redirect to the pertinent redirect_uri | ||||
| and include the pertinent error information. | and include the pertinent error information. | ||||
| = Obtaining an Access Token = | = Obtaining an Access Token = | ||||
| POST or GET `https://phabricator.example.com/oauthserver/token/` | POST or GET `https://phorge.example.com/oauthserver/token/` | ||||
| with the following parameters: | with the following parameters: | ||||
| - Required - **client_id** - the id of the client | - Required - **client_id** - the id of the client | ||||
| - Required - **client_secret** - the secret of the client. | - Required - **client_secret** - the secret of the client. | ||||
| This is used to authenticate the client. | This is used to authenticate the client. | ||||
| - Required - **code** - the authorization code obtained earlier. | - Required - **code** - the authorization code obtained earlier. | ||||
| - Required - **grant_type** - the desired type of access grant. | - Required - **grant_type** - the desired type of access grant. | ||||
| Only token is supported at this time. | Only token is supported at this time. | ||||
| - Optional - **redirect_uri** - should be the exact same redirect_uri as | - Optional - **redirect_uri** - should be the exact same redirect_uri as | ||||
| the redirect_uri specified to obtain the authorization code. If no | the redirect_uri specified to obtain the authorization code. If no | ||||
| redirect_uri was specified to obtain the authorization code then this | redirect_uri was specified to obtain the authorization code then this | ||||
| should not be specified. | should not be specified. | ||||
| If done correctly, the OAuth Server will redirect to the pertinent | If done correctly, the OAuth Server will redirect to the pertinent | ||||
| redirect_uri with an access token. | redirect_uri with an access token. | ||||
| If there is an error, the OAuth Server will return a descriptive error | If there is an error, the OAuth Server will return a descriptive error | ||||
| message. | message. | ||||
| = Using an Access Token = | = Using an Access Token = | ||||
| Simply include a query param with the key of "access_token" and the value | Simply include a query param with the key of "access_token" and the value | ||||
| as the earlier obtained access token. For example: | as the earlier obtained access token. For example: | ||||
| ```https://phabricator.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp``` | ```https://phorge.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp``` | ||||
Lint: Line Too Long: This line is 94 characters long, but the convention is 80 characters. | |||||
| If the token has expired or is otherwise invalid, the client will receive | If the token has expired or is otherwise invalid, the client will receive | ||||
| an error indicating as such. In these cases, the client should re-initiate | an error indicating as such. In these cases, the client should re-initiate | ||||
| the entire `Authorization Code Grant` flow. | the entire `Authorization Code Grant` flow. | ||||
| NOTE: See "Scopes" section below for more information on what data is | NOTE: See "Scopes" section below for more information on what data is | ||||
| currently exposed through the OAuth Server. | currently exposed through the OAuth Server. | ||||
| Scopes | Scopes | ||||
| ====== | ====== | ||||
| //This section has not been written yet.// | //This section has not been written yet.// | ||||
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0
This line is 94 characters long, but the convention is 80 characters.