OAuth2 is Done

class: center, middle

# OAuth2 is Done

Lee Johnson (LEEJO / leejo / lee@humanstate.com)

???
Is there anyone who thinks they've never encountered OAuth2?

---

class: center, middle

# leejo.github.io/code/

???
Slides available here

---
# OAuth2

.middle[.center[![Login With Buttons](img/bootstrap-social.png)]]

???
Not all services utilise OAuth2, for example twitter use OAuth1 (which we aren't covering here)
---
# "Done"?

### [Net::OAuth2::AuthorizationServer](https://metacpan.org/release/Net-OAuth2-AuthorizationServer)
--

- Implements all four OAuth2 grant flows
--

- Base module for use by framework plugins
--

- Although can be used "as is"
--

- Works "out of the box" with simple config
--

- But allows full overrides of all methods
--

- Used by a Mojolicious plugin, and a Dancer2 plugin
--

- Comprehensively tested
--

- Some refactoring and cleanup necessary (more so in the Dancer2 plugin)
???
The Dancer2 plugin was a fork of my Mojolicious plugin before I refactored the guts out into this module

- Code reviewed by at least one other person! (needs more eyeballs)

???
Thanks to Martin Renvoize for the code review

---
# The RFCs

- https://tools.ietf.org/html/rfc6749 - The OAuth 2.0 Authorization Framework, 76 pages

"MAY" x 29

"SHOULD" x 51
???
Full of ambiguities and inconsistencies, some grant types "MUST" ... while others "SHOULD" ...

Was designed by a committee

- https://tools.ietf.org/html/rfc6819 - OAuth 2.0 Threat Model and Security Considerations, 71 pages

???
Almost the same length!

--
- https://tools.ietf.org/html/rfc6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage, 18 pages

--
- https://tools.ietf.org/html/rfc7521 - Assertion Framework for OAuth 2.0, 20 pages

???
In which the committee decided the framework wasn't over engineered enough so they attempt to generalise OAuth2, leading to...

--
- https://tools.ietf.org/html/rfc7522 - Security Assertion Markup Language (SAML) 2.0 Profile for OAuth 2.0 Client Authentication and Authorization Grants, 15 pages
- https://tools.ietf.org/html/rfc7523 - JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants, 12 pages

???
These last three are currently proposed standards (2015)

---
# More RFCs

Yes, there are more:

https://tools.ietf.org/html/rfc7009 - OAuth 2.0 Token Revocation, 11 pages

https://tools.ietf.org/html/rfc7662 - OAuth 2.0 Token Introspection, 17 pages

These are also proposed standards.

We're up to 212 pages across 7 RFCs.

---
# The RFCs

https://tools.ietf.org/html/rfc6749#section-1.8

<b>1.8.  Interoperability</b>

OAuth 2.0 provides a rich authorization framework with well-defined
   security properties.  However, as a rich and highly extensible
   framework with many optional components, on its own, this
   specification is likely to produce a wide range of non-interoperable
   implementations.

???
This is from the main RFC and is worth highlighting

---
# The Flows

- Authorization Code Grant
--

- Implicit Grant
--

- Resource Owner Password Credentials Grant

--
- Client Credentials Grant

???
Il y a quatre, mais aussi ...

--
- Extension Grants

4.5.  Extension Grants

The client uses an extension grant type by specifying the grant type
   using an absolute URI (defined by the authorization server) as the
   value of the "grant_type" parameter of the token endpoint, and by
   adding any additional parameters necessary.

???
Extension Grants - The "Whatever" Grant

So, which one to use and how?

---
# Authorization Code Grant

- Very common
???
Comme nous avons vu : utilisé par Google, Facebook, et al
--

- Used by the "Login with" examples you will find on the web
???
Unless it's OAuth 1
--

- Generally for browser based clients (i.e. not "apps")

--
- The most secure flow

--
- Also the most complicated flow
???
Somewhat frustrating to implement
--

- But easier with framework plugins

--
- Security is through a whitelist of know clients + secrets

--
- Client identifies self through a background POST to get access\_token
???
Access token is thus not known to user

---
# Authorization Code Grant

<pre>
   +----------+
   | Resource |
   |   Owner  |
   +----------+
        ^
        |
   +----|-----+        Client Identifier     +---------------+
   |         -+--(A)-- & Redirection URI --->|               |
   |  User-   |                              | Authorization |
   |  Agent  -+--(B)-- User authenticates -->|     Server    |
   |          |                              |               |
   |         -+--(C)-- Authorization Code --<|               |
   +-|----|---+                              +---------------+
     |    |                                      ^      v
    (A)  (C)                                     |      |
     |    |                                      |      |
     ^    v                                      |      |
   +---------+                                   |      |
   |         |>-(D)-- Authorization Code --------'      |
   |  Client |        & Redirection URI                 |
   |         |                                          |
   |         |<-(E)----- Access Token ------------------'
   +---------+       (w/ Optional Refresh Token)
</pre>

???
Resource owner - c'est vous

Authorization Server - c'est Google/Facebook

Client - c'est le site web qui a dit "Login with Facebook"

---
# Authorization Code Grant

<pre>
   +----------+
   | Resource |
   |   Owner  |
   +----------+
        ^
        |
   +----|-----+
   |          |
   |  User-   |
   |  Agent   |
   |          |
   |          |
   +-|--------+
     |
    (A)
     |
     ^
   +---------+
   |         |
   |  Client |
   |         |
   |         |
   +---------+
</pre>

---
# Authorization Code Grant

---

# Authorization Code Grant

Example of Dancer2 configuration in the Authorization Server app:

```yml
plugins:
	"OAuth2::Server":
		jwt_secret: super_secret_jwt_secret
		clients:
			client_identifier:
				client_secret: super_secret_client_secret
				scopes:
					read_posts: 1
					post_to_wall: 0
```

Route In the app:

```perl
use Dancer2::Plugin::OAuth2::Server;
 
get '/protected' => oauth_scopes 'read_posts' => sub { ... }
```

???
The plugin creates a couple of routes in your app to allow the OAuth2 flow to function

---
# Authorization Code Grant

In the client:

```perl
my $ua  = ...
my $uri = URI->new( '/authorize' );
$uri->query_param( client_id     => 'client_identifier' );
$uri->query_param( redirect_uri  => 'http://localhost/callback' );
$uri->query_param( response_type => 'code' );
$uri->query_param( scope         => 'read_posts' );
```

???
Creating a request to get an authorization code (response_type => 'code')

```perl
# get an auth code
my $response = $ua->request( HTTP::Request->new( GET => $uri ) );
$uri = URI->new( $response->header('location') );
my $auth_code = $uri->query_param( 'code' );
```

???
What you don't see here is the user login/allow/deny part of the process on
the Authorization Server side - you need to implement that in your web framework

---
# Authorization Code Grant

```perl
# get the access token
$request = POST '/access_token', Content => [
	client_id     => 'client_identifier',
    client_secret => 'super_secret_client_secret',
    grant_type    => 'authorization_code',
    code          => $auth_code,
    redirect_uri  => 'http://localhost/callback'
];

my $access_token = from_json( $ua->request($request)->content )->{access_token};
```

???
Use the authorization code returned with client_id and client_secret to get an auth code

```perl
# call API with access token
$request = HTTP::Request->new( GET => '/protected' );
$request->header( Authorization => "Bearer $access_token");
my $response = $ua->request( $request );
...
```

---
# Implicit Grant

- Also very common
--

- Used by the "Login with" examples you will find on apps

--
- Generally for app (phone) based clients

--
- Reasonably secure

--
- Reasonably simple

--
- Security is through a whitelist of know clients + redirect URIs

--
- Access token sent back to pre-agreed redirect URI in fragment

--
- Access token can be known to user

???
vulnerable to MITM attacks?

---
# Implicit Grant

???

For some reason on this diagram they include the "Client Resource"

They didn't do that on the previous grant type, even though it also
uses a redirect URI. I guess because it looked complicated enough
already.

Really it looks something like... (next slide)

---
# Implicit Grant

---
# Implicit Grant

Example of Mojolicious configuration, again in the Authorization Server app:

```perl
$self->plugin( 'OAuth2::Server' => {
	jwt_secret => $jwt_secret
	clients    => {
		client_identifier => {
			redirect_uri => 'https://client/cb',
			scopes       => {
				 read_posts   => 1,
				 post_to_wall => 0,
			}
		}
	}
} );
```

???
Looks very similar to the previous example but this time we have a redirect_uri rather
than a client_secret

In the controller:

```perl
if ( my $oauth_details = $c->oauth( qw/required scopes/ ) ) {
	... # do something, user_id, client_id, etc, available in $oauth_details
} else {
	return $c->render( status => 401, text => 'Unauthorized' );
}
```

???
Note that qw/required scopes/ is only necessary for routes requiring specific scopes ("privileges") to access them

---
# Implicit Grant

Call server with client and redirect URL:

```sh
curl -v 'https://foo.com/oauth/authorize
	?client_id=client_identifier
	&redirect_uri=https://client/cb
	&response_type=token'
```

Access token sent back to redirect URL in query fragment:

```sh
Location: https://client/cb#access_token=ABCDEFG&...
```

Call the API:

```sh
curl -v -H"Authorization: Bearer ABCDEFG" 'https://foo.com/api/v1.0/me' | jq

{
  ...
}

```

???
Examples calling the Authorization Server on the command line here, because why not

This flow is a bit simpler so we can do that trivially here anyway

---
# Resource Owner Password Credentials Grant

- Uncommon
--

- In fact, discouraged unless a last resort
--

- Certainly don't use outside of private client/server systems
--

- And only use when there is high trust between client/server
--

---
# Resource Owner Password Credentials Grant

---
# Resource Owner Password Credentials Grant

Example of a simple script as a "server":

```perl
my $Server = Net::OAuth2::AuthorizationServer->new;
my $Grant  = $Server->password_grant(
	jwt_secret => 'weeeeee',
	clients => {
		bob => {
			client_secret => 'foo',
		},
	},
	users => {
		sue => 'letmein',
	}
);

```

???
In this case the command line would be the client, running script the server

It's problematic in that we have to give the client our password

Which sort of defeats the point of OAuth, although we can limit the scopes

Here you're seeing a bit more of the direct calls to the module, used by the previously mentioned plugins

---
# Resource Owner Password Credentials Grant

```perl
my ( $is_valid,$error,$scopes ) = $Grant->verify_user_password(
	client_id     => $opts->{'client-id'}     // '',
	client_secret => $opts->{'client-secret'} // '',
	username      => $opts->{'username'}      // '',
	password      => $opts->{'password'}      // '',
);

die $error if ! $is_valid;

say $Grant->token(
	client_id       => $opts->{'client-id'} // '',
	scopes          => undef,
	type            => 'access',
);
```

???
You can see it's possible to use the module itself outside of the various web frameworks - you do need to
be aware of the full flow, although these are documented in each module within the distribution

```sh
 > perl examples/password_credentials_grant.pl -c bob -s foo -u sue -p letmein
```

???
Passing the details from the "client" to the "server"

```sh
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOm51bGwsImNsaWVudCI6ImJvYiIsIm \
V4cCI6MTQ5NDY3NTczMSwiaWF0IjoxNDk0NjcyMTMxLCJqdGkiOiIyQUxUZzc2dENnbkl5SlJSc \
XJhTnRKUExNbk1JaEhwdiIsInNjb3BlcyI6bnVsbCwidHlwZSI6ImFjY2VzcyIsInVzZXJfaWQi \
Om51bGx9.L-dpho5QTNKtWkm2lQ76ljHufx2onBUJ_6MELs3mMMI
```

???
Gives us an Access Token

---
# Resource Owner Password Credentials Grant

```perl
if ( my $access_token = $opts->{'access-token'} ) {

my ( $is_valid,$error ) = $Grant->verify_access_token(
		access_token     => $access_token,
		is_refresh_token => 0,
	);

die $error if ! $is_valid;

say "Welcome";

}
```

???
The chunk of code that verifies the Access Token

This could be an entirely different script, process, etc, because the JWT is persistant

If you didn't use jwt\_secret it's more complicated, more on that in a minute
--

```sh
 > perl examples/password_credentials_grant.pl -a \
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOm51bGwsImNsaWVudCI6ImJvYiIsIm \
V4cCI6MTQ5NDY3NTczMSwiaWF0IjoxNDk0NjcyMTMxLCJqdGkiOiIyQUxUZzc2dENnbkl5SlJSc \
XJhTnRKUExNbk1JaEhwdiIsInNjb3BlcyI6bnVsbCwidHlwZSI6ImFjY2VzcyIsInVzZXJfaWQi \
Om51bGx9.L-dpho5QTNKtWkm2lQ76ljHufx2onBUJ_6MELs3mMMI
```

???
Pass the access token from the "client" to the "server"

```sh
Welcome
```

???
And we're in

---
# Client Credentials Grant

- Also uncommon
--

- Really only for internal and non public services
--

- For the most part, why would you even bother with this?

---
# Client Credentials Grant

---
# Client Credentials Grant

Example of a CGI.pm based script:

```perl
use strict;
use warnings;

use Net::OAuth2::AuthorizationServer;
use CGI;

my $Server = Net::OAuth2::AuthorizationServer->new;
my $Grant  = $Server->client_credentials_grant(
	jwt_secret => 'weeeeee',
	clients => {
		bob => {
			client_secret => 'foo',
		},
	}
);
```

???
Please don't use CGI.pm, just showing here that it is possible to use this with older style perl code

Or even in house bespoke frameworks
---
# Client Credentials Grant

```perl
my $query = CGI->new;

my $client_id     = $query->param( 'client-id' )     // '';
my $client_secret = $query->param( 'client-secret' ) // '';

my ( $is_valid,$error,$scopes ) = $Grant->verify_client(
	client_id     => $client_id,
	client_secret => $client_secret,
);

print $query->header('application/json');
print "\"$error\"" if ! $is_valid;
exit( 1 )          if ! $is_valid;

print '{ "access_token":"' . $Grant->token(
	client_id       => $client_id,
	scopes          => undef,
	type            => 'access',
) . '" }';
```

???
More of the direct calls to the module: verify the client, get a token

---
# Client Credentials Grant

```perl
if ( my $access_token = $query->param( 'access-token' ) ) {

my ( $is_valid,$error ) = $Grant->verify_access_token(
		access_token     => $access_token,
		is_refresh_token => 0,
	);

print $query->header;
	print $error if ! $is_valid;
	exit( 1 )    if ! $is_valid;

print "Welcome";

} else {
...
}
```

???
And then the Access Token verification section

---
# Client Credentials Grant

```sh
> curl http://127.0.0.1:3000/token -d "client-id=bob" -d "client-secret=foo"
```

???
Calling the Authorization Server CGI script with the params, note the client_secret
is in the clear here so as stated this should be private systems only

```sh
{ "access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOm51bGwsImNsa \
WVudCI6ImJvYiIsImV4cCI6MTQ5NDcxMTkwNSwiaWF0IjoxNDk0NzA4MzA1LCJqdGkiOiJ5UnRZe \
FA3enAyaFVtVXVnNHk2RzlSUm0xWURWV1FFViIsInNjb3BlcyI6bnVsbCwidHlwZSI6ImFjY2Vzc \
yIsInVzZXJfaWQiOm51bGx9.1aKd8YxIz1uVCaO4ZT-JHCJdjyh6RLm1V8A8tYP-hN8" }
```

???
Gives us an Access Token

```sh
> curl -v http://127.0.0.1:3000/token -d "access-token=eyJhbGciOiJIUzI1NiIs \
InR5cCI6IkpXVCJ9.eyJhdWQiOm51bGwsImNsaWVudCI6ImJvYiIsImV4cCI6MTQ5NDcxMTkwNS \
wiaWF0IjoxNDk0NzA4MzA1LCJqdGkiOiJ5UnRZeFA3enAyaFVtVXVnNHk2RzlSUm0xWURWV1FFV \
iIsInNjb3BlcyI6bnVsbCwidHlwZSI6ImFjY2VzcyIsInVzZXJfaWQiOm51bGx9.1aKd8YxIz1u \
VCaO4ZT-JHCJdjyh6RLm1V8A8tYP-hN8"
```

???
Which we can use

--
```sh
Welcome
```

---
# Overriding Defaults

???
If you want to be more bespoke, store tokens, etc, you can override defaults

```perl
my $store_access_token_sub = sub {
  my ( %args ) = @_;

my (
    $obj,$client,$auth_code,$access_token,$refresh_token,
    $expires_in,$scope,$old_refresh_token
  ) = @args{qw/
    mojo_controller client_id auth_code access_token
    refresh_token expires_in scopes old_refresh_token
  / };

...
};
```
???
For example if you want to store the access token somewhere...

Supply functions to override the particular part of the flow you need to

Be aware that different flows only have some parts of the available functions

And that you need to be more familiar with the specifics of each OAuth2 flow

--
```sh
confirm_by_resource_owner_cb
login_resource_owner_cb
verify_client_cb
store_auth_code_cb
verify_auth_code_cb
jwt_claims_cb
store_access_token_cb
verify_access_token_cb
verify_user_password_cb
```

???
Note there's a jwt_claims_cb for adding to the default claims in the JWT

---
# Questions?

Links:

Blog Posts/Web Stuff

- [OAuth, An Introduction](https://hueniverse.com/introduction-e10f43314db5)
- [OAuth 2.0 - The Good, The Bad & The Ugly](https://code.tutsplus.com/articles/oauth-20-the-good-the-bad-the-ugly--net-33216)
- [OAuth 2.0 - Looking Back and Moving On](https://vimeo.com/52882780)

CPAN

- [Net::OAuth::AuthorizationServer](https://metacpan.org/release/Net-OAuth2-AuthorizationServer)
- [Net::OAuth2::AuthorizationServer::Manual](https://metacpan.org/release/Net-OAuth2-AuthorizationServer-Manual)
- [Mojolicious::Plugin::OAuth2](https://metacpan.org/release/Mojolicious-Plugin-OAuth2)
- [Mojolicious::Plugin::OAuth2::Server](https://metacpan.org/release/Mojolicious-Plugin-OAuth2-Server)
- [Dancer2::Plugin::Auth::OAuth](https://metacpan.org/pod/Dancer2::Plugin::Auth::OAuth)
- [Dancer2::Plugin::OAuth2::Server](https://metacpan.org/pod/Dancer2::Plugin::OAuth2::Server)
- [CatalystX::OAuth2::Provider](https://metacpan.org/release/CatalystX-OAuth2-Provider)