overview.md #2

title=Overview
date=2014-05-22
type=page
status=published
~~~~~~

P4OAuth Overview
================

#### Motivation; why create P4OAuth?

We've needed some kind of single sign-on (SSO) solution for some time now. There's been a couple of different workarounds that we'd like to avoid:

1. Instead of providing depot paths for the preview server, the Commons preview server takes the entire preview content. This is a complete workaround to SSO; just do all p4 operations on one server.

2. The p4search integration instead takes a p4 token bound to a host IP. Unfortunately this requires setting the IP Address that p4-search will use on the commons webserver. If we extend this to other services, Commons needs to know the **networking** configuration of all other services.

P4OAuth should simplify deployment and configuration issues. We aim to make it possible for one application to sign in to Perforce, and then pass a user token to other services that can operate as that user on Perforce as well, without requiring complex reconfiguration.

This is what OAuth 2.0 provides. After authenticating, each application will pass the user token around via the HTTP `Authorization` header, like this:

    Authorization: Bearer RsT5OjbzRn430zqMLgV3Ia

Under the current implementation, the other services will use this token to then retrieve a p4d token that's been registered just for that one host.

P4OAuth is not intended to be a general "OAuth" provider, it's really just intended to be the SSO protocol used for our internal services. This is enforced by use of a whitelist.


## Workflows ##

OAuth 2.0 allows several different kinds of workflows. We've currently only implemented one of them; the recommended "authorization code" workflow ideally used by web applications. The gist of this is

1. The client application redirects the users web page to request an "authorization code" from P4OAuth.

2. If the user needs to be signed in (which will probably always be the case), P4OAuth presents a login screen, and the user signs in to Perforce.

3. P4OAuth responds back to the client application with an authorization code.

4. The client application retrieves the access token by sending the authorization code back to P4OAuth.

We've added an additional steps from this point, when the application code goes around from one client to the next:

1. Client 1 sends the authorization token to Client 2.

2. Client 2 requests the p4d token for it's services on behalf of the user indicated in the auth token.

We may want to implement other workflows in the future. We can, for example, allow other applications to send in credentials into P4OAuth, to present their own login screen. Since we are using a whitelist underneath, this should not present major problems.


## Notable Requirements ##

The biggest requirement is TLS. Client applications and P4OAuth itself should only communicate via TLS. Ideally, a certificate that can actually be recognized by a trusted CA.

Additionally, we've required that all services that will use P4OAuth be registered via whitelist. This means that our implementation really is not intended to be thought of like OAuth implementations from Twitter, Google, etc. Which makes sense, since it's likely that there would be one (or more) P4OAuth instances per Perforce installation.


## The Whitelist ##

Each P4OAuth instance should come with it's own "whitelist" of approved services only. This is a list that indicates allowed Redirect URIs associated with the IP address of the machine we'll generate the Perforce token for.

This whitelist currently resides in a single file on the P4OAuth instance. In the future, it may be possible to provide secure service discovery and configuration to allow this to be determined more automatically. Those would be separate projects, however.