== The OAuth2 auth provider

This component contains an out of the box OAuth2 implementation.

To use this project, add the following
dependency to the _dependencies_ section of your build descriptor:

* Maven (in your `pom.xml`):

[source,xml,subs="+attributes"]
----
<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-auth-oauth2</artifactId>
  <version>3.4.1</version>
</dependency>
----

* Gradle (in your `build.gradle` file):

[source,groovy,subs="+attributes"]
----
compile 'io.vertx:vertx-auth-oauth2:3.4.1'
----

OAuth2 lets users grant the access to the desired resources to third party applications, giving them the possibility
to enable and disable those accesses whenever they want.

Vert.x OAuth2 supports the following flows.

* Authorization Code Flow (for apps with servers that can store persistent information).
* Password Credentials Flow (when previous flow can't be used or during development).
* Client Credentials Flow (the client can request an access token using only its client credentials)

=== Authorization Code Flow

The authorization code grant type is used to obtain both access tokens and refresh tokens and is optimized for
confidential clients. As a redirection-based flow, the client must be capable of interacting with the resource
owner's user-agent (typically a web browser) and capable of receiving incoming requests (via redirection) from the
authorization server.

For more details see http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.1[Oauth2 specification, section 4.1].

=== Password Credentials Flow

The resource owner password credentials grant type is suitable in cases where the resource owner has a trust
relationship with the client, such as the device operating system or a highly privileged application. The
authorization server should take special care when enabling this grant type, and only allow it when other flows are
not viable.

The grant type is suitable for clients capable of obtaining the resource owner's credentials (username and password,
typically using an interactive form).  It is also used to migrate existing clients using direct authentication
schemes such as HTTP Basic or Digest authentication to OAuth by converting the stored credentials to an access token.

For more details see http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.3[Oauth2 specification, section 4.3].

=== Client Credentials Flow

The client can request an access token using only its client credentials (or other supported means of authentication)
when the client is requesting access to the protected resources under its control, or those of another resource owner
that have been previously arranged with the authorization server (the method of which is beyond the scope of this
specification).

The client credentials grant type MUST only be used by confidential clients.

For more details see http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-4.4[Oauth2 specification, section 4.4].

=== Extensions

The provider supports RFC7523 an extension to allow server to server authorization based on JWT.

=== Getting Started

An example on how to use this provider and authenticate with GitHub can be implemented as:

[source,java]
----
OAuth2Auth oauth2 = OAuth2Auth.create(vertx, OAuth2FlowType.AUTH_CODE, new OAuth2ClientOptions()
        .setClientID("YOUR_CLIENT_ID")
        .setClientSecret("YOUR_CLIENT_SECRET")
        .setSite("https://github.com/login")
        .setTokenPath("/oauth/access_token")
        .setAuthorizationPath("/oauth/authorize")
);

// when there is a need to access a protected resource or call a protected method,
// call the authZ url for a challenge

String authorization_uri = oauth2.authorizeURL(new JsonObject()
    .put("redirect_uri", "http://localhost:8080/callback")
    .put("scope", "notifications")
    .put("state", "3(#0/!~"));

// when working with web application use the above string as a redirect url

// in this case GitHub will call you back in the callback uri one should now complete the handshake as:


String code = "xxxxxxxxxxxxxxxxxxxxxxxx"; // the code is provided as a url parameter by github callback call

oauth2.getToken(new JsonObject().put("code", code).put("redirect_uri", "http://localhost:8080/callback"), res -> {
  if (res.failed()) {
    // error, the code provided is not valid
  } else {
    // save the token and continue...
  }
});
----

==== Authorization Code flow

The Authorization Code flow is made up from two parts. At first your application asks to the user the permission to
access their data. If the user approves the OAuth2 server sends to the client an authorization code. In the second
part, the client POST the authorization code along with its client secret to the authority server in order to get the
access token.

[source,java]
----
OAuth2ClientOptions credentials = new OAuth2ClientOptions()
    .setClientID("<client-id>")
    .setClientSecret("<client-secret>")
    .setSite("https://api.oauth.com");


