# OAuth Proxy

## What is it?

The OAuth proxy is a very straightforward HTTP server that proxifies API requests and helps with OAuth2 authentication. It is meant to simplify the workflow of authentication, refreshing tokens etc...
The Proxy will simply handle everything for you.

graph LR

C[Client]
P[OAuth Proxy]
API

C -- authenticated with base64 encoded token --> P
P -- decoded actual OAuth Access token --> API

## How it works

Check this sequence diagram out to understand how it works behind the scenes:

sequenceDiagram

Client->>OAuth Proxy: unauthenticated request
OAuth Proxy->>Client: sends 401 (unauthorized) with an `auth_url` that points to the Authentication URL in the body
Client->>OAuth API: redirects to said URL
OAuth API->>Client: redirects to the app's Redirect URI authorization code and state
Client->>OAuth Proxy: calls /callback with authorization code and state  in query
OAuth Proxy->>OAuth API: requests access token
OAuth API->>OAuth Proxy: returns access token
OAuth Proxy->>Client: returns access token (full body) encoded as base64 token
Client->>OAuth Proxy: authenticated request (with base64 token)
OAuth Proxy->>API: authenticated request (with decoded access token)
API->>OAuth Proxy: returns
OAuth Proxy->>Client: returns

## What you need to use it

First of all, you need to run the OAuth Proxy. If you already have that covered, the next thing you need is handling the callback.

When the proxy will `401 Unauthorized` your request you'll have to actually redirect to the page indicated by the 401 in the body. This page is the standard login/opt-in page for the OAuth2 standard.

This page will in turn redirect to the redirect URI you provided in the app setup. This URI **needs** to be a page of your client, that will then call the `/callback` endpoint on the proxy with `authorization_code` and `state` as query parameters.
This call will return a base64 encoded access token, it will look like this:

eyJhY2Nlc3NfdG9rZW4iOiJKajhPSUxFSTh1cFB4WlA1SlhUZ211UW1xU1oyN3pLZEpHdXYwc3JqUWRXSlZNbFZxWEJCeXBFeGM4eERRUhl3IiwidG9rZW5fdHlwZSI6IkJlYXJlciIsInJlZnJlc2hfdG9rZW4iOiJOSGo3SXFGOTlLYkRUSFBDT0RCNzZidEhsR1UwcWxPdEVQMW92aFdTTWdBRkJrNjBHMlY2U1hCR1liWEdoNXZSIiwiZXhwaXJ5IjoiMjAyMC0wMS0wM1QxNDowNzo0Mi44MjEzMDY2OTlaIn0=

Once you have the token, you just have to use it in your `Authorization` header like this:

Authorization: eyJhY2Nlc3NfdG9rZW4iOiJKajhPSUxFSTh1cFB4WlA1SlhUZ211UW1xU1oyN3pLZEpHdXYwc3JqUWRXSlZNbFZxWEJCeXBFeGM4eERRUhl3IiwidG9rZW5fdHlwZSI6IkJlYXJlciIsInJlZnJlc2hfdG9rZW4iOiJOSGo3SXFGOTlLYkRUSFBDT0RCNzZidEhsR1UwcWxPdEVQMW92aFdTTWdBRkJrNjBHMlY2U1hCR1liWEdoNXZSIiwiZXhwaXJ5IjoiMjAyMC0wMS0wM1QxNDowNzo0Mi44MjEzMDY2OTlaIn0=

The proxy will handle everything for you; from refreshing the token if it's expired, getting a new one.

It hides the application client and secret from your front-end app and makes it easier to get started with OAuth2 authentication.