P4OAuth API

The P4OAuth API provides a few different workflows. The exact calls you'll make varies generally with each workflow. You'll typically need to worry about the "fetch p4 token" workflow, and one of the grant workflows.

You'll have to implement a redirect handler, however, that can retrieve authorization and p4d tokens, and generally know "what to do" with them.

Fetch P4 Token

Outside of the grant workflows is a basic "get me my p4d token for this whitelist" given a particular access token.

Send a GET request to the URL:

https://p4oauth.perforce.com/p4token?redirect_uri=[WHITELISTED URL]&client_id=[LOGIN]

Required header:

Authorization: Bearer A129380-123124-2312314

Required parameters:

redirect_uri: The whitelisted redirect URI
client_id: The perforce user's login

Optional parameter:

state: A custom application state variable, it's recommended to use this, probably something random

This will return the P4D token via text.

Password Authorization Grant

This grant is probably valid for P4OAuth since all of our applications must be put on a whitelist anyway for this thing to work. This allows the client application to collect the login and password, and submits those to the p4oauth server. The code authorization grant has the P4OAuth server collect this information "indirectly".

The user starts at the client application, which collects the username and password
The client application posts this information to the P4OAuth "password grant" URL
The browser is redirected back to the client application with an authorization code
The client application POSTs this authorization code back to the P4OAuth server, and receives the access token (which can be handed off to other apps) and a p4d token usable on that host only.

Password Grant Request

Make a POST request to this URL:

http://p4oauth.example.com/grants/password

Required parameters:

response_type should be `password
client_id - The perforce login
password - The user's password
redirect_uri - The whitelisted application URI we'll be redirecting back to

Optional parameters:

state - If set, this will be sent back to the redirect_uri. Recommended.

Redirect

After login, your client application will be called back with the following information:

[WHITELISTED URL]?code=[AUTH CODE]

If you've added a state option, it will appear as another URL parameter.

Access Token POST

This may change soon to include HTTP basic authentication

Your application should take the AUTH CODE from the redirect, and generate the following POST request to this URL:

https://p4oauth.example.com/grants/token

Required POST parameters:

client_id is the perforce login
redirect_uri is the same URL used for the authorization start request for this authorization code
code is the AUTH CODE sent to the client application's redirect handler
grant_type must be set to authorization_code

The post will return a JSON response:

{
    "token_type": "bearer",
    "access_token": "A129380-123124-2312314",
    "perforce_token": "12983918247912875AH"
}

The token_type will always be bearer for P4OAuth.
The access_token is a random string that should be put into the Authorization header of subsequent requests to P4OAuth or other Perforce services, like this:
```
Authorization: Bearer A129380-123124-2312314
```
The perforce_token can be used for that machine directly

Code Authorization Grant

The code authorization grant is intended for general web applications. The workflow involves a few redirects:

The user starts at the client application, or "resource owner"
The user is redirected to the P4OAuth server
- The P4OAuth server will likely present a login page for the user to sign in with their Perforce credentials
The user is redirected back to the client application
- At this point, the client application has received an "authorization code" that must be submitted back to the P4OAuth server
- When the client application posts the authorization code back, it receives the access token, and, a P4 token for the registered client application host

The access token is really all that the client application should maintain for the user. The client application can pass that access token around to other services using the bearer authorization header. Each other service will then use that token to retrieve the p4d token that has been provided for that host.

Authorization Start Request

Make a GET request to the authorization start URI:

https://p4oauth.example.com/grants/authorization_code?response_type=code&client_id=[LOGIN]&redirect_uri=[WHITELISTED URL]

Required options:

LOGIN should be the Perforce username.
WHITELISTED URL should be the exact URL registered in the whitelist for your client application

It's recommended that clients add a state parameter to ensure that redirects back to the handler are double-checked.