Diagram proxy oauth authentication sequence

[brylie]

Context

We have a task to research OAuth2 authentication. We are coordinating with the upstream project and downstream stakeholders to make sure we understand what is involved with OAuth2 authentication and how it involves the Proxy.

Rationale

Users often need to authenticate when making API requests. By design, our Proxy layer is managing user authentication, by using API keys. However, API keys are deemed undesirable, and may be insecure.

OAuth2 is an alternative authentication mechanism that might prove to be more secure than, or at least a good option in comparison to, API keys.

Task

Create one or more sequence diagrams showing user authentication:

• API key directly to an API
• API key managed by a proxy layer
• OAuth2 directly to an API
• Oauth2 managed by a proxy layer

Deliverables

The outcome of this task should be to produce one or more sequence diagrams in SVG, and/or PNG format. The diagrams should be easy to modify and share, so we would like them to be generated from plain text.

The text and accompanying image(s) should be added to our documentation repository:

• /develop/Architecture/proxy-oauth-authentication.sequence
• /develop/Architecture/proxy-oauth-authentication.svg

Examples

The following examples are to serve as a starting point:

Client->Proxy: Authenticate
Note right of Proxy: Generate session token
Proxy->Client: Return session token
Client->Proxy: Backend request (authenticated)
Note right of Proxy: Process request
Proxy-->Backend: Send request
Backend-->Proxy: Send response
Note right of Proxy: Process response
Proxy->Client: Send processed response

Resources

There is an online sequence diagram generator that takes structured text as input and outputs SVG.

[brylie]

Ping @bajiat @shaliko

[shaliko]

@brylie A little bit updated your diagram, just replaced "session token" to "access token" and renamed first step to "Authorization".

Title: When Proxy is OAuth provider
Client->Proxy: (1) Authorization
Note right of Proxy: Generate access token
Proxy->Client: (2) Return access token
Client->Proxy: (3) Backend request (Authenticated: with access token)
Note right of Proxy: Process request
Proxy-->Backend: (4) Send request
Backend-->Proxy: (5) Send response
Note right of Proxy: Process response
Proxy->Client: (6) Send processed response

Pros:

• Backend API no need care about Authorization/Authentication.
• The same client account can be used for Authorization/Authentication for any number of backends on one proxy installation.
• Easy count requests and other stats per client. Even if access_token will expire or be revoked, Proxy can easy continue count stats per client.

Cons:

• Backend will not know any details about client. It will get only access_token that can be expired or be revoked any time. So identification and count stats on backend side will not be reliable. For fix this problem will require send persisted client ID from proxy in each request with access_token.

[brylie]

In our setup, the Proxy (e.g. API Umbrella) is responsible for things like analytics. That way, the API behind the Proxy can be very simple.

In other words, the proxy is responsible for:

• authentication
• access control
• rate limiting
• load balancing
• analytics