// Initialize the OAuth2 Library
OAuth2Auth oauth2 = OAuth2Auth.create(vertx, OAuth2FlowType.AUTH_CODE, credentials);

// Authorization oauth2 URI
String authorization_uri = oauth2.authorizeURL(new JsonObject()
    .put("redirect_uri", "http://localhost:8080/callback")
    .put("scope", "<scope>")
    .put("state", "<state>"));

// Redirect example using Vert.x
response.putHeader("Location", authorization_uri)
    .setStatusCode(302)
    .end();

JsonObject tokenConfig = new JsonObject()
    .put("code", "<code>")
    .put("redirect_uri", "http://localhost:3000/callback");

// Callbacks
// Save the access token
oauth2.getToken(tokenConfig, res -> {
  if (res.failed()) {
    System.err.println("Access Token Error: " + res.cause().getMessage());
  } else {
    // Get the access token object (the authorization code is given from the previous step).
    AccessToken token = res.result();
  }
});
----

==== Password Credentials Flow

This flow is suitable when the resource owner has a trust relationship with the client, such as its computer
operating system or a highly privileged application. Use this flow only when other flows are not viable or when you
need a fast way to test your application.

[source,java]
----
OAuth2Auth oauth2 = OAuth2Auth.create(vertx, OAuth2FlowType.PASSWORD);

JsonObject tokenConfig = new JsonObject()
    .put("username", "username")
    .put("password", "password");

// Callbacks
// Save the access token
oauth2.getToken(tokenConfig, res -> {
  if (res.failed()) {
    System.err.println("Access Token Error: " + res.cause().getMessage());
  } else {
    // Get the access token object (the authorization code is given from the previous step).
    AccessToken token = res.result();

    oauth2.api(HttpMethod.GET, "/users", new JsonObject().put("access_token", token.principal().getString("access_token")), res2 -> {
      // the user object should be returned here...
    });
  }
});
----

==== Client Credentials Flow

This flow is suitable when client is requesting access to the protected resources under its control.

[source,java]
----
OAuth2ClientOptions credentials = new OAuth2ClientOptions()
    .setClientID("<client-id>")
    .setClientSecret("<client-secret>")
    .setSite("https://api.oauth.com");


// Initialize the OAuth2 Library
OAuth2Auth oauth2 = OAuth2Auth.create(vertx, OAuth2FlowType.CLIENT, credentials);

JsonObject tokenConfig = new JsonObject();

// Callbacks
// Save the access token
oauth2.getToken(tokenConfig, res -> {
  if (res.failed()) {
    System.err.println("Access Token Error: " + res.cause().getMessage());
  } else {
    // Get the access token object (the authorization code is given from the previous step).
    AccessToken token = res.result();
  }
});
----

=== AccessToken object

When a token expires we need to refresh it. OAuth2 offers the AccessToken class that add a couple of useful methods
to refresh the access token when it is expired.

[source,java]
----
if (token.expired()) {
  // Callbacks
  token.refresh(res -> {
    if (res.succeeded()) {
      // success
    } else {
      // error handling...
    }
  });
}
----

When you've done with the token or you want to log out, you can revoke the access token and refresh token.

[source,java]
----
token.revoke("access_token", res -> {
  // Session ended. But the refresh_token is still valid.

  // Revoke the refresh_token
  token.revoke("refresh_token", res1 -> {
    System.out.println("token revoked.");
  });
});
----

=== Example configuration for common OAuth2 providers

For convenience there are several helpers to assist your with your configuration. Currently we provide:

