Introduction to OAuth2 AuthStates

Introduction

An OAuth2 AuthState is a collection of OAuth 2.0 client applications requiring end-user authentication and claims from an OAuth2 provider (as defined in RFC 6749. In this situation, the client relies on authorization information and claims issued by another entity. A common use case is to support login to a web application via an identity provider such as, for example, Facebook and GitHub.

In nevisAuth, this functionality is implemented with the following AuthState: OAuth2ClientState.

Designated usage of the OAuth2 AuthState(s) and integration with nevisProxy

The OAuth2 AuthState(s) implement the authorization code flow. You can use the OAuth2 AuthState(s) to implement the login to a Nevis-protected web application with an OAuth2 identity provider. This is what happens:

1. nevisProxy intercepts an unauthenticated request to the web application and requires authentication by nevisAuth.
2. The nevisAuth instance, which is configured with the OAuth2 AuthState(s), issues an authorization request to the OAuth2 identity provider via an HTTP redirect.
3. Subsequently, the OAuth2 identity provider requires the end user to authorize.
4. Upon successful completion of the authorization, the provider redirects the end user back to the client with an authorization code.
5. After receiving the authorization code, the OAuth2 AuthState redeems the code for an access token at the provider.
6. The OAuth2 AuthState asks for the user's information with another HTTP GET request, and propagates the user information in the session.
7. nevisAuth responds to nevisProxy with AUTH_DONE and a SecToken.
8. nevisProxy delegates the SecToken to the originally requested web application.

The following figure shows the described flow:

A note on the root certificate

The root certificate is used to prove the authenticity of the provider configuration and to verify the authenticity of the token and authorization endpoints.

If not present yet, add the root certificate to the truststore (-Djavax.net.ssl.trustStore) that is defined in the JAVA_OPTS configuration option in the env.conf file. See also the following sample code snippet:

keytool -import -keystore /var/opt/keybox/default/truststore.jks -file GeoTrustGlobalCA.pem