[Summary view] [Print] [Text view]

   1  @title Using the Phabricator OAuth Server
   2  @group developer
   3  
   4  How to use the Phabricator OAuth Server.
   5  
   6  = Overview =
   7  
   8  Phabricator includes an OAuth Server which supports the
   9  `Authorization Code Grant` flow as described in the OAuth 2.0
  10  specification:
  11  
  12  http://tools.ietf.org/html/draft-ietf-oauth-v2-23
  13  
  14  This functionality can allow clients to integrate with a given
  15  Phabricator instance in a secure way with granular data access.
  16  For example, Phabricator can be used as a central identity store for any
  17  clients that implement OAuth 2.0.
  18  
  19  = Vocabulary =
  20  
  21  - **Access token** - a token which allows a client to ask for data on
  22  behalf of a resource owner. A given client will only be able to access
  23  data included 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 https://phabricator.example.com/oauthserver/client/create/
  39  # Fill out the form
  40  # Profit
  41  
  42  = Obtaining an Authorization Code =
  43  
  44  POST or GET https://phabricator.example.com/oauthserver/auth/ with the
  45  following 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  and have at least the same query parameters as the redirect_uri the client
  53  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  
  60  If done correctly and the resource owner has not yet authorized the client
  61  for the desired scope, then the resource owner will be presented with an
  62  interface to authorize the client for the desired scope. The OAuth Server
  63  will redirect to the pertinent redirect_uri with an authorization code or
  64  an error indicating the resource owner did not authorize the client, depending.
  65  
  66  If done correctly and the resource owner has already authorized the client for
  67  the desired scope, then the OAuth Server will redirect to the pertinent
  68  redirect_uri with a valid authorization code.
  69  
  70  If there is an error, the OAuth Server will return a descriptive error
  71  message. This error will be presented to the resource owner on the
  72  Phabricator domain if there is reason to believe there is something fishy
  73  with the client. For example, if there is an issue with the redirect_uri.
  74  Otherwise, the OAuth Server will redirect to the pertinent redirect_uri
  75  and include the pertinent error information.
  76  
  77  = Obtaining an Access Token =
  78  
  79  POST or GET https://phabricator.example.com/oauthserver/token/
  80  with 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  
  93  If done correctly, the OAuth Server will redirect to the pertinent
  94  redirect_uri with an access token.
  95  
  96  If there is an error, the OAuth Server will return a descriptive error
  97  message.
  98  
  99  = Using an Access Token =
 100  
 101  Simply include a query param with the key of "access_token" and the value
 102  as the earlier obtained access token. For example:
 103  
 104  https://phabricator.example.com/api/user.whoami?access_token=ykc7ly7vtibj334oga4fnfbuvnwz4ocp
 105  
 106  If the token has expired or is otherwise invalid, the client will receive
 107  an error indicating as such. In these cases, the client should re-initiate
 108  the entire ##Authorization Code Grant## flow.
 109  
 110  NOTE: See "Scopes" section below for more information on what data is
 111  currently exposed through the OAuth Server.
 112  
 113  = Scopes =
 114  
 115  There are only two scopes supported at this time.
 116  
 117  - **offline_access** - allows an access token to work indefinitely without
 118  expiring.
 119  - **whoami** - allows the client to access the results of Conduit.whoami on
 120  behalf of the resource owner.