OAuth2 Support

Since Payara Server 4.1.2.182 and 5.182

The Payara API provides a @OAuth2AuthorisationMechanism annotation that creates an authorisation mechanism for OAuth2 support. This works in the same way as other authorisation mechanisms in the Java EE Security API.

Usage

The OAuth2 authentication mechanism is defined through the @OAuth2AuthorisationMechanism annotation. Specifying this in a valid place as defined by the Java EE Security API will create the mechanism. Often this may mean that any class is a valid position.

Example

Here’s an example that configures a Google OAuth2 endpoint:

@OAuth2AuthenticationDefinition(
    authEndpoint="https://accounts.google.com/o/oauth2/v2/auth",
    tokenEndpoint="https://www.googleapis.com/oauth2/v4/token",
    clientId="{my-key}.apps.googleusercontent.com",
    clientSecret="{my-secret}",
    redirectURI="https://localhost:8181/{my-application}/callback",
    scope="email",
    extraParameters = {
        "testKey=testValue",
        "testKey2=testValue2"
    }
)
public class SecurityBean {

}

Once the user is authenticated they will not have any roles defined, regardless of the OAuth scope. Roles should be specified using @DeclareRoles. See this sample project for a more detailed example.

When defining a OAuth2 flow within an application deployed on Payara Server it is possible to retrieve the access token within any bean in the scope of the callback/redirectURI resource used to configure the authentication:

@WebServlet("/callback")
public class CallbackServlet extends HttpServlet {

    @Inject
    OAuth2AccessToken token;

    @Override
    protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
        PrintWriter out = response.getWriter();
        //Here's the access token
        out.println(token.getAccessToken());
    }
}

OAuth2 authorization support require the use of HTTP/2, so make sure to use the appropriate HTTP network listener when preparing your application.

Configuration

The @OAuth2AuthenticationDefinition annotation has several configuration options.

They are detailed below.

Table 1. Configuration Options
Option	Required	Description	Requirements
`authEndpoint`	true	The URL for the OAuth2 provider to provide authentication.	The endpoint must be HTTPS.
`tokenEndpoint`	true	The URL for the OAuth2 provider to give the authorisation token.	The endpoint must be HTTPS.
`clientId`	true	The client identifier issued when the application was registered.	N/A.
`clientSecret`	true	The client secret for the registered application.	N/A.
`scope`	false	The scopes requested from the OAuth provider.	N/A.
`redirectURI`	false	The URL to redirect the user to upon successful authentication.	Must be equal to one set in the OAuth2 Authentication provider.
`extraParameters`	false	An array of extra options to be sent to the OAuth provider.	Must be in the form `"key=value"`.

Expression Language Support

Additionally, the @OAuth2AuthenticationDefinition supports the use of expression language (EL) notation for dynamic configuration scenarios. This means that you can use any CDI bean properties to set the OAuth2 configuration like this:

@OAuth2AuthenticationDefinition(
    authEndpoint="#{oauth2ConfigBean.authEndpointURL}",
    tokenEndpoint="#{oauth2ConfigBean.tokenEndpointURL}",
    clientId="#{oauth2ConfigBean.clientId}",
    clientSecret="#{oauth2ConfigBean.clientSecret}",
    redirectURI="#{oauth2ConfigBean.redirectURI}"
)
public class SecurityBean {
}

Client Secret Aliasing

The client secret can be input directly, or for added security it can be aliased using any of the following features:

Extra Resources

To read more about OAuth2 itself, visit https://oauth.net/2/