OAuth2 Implementation

Description

Since version 11.5 PowerFolder Server supports OAuth2 authorization. With OAuth you're able to receive an access- and refresh token from the PowerFolder server to access protected resources (folders).

The following documentation shows the OAuth2 life cycle, how to provide your OAuth2 client-ID and client-secret to the PowerFolder server and how to receive an access- and refresh token.

Requirements server-side

Just set your OAuth2 client-ID and client-secret on the PF-Server with the API call mentioned below.

API call (admin login required):

<PF-SERVER-URL>/api/oauth?action=store&client_id=<CLIENT-ID>&client_secret=<CLIENT-SECRET>

Workflow client-side

Your OAuth2 has to sent an initial POST request to start OAuth2 authentication against the server:
```
<PF-SERVER-URL>/oauth/allow?state=<STATE>&response_type=code&redirect_uri=<CLIENT-HOST>/oauth&client_id=<CLIENT-ID>
```
Note: The state must be generated by your OAuth2 client. This can be any random alphanumeric string.
If an active user session is available the server will show the OAuth2 "Allow or Decline" page, if not the user has to enter his credentials after that the OAuth2 "Allow or Decline" will be displayed.
If the user clicks on "Allow" the server will send a GET request to the OAuth2 client with the following URI:
```
<OAUTH2-CLIENT>/<OAUTH2-ENDPOINT>/code=<AUTH-CODE>&state=<STATE-FROM-FIRST-STEP>
```
This state should now be validated by your OAuth2 client. After successful validation your client should respond with a POST request and a JSON body against the server:
```
{
"grant_type" : "authorization_code",
"code" : "<AUTH-CODE>",
"client_id" : "<CLIENT-ID>",
"client_secret" : "<CLIENT-SECRET>"
}
```
The state, client-ID and secret will be validated by the server. If these parameters could be validated successfully the server will responds with the final access-/refresh-tokens as JSON:
```
{
"access_token": "<ACCESS-TOKEN>",
"refresh_token": "<REFRESH-TOKEN>",
"expires_in": <EXPIRES-IN>
}
```

Receive access token with refresh token

With the refresh token you're able to fetch a new access token at any time. That means the refresh token has unlimited validity - please store your refresh token somewhere save!

The GET request for getting a new access token with the refresh token is:

<PF-SERVER-URL>/oauth?grant_type=refresh_token&client_id=<CLIENT-ID>&refresh_token=<REFRESH-TOKEN>

Theoretical workflow: OAuth2 life cycle

Testing your application

For testing purposes PowerFolder provides a shell script. Just replace your client-ID, client-Secret and server-URL inside the script and run it against your PowerFolder server. You can download the script here: