OAuth 2.0 SDK with OpenID Connect extensions

Download

This SDK is provided under the terms of the open source Apache 2.0 licence.

If you use Maven, you can obtain the dependency from the Central repo:

<dependency>
    <groupId>com.nimbusds</groupId>
    <artifactId>oauth2-oidc-sdk</artifactId>
    <version>3.4.1</version>
</dependency>

OpenID Connect authentication requests

OpenID Connect specifies an extended OAuth 2.0 authorisation endpoint where the application sends the user to authenticate and request access to selected personal details, such as name and email. The authentication response is transmitted by redirecting the browser back to the client with the authorisation code/ID token/access token encoded in a query/fragment string.

To compose an OpenID Connect authorisation request on the client side:

// The client identifier provisioned by the server
ClientID clientID = new Client("123");

// The client callback URL
URL callback = new URL("https://client.com/callback");

// Generate random state string for pairing the response to the request
State state = new State();

// Generate nonce
Nonce nonce = new Nonce();

// Compose the request (in code flow)
AuthenticationRequest req = new AuthenticationRequest(
    new URL("https://c2id.com/login"),
    new ResponseType(ResponseType.Value.CODE),
    Scope.parse("openid email profile address"),
    clientID,
    callback,
    state,
    nonce);

HTTPResponse httpResponse = req.toHTTPRequest().send();

AuthenticationResponse response = AuthenticationResponseParser.parse(httpResponse);

if (response instanceof AuthenticationErrorResponse) {
    // process error
}

AuthenticationSuccessResponse succesResponse = 
    (AuthenticationSuccessResponse)response;

// Retrieve the authorisation code
AuthorizationCode code = successResponse.getAuthorizationCode();

// Don't forget to check the state
assert successResponse.getState().equals(state);

Decoding the OpenID Connect authentication request on the server side:

// Get the query string
String query = "https://server.example.com/op/authorize?response_type=code&client_id=123...";

// Decode the query string
AuthenticationRequest req = AuthenticationRequest.parse(query);

// Extract the parameters

// Required to look up the client in the provider's database
ClientID clientID = req.getClientID();

// The client redirection URL, must be registered in the provider's database
URL redirectURI = req.getRedirectionURI();

// The response type (implies code flow)
ResponseType rt = req.getResponseType();

// The state, must be echoed back with the response
State state = req.getState();

// The requested scope
Scope scope = req.getScope();

// Other parameters....


// Process the request and generate a code
AuthorizationCode code = new AuthorizationCode();

// Create response
AuthenticationSuccessResponse(redirectURI, code, null, null, state);

// Output the response depending on your web server framework
// ...

OAuth 2.0 token request

TBD

OpenID Connect UserInfo requests

TBD