* Azure Active Directory `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/AzureADAuth.html[AzureADAuth]`
* Box.com `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/BoxAuth.html[BoxAuth]`
* Dropbox `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/DropboxAuth.html[DropboxAuth]`
* Facebook `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/FacebookAuth.html[FacebookAuth]`
* Foursquare `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/FoursquareAuth.html[FoursquareAuth]`
* Github `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/GithubAuth.html[GithubAuth]`
* Google `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/GoogleAuth.html[GoogleAuth]`
* Instagram `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/InstagramAuth.html[InstagramAuth]`
* Keycloak `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/KeycloakAuth.html[KeycloakAuth]`
* LinkedIn `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/LinkedInAuth.html[LinkedInAuth]`
* Mailchimp `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/MailchimpAuth.html[MailchimpAuth]`
* Salesforce `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/SalesforceAuth.html[SalesforceAuth]`
* Shopify `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/ShopifyAuth.html[ShopifyAuth]`
* Soundcloud `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/SoundcloudAuth.html[SoundcloudAuth]`
* Stripe `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/StripeAuth.html[StripeAuth]`
* Twitter `link:../../apidocs/io/vertx/ext/auth/oauth2/providers/TwitterAuth.html[TwitterAuth]`

==== JBoss Keycloak

When using this Keycloak the provider has knowledge on how to parse access tokens and extract grants from inside.
This information is quite valuable since it allows to do authorization at the API level, for example:

[source,java]
----
JsonObject keycloakJson = new JsonObject()
    .put("realm", "master")
    .put("realm-public-key", "MIIBIjANBgkqhk...wIDAQAB")
    .put("auth-server-url", "http://localhost:9000/auth")
    .put("ssl-required", "external")
    .put("resource", "frontend")
    .put("credentials", new JsonObject()
        .put("secret", "2fbf5e18-b923-4a83-9657-b4ebd5317f60"));

// Initialize the OAuth2 Library
OAuth2Auth oauth2 = KeycloakAuth.create(vertx, OAuth2FlowType.PASSWORD, keycloakJson);

// first get a token (authenticate)
oauth2.getToken(new JsonObject().put("username", "user").put("password", "secret"), res -> {
  if (res.failed()) {
    // error handling...
  } else {
    AccessToken token = res.result();

    // now check for permissions
    token.isAuthorised("account:manage-account", r -> {
      if (r.result()) {
        // this user is authorized to manage its account
      }
    });
  }
});
----

We also provide a helper class for Keycloak so that we can we can easily retrieve decoded token and some necessary
data (e.g. `preferred_username`) from the Keycloak principal. For example:

[source,java]
----
JsonObject idToken = KeycloakHelper.idToken(principal);

// you can also retrieve some properties directly from the Keycloak principal
// e.g. `preferred_username`
String username = KeycloakHelper.preferredUsername(principal);
----

==== Google Server to Server

The provider also supports Server to Server or the RFC7523 extension. This is a feature present on Google with their
service account.

=== Token Introspection

Tokens can be introspected in order to assert that they are still valid. Although there is RFC7660 for this purpose
not many providers implement it. Instead there are variations also known as `TokenInfo` end points. The OAuth2
provider will accept both end points as a configuration. Currently we are known to work with `Google` and `Keycloak`.

Token introspection assumes that tokens are opaque, so they need to be validated on the provider server. Every time a
token is validated it requires a round trip to the provider. Introspection can be performed at the OAuth2 level or at
the User level:

[source,java]
----
oauth2.introspectToken("opaque string", res -> {
  if (res.succeeded()) {
    // token is valid!
    AccessToken accessToken = res.result();
  }
});

// User level
token.introspect(res -> {
  if (res.succeeded()) {
    // Token is valid!
  }
});
----

=== Verifying JWT tokens

We've just covered how to introspect a token however when dealing with JWT tokens one can reduce the amount of trips
to the provider server thus enhancing your overall response times. In this case tokens will be verified using the
JWT protocol at your application side only. Verifying JWT tokens is cheaper and offers better performance, however
due to the stateless nature of JWTs it is not possible to know if a user is logged out and a token is invalid. For
this specific case one needs to use the token introspection if the provider supports it.

[source,java]
----
oauth2.decodeToken("jwt-token", res -> {
  if (res.succeeded()) {
    // token is valid!
    AccessToken accessToken = res.result();
  }
});
----