Differential D25007 Diff 23 src/docs/contributor/using_oauthserver.diviner

Changeset 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```

	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.//