Page Comparison

...

• Authorization Code - For web applications, run on the server.  Also referred to as "Trusted Application"
• Implicit - For mobile or javascript applications, run on the client.  Also referred to as "Untrusted Application"
• Resource Owner Password Credentials - Used when the users password is stored in the application, useful for scheduled events like backup scripts or "canonical" apps.
• Client Credentials - For actions not invoked by a User or when user authentication is done by the Application and any required user details are passed to the backend in the payload.
• SAML2 Bearer Assertion - Allows the web application to pass along the assertion it received from the user signing into SSO.

Client Credentials are the simplest to implement and therefor therefore a good starting point.

...

Speaking about the OAuth flow it is important to clearly define some of the common terms. The terms used throughout this document are defined below.

Authorization Code - Trusted Application

...

1. The Client ID & Secret are compiled into the application. 
2. Users of the application are sent to the Authorization Server to provide their consent.  The Client ID and requested Scope are encoded in the url.
3. The Authorization Server returns a Authorization Grant to the Client.
4. The Client gives they the Authorization Grant and Client ID & Secret to the Authorization Server.
5. The Authorization Server returns a OAuth Token.
6. The Client invokes api on the Resource Server, passing along the OAuth Token.

...

This problem has been the subject of significant consideration and while not optimal the Fragment Identifier seems the best solution.

Possible Solution: One Time Tokens

It has been proposed that the Authorization Server could send back a One Time Token instead of the OAuth Token.  The Client would then make a GET request to the Authorization Server to exchange the One Time Token for a OAuth Token.  As the name indicates, the One Time Token would only be valid for one such exchange and have a much shorter TTL (~2min).

The Browser History Attack would be impossible, as the only time any token is placed in the browser history it is invalidated by that same call.

An alternative proposal is that One Time Tokens behave as normal OAuth Tokens but are only good for a single use (or a very small window ~30sec from first use).

Neither concept is not part of the OAuth spec and is not supported by WSO2's products.

WSO2 has expressed interest in such a feature (more likely the alternative version) but has not placed it on any road map.  WSO2's products are designed for extensibility so it is entirely possible to write a 3rd party Grant Type and API that would implement this feature.

Resource Owner Password Credentials - Thick Client / Script

With the Resource Owner Password Credentials grant type the Client submits it's own Client ID & Secret along with the Resource Owner's Username & Password.  The motivation for this grant type is "canonical" apps, for example the Facebook app on a mobile device might ask for the users Facebook password and use Resource Owner Password Credentials. 

Flow:

1. The Client requests and stores the Username & Password from the Resource Owner.  This can be done in advance of the other steps and persist over sessions.
2. The Client submits to the Authorization Server the Client ID & Secret along with the Username & Password.
3. The Authorization Server returns a OAuth Token.  There is now "consent" screen as the user has give all control to the Client by turning over their Password.
4. The Client invokes APIs on the Resource Server, passing along the OAuth Token.

Example:

Image Removed

Pros & Cons:

• Requires the user to turn over their Username & Password, which users should be very wary of doing.  Which is why this is usually restricted to "canonical" apps (e.g. the Facebook App -> Facebook API).
• App has responsibility of securely storing the Password.  The Password cannot be stored as a salted hash as is normally advised, because the request to the Authorization Server requires the original plain text (Base64 Encoded) Password.
• The User doesn't have the authenticate every time they use the app.
• The App can act on the users behalf without user input, for example the App can check for new messages in the background.

Client Credentials -  Client = Resource Owner

The Client Credentials grant type is designed for operations that the App is preforming on it own behalf.  This could be a backup script that isn't designed to run as a particular user or a webapp doing a background task that is related to the user currently invoking it.  This is the simplest of the grant types, but also provides the least information to the API Manager for access decisions and statistics.

...

PKCE

Proof Key of Code Exchange is a replacement for implicit grant type.  It's the same as Implicit Grant with the change that the OAuth Token is retrieved via a separate direct call where the token is stored in the body and thus encrypted by SSL.

Before sending the user off to authenticate the Client generates a random value, it then sends a hash of the value off with the user when they are sent to authenticate.  At the end of the process the Client sends the unhashed random value to the Authorization Server, which then verifies that this value hashes to the hash previously presented.  This proves to the Authorization Server that the Client asking for the token is the same one that sent the user in for authorization.

Flow:

1. The Client generates a random value (CodeVerifier) and then hashes it (CodeChallenge).
2. Users of the application are sent to the Authorization Server to provide their consent.  The ClientId and CodeChallenge are sent with the request.
3. The User authenticates with the Authorization Server.
4. The Authorization Server redirects the browser to the Client's callback URL with a randomly generated Authorization Code.  It stores this authorization event associated with the Authorization Code.
5. The Client extracts the Authorization Code from the browsers url.
6. The Client sends the Authorization Code, ClientId and CodeVerifier to the Authorization Server.
7. The Authorization Server looks up the authorization event attached to the Authorization Code. It then hashes the CodeVerifier and checks that it matches the CodeVerifier.  It returns a OAuth Token in the payload.
8. The Client invokes APIs on the Resource Server, passing along the OAuth Token.

Example:

Image Added

Pros & Cons

• This process allows authenticating the user even when the Client can't be trusted to protect the Client Secret.
• The API can not trust the application, as the code may have been modified by the User. 

Resource Owner Password Credentials - Thick Client / Script

With the Resource Owner Password Credentials grant type the Client submits it's own Client ID & Secret along with the Resource Owner's Username & Password.  The motivation for this grant type is "canonical" apps, for example the Facebook app on a mobile device might ask for the users Facebook password and use Resource Owner Password Credentials. 

Flow:

1. The Client requests and stores the Username & Password from the Resource Owner.  This can be done in advance of the other steps and persist over sessions.
2. The Client submits to the Authorization Server the Client ID & Secret along with the Username & Password.
3. The Authorization Server returns a OAuth Token.  There is now "consent" screen as the user has give all control to the Client by turning over their Password.
4. The Client invokes APIs on the Resource Server, passing along the OAuth Token.

Example:

Image Added

Pros & Cons:

• Requires the user to turn over their Username & Password, which users should be very wary of doing.  Which is why this is usually restricted to "canonical" apps (e.g. the Facebook App -> Facebook API).
• App has responsibility of securely storing the Password.  The Password cannot be stored as a salted hash as is normally advised, because the request to the Authorization Server requires the original plain text (Base64 Encoded) Password.
• The User doesn't have the authenticate every time they use the app.
• The App can act on the users behalf without user input, for example the App can check for new messages in the background.

Client Credentials

The Client Credentials grant type was designed for operations that the App is performing on it own behalf.  This could be a backup script that isn't designed to run as a particular user or a webapp doing a background task that is not related to the user currently invoking it.  This is the simplest of the grant types, but also provides the least information to the API Manager for access decisions and statistics.

Because the APIM will not know what user is driving the operation it can not pass this information onto the Backend.

Flow:

1. Client requests a token from the Authorization Server, including the Client ID & Secret.
2. The Authorization Server returns an OAuth Token.
3. The Client invokes APIs on the Resource Server, passing along the OAuth Token.

Example:

Pros & Cons:

• Simple.
• No need for "fake" users or service accounts.
• API Manager can not consider User when determining permissions (if there is one).
• API Manager cannot log which User was involved (if there is one)

...

When a web app sends the user to SSO for authentication, the SSO server returns a signed SAML Assertion.  This assertion includes the known data about the current user, such as username.  If the Authorization Server also trusts the SSO Server, then that signed SAML Assertion can be exchanged for a OAuth Token.  

Flow:

1. Client sends user to SSO for authentication.
2. The user authenticates with the SSO server, usually with a username/password.
3. The SSO returns an assertion to the Client, proving that the current user has authenticated.
4. The Client requests an OAuth Token from the Authorization Server, including the SAML Assertion.
5. The Authorization Server verifies the assertion was signed by a trusted IDP and returns an OAuth Token.

...

title SAML2 Bearer Assertion
participant A4
participant Mary
participant MyTime
participant Auth Server
Mary->MyTime: Access MyTime
MyTime->Mary: Redirect to A4
Mary->A4: Authenticate
note over Mary, A4: Authenticate
A4->Mary: SAML Assertion
Mary->MyTime: Access MyTime (SAML Assertion)
MyTime->MyTime: Process Assertion, \nextract user data.
MyTime->Auth Server: Request OAuth Toke (SAMl Assertion)
Auth Server->Auth Server: Verify Signed by trusted IDP
Auth Server->MyTime: OAuth Token
MyTime->Leave Balances API: get user's vacation time (OAuth Token)

...