Micronaut Security is a fully featured and customizable security solution for your applications.

Micronaut Security 1.2.4.BUILD-SNAPSHOT includes the following changes:

To authenticate users you must provide implementations of AuthenticationProvider.

The following code snippet illustrates a naive implementation:

The built-in Login Controller uses every available authentication provider. Authentication strategies, such as basic auth, where the credentials are present in the request use the available authentication providers too.

Micronaut ships with DelegatingAuthenticationProvider which can be typically used in environments such as the one described in the following diagram.

DelegatingAuthenticationProvider is not enabled unless you provide implementations for UserFetcher, PasswordEncoder and AuthoritiesFetcher

The decision to allow access to a particular endpoint to anonymous or authenticated users is determined by a collection of Security Rules. Micronaut ships with several built-in security rules. If they don’t fulfil your needs, you can implement your own SecurityRule.

When you turn on security, traffic coming from any ip address is allowed by default.

You can however reject traffic not coming from a white list of IP Patterns as illustrated below:

In the previous code, the IpPatternsRule rejects traffic not coming either 127.0.0.1 or 192.168.1.* range.

As illustrated below, you can use Secured annotation to configure access at Controller or Controller’s Action level.

Alternatively, you could use JSR_250 annotations (javax.annotation.security.PermitAll, javax.annotation.security.RolesAllowed, javax.annotation.security.DenyAll):

Moreover, you can configure endpoint authentication and authorization access with an Intercept URL Map:

As you see in the previous code listing, any endpoint is identified by a combination of pattern and an optional HTTP method.

If a given request URI matches more than one intercept url map, the one that specifies an http method that matches the request method will be used. If there are multiple mappings that do not specify a method and match the request URI, then the first mapping will be used. For example:

The example below defines that all HTTP requests to URIs matching the pattern /v1/myResource/** and using HTTP method GET will be accessible to everyone. Requests matching the same URI pattern but using a different HTTP method than GET require fully authenticated access.

When you turn on security, Built-in endpoints are secured depending on their sensitive value.

Out-of-the-box, Micronaut supports RFC7617 which defines the "Basic" Hypertext Transfer Protocol (HTTP) authentication scheme, which transmits credentials as user-id/password pairs, encoded using Base64.

Once you enable Micronaut security, Basic Auth is enabled by default.

The following sequence illustrates the authentication flow:

Below is a sample of a cURL command using basic auth:

After credentials are read from the HTTP Header, they are feed into an Authenticator which attempts to validate them.

The code snippet below illustrates how to send credentials using the basicAuth method from MutableHttpRequest method:

The following configuration properties are available to customize basic authentication behaviour:

Micronaut supports Session based authentication.

To use the Micronaut’s session based authentication capabilities you must have the security-session dependency on your classpath. For example in build.gradle:

The following sequence illustrates the authentication flow:

The following configuration properties are available to customize session based authentication behaviour:

The following configuration properties are available to customize token based authentication:

Micronaut ships with security capabilities based on Json Web Token (JWT). JWT is an IETF standard which defines a secure way to encapsulate arbitrary data that can be sent over unsecure URL’s.

To use the Micronaut’s JWT based authentication capabilities you must have the security-jwt dependency on your classpath. For example in build.gradle:

The following configuration properties are available to customize JWT based authentication behaviour:

Micronaut supports the RFC 6750 Bearer Token specification for transmitting JWT tokens. The following sequence illustrates the RFC 6750 authentication flow:

The following configuration properties are available to customize how the Bearer Token will be read:

You can send/read a JWT token from a Cookie too.

The following sequence illustrates the authentication flow:

Reading tokens from Cookies is disabled by default. Note that using JWT tokens from cookies requires JWT Authentication to be enabled.

Micronaut relies on Nimbus JOSE + JWT library to provide JWT token signature and encryption.

The following configuration options are available:

Micronaut security capabilities use signed JWT’s as specified by the JSON Web Signature specification.

To enable a JWT signature in token generation, you need to have in your app a bean of type RSASignatureGeneratorConfiguration, ECSignatureGeneratorConfiguration, SecretSignatureConfiguration qualified with name generator.

To verify signed JWT tokens, you need to have in your app a bean of type RSASignatureConfiguration, RSASignatureGeneratorConfiguration, ECSignatureGeneratorConfiguration, ECSignatureConfiguration, or SecretSignature.

You can setup a SecretSignatureConfiguration named generator easily via configuration properties:

You can supply the secret with Base64 encoding.

Signed claims prevents an attacker to tamper its contents to introduce malicious data or try a privilege escalation by adding more roles. However, the claims can be decoded just by using Base 64.

If the claims contains sensitive information, you can use a JSON Web Encryption algorithm to prevent them to be decoded.

To enable a JWT encryption in token generation, you need to have in your app a bean of type RSAEncryptionConfiguration, ECEncryptionConfiguration, SecretEncryptionConfiguration qualified with name generator.

Micronaut’s JWT validation support multiple Signature and Encryption configurations.

Any beans of type RSASignatureConfiguration, ECSignatureConfiguration, SecretSignatureConfiguration participate as signature configurations in the JWT validation.

Any beans of type RSAEncryptionConfiguration, ECEncryptionConfiguration, SecretEncryptionConfiguration participate as encryption configurations in the JWT validation.

A JSON Web Key (JWK) is a JSON object that represents a cryptographic key. You can use a remote JWK Set, A JSON object that represents a set of JWKs, to validate JWT signatures.

You can configure a remote JWKS as a signature validator:

The previous snippet creates a JwksSignature bean with a awscognito name qualifier.

If you want to expose your own JWK Set, read the Keys Controller section.

If the built-in JWTClaimsSetGenerator, does not fulfil your needs you can provide your own replacement of ClaimsGenerator.

For example, if you want to add the email address of the user to the JWT Claims you could create a class which extends UserDetails:

Configure your AuthenticationProvider to respond such a class:

And then replace JWTClaimsSetGenerator with a bean that overrides the method populateWithUserDetails:

When you use JWT authentication and the built-in LoginController, the JWT tokens are returned to the client as part of an OAuth 2.0 RFC6749 access token response.

An example of such a response is:

If you wish to customize the previous JSON payload, you may want to provide a bean replacement for BearerTokenRenderer. If that is not enough, check the AccessRefreshTokenLoginHandler to accommodate it to your needs.

Micronaut supports authentication with LDAP out of the box. To get started, add the security-ldap dependency to your application.

The LDAP authentication in Micronaut supports configuration of one or more LDAP servers to authenticate with. Each server has it’s own settings and can be enabled or disabled.

This section will outline some common requirements that will require custom code to implement and describe what to do in those cases.

Micronaut allows the customization of the response that is sent when a request is not authorized to access a resource, or is not authenticated and the resource requires authentication.

To control this response, it is necessary to register a RejectionHandler and ensure your bean replaces the default implementation.

If both beans (UnauthorizedRejectionUriProvider, ForbiddenRejectionUriProvider) exists, then RedirectRejectionHandler, a generic redirect handler, is registered as a RejectionHandler.

You can create your own RejectionHandler. You will need to replace the current RejectionHandler.

For those using JWT based security, replace HttpStatusCodeRejectionHandler.

For example:

For those using session based security, replace SessionSecurityfilterRejectionHandler.

Imagine you have a Gateway microservice which consumes three other microservices:

If the incoming request localhost:8080/api/books contains a valid JWT token, you may want to propagate that token to other requests in your network.

You can configure token propagation to achieve that.

The previous configuration, configures a HttpHeaderTokenWriter and a and a propagation filter, TokenPropagationHttpClientFilter, which will propagate the security token seamlessly.

If you use Service Discovery features, you can use the service id in your service id regular expression:

You can enable LoginController with configuration property:

The response of the Login Endpoint is handled by a bean instance of LoginHandler.

You can enable the logout endpoint with configuration:

The behavior of the controller is delegated to a LogoutHandler implementation. There are default implementations provided for JWT Cookie and Session based authentication storage.

By default, issued access tokens expire after a period of time, and they are paired with refresh tokens. To ease the refresh, you can enable OauthController, with configuration property:

The controller exposes an endpoint as defined by section 6 of the OAuth 2.0 spec - Refreshing an Access Token.

By default, issued Refresh tokens never expire, and can be used to obtain a new access token by sending a POST request to the /oauth/access_token endpoint:

As you can see, is a form request with 2 parameters:

grant_type: must be refresh_token always.

refresh_token: the refresh token obtained previously.

A JSON Web Key (JWK) is a JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.

Meanwhile, a JWK Set is a JSON object that represents a set of JWKs. The JSON object MUST have a "keys" member, which is an array of JWKs.

You can enable the KeysController to expose an endpoint which returns a JWK Set. You can configure it with:

Moreover, you will need to provide beans to type JwkProvider.

Often you may want to retrieve the authenticated user.

You can bind java.security.Principal as a method’s parameter in a controller.

If you need a greater level of detail, you can bind Authentication as a method’s parameter in a controller.

If you need to access the currently authenticated user outside of a controller, you can inject SecurityService bean, which provides a set of convenient methods related to authentication and authorization.

Micronaut security classes generate several ApplicationEvents which you can subscribe to.

To learn how to listen for events, see the Context Events section of the documentation.

Micronaut supports authentication with OAuth 2.0 servers, including support for the OpenID standard.

The easiest way to get started is by configuring a provider that supports OpenID. Platforms such as Okta, Auth0, AWS Cognito, Keycloak, and Google are common examples.

Once you create an application client with a provider, you will get a client id and a client secret. The client id and secret combined with the issuer URL is all that is needed to enable the authentication code grant flow with an OpenID provider.

For example, to configure Google as a provider:

For normal OAuth 2.0, different steps are required to allow for the authorization code grant flow.

For the full authorization code flow to work there are also some additional requirements. A RedirectingLoginHandler must be in the context to determine how to respond after a failed or successful login. A custom implementation can of course be provided, however the following options are available out of the box.

To use the BUILD-SNAPSHOT version of this library, check the documentation to use snapshots.

Code can be found at the micronaut-security repository.

If you are new to OpenID Connect, we recommend watching OAuth 2.0 and OpenID Connect to get a better understanding.

The authorization code grant flow is the most typical authentication flow with OAuth 2.0 and OpenID providers. The same main steps apply to the flow whether or not the provider supports OpenID, and is described in RFC6749 - Authorization Code Grant.

The OAuth 2.0 authorization code flow requires a callback endpoint. In addition, a login endpoint is available to trigger the flow. The URIs are configurable.

The URI templates for login and callback have a template variable in them {provider}. That variable is used by the route builder to build routes for each provider that is configured. The name provider is special in this context and cannot be changed. The URI may be manipulated however in any way as long as the provider variable is part of the path of the URI.

For example /oauth/login{?provider} is not a valid configuration because Micronaut does not consider the query segment of a URL when routing requests. The provider variable must be part of the path.

It’s possible to configure authorization with an OpenID provider simply with this library because OpenID standardizes how to retrieve user information from the provider. Because a user information endpoint is not part of the OAuth 2.0 specification, it is up to you to provide an implementation to retrieve that information.

Here is a high level diagram of how the authorization code grant flow works with an OAuth 2.0 provider.

The minimum requirements to allow authorization with an OAuth 2.0 provider are:

Configuration is quite simple. For example to configure authorization with Github:

Authentication methods are not clearly defined in RFC 6749, however most OAuth 2.0 providers either accept client-secret-basic (basic authentication with id and secret), or client-secret-post (client id and secret are sent in the request body).

Beyond configuration, an implementation of OauthUserDetailsMapper is required by the user to be implemented. The implementation must be qualified by name that matches the name present in the client configuration.

The purpose of the user details mapper is to transform the TokenResponse into a UserDetails. That will entail calling some endpoint the provider exposes to retrieve the user’s information. Once that information is received, the user details can be populated per your requirements.

Common requirements of a user details mapper may be to combine data from the OAuth 2.0 provider with data from a remote database and/or create new user records. The UserDetails object stores three basic properties: username, roles, and arbitrary attributes. All data stored in the user details will be retrievable in controllers that accept an Authentication.

For example, here is how it might be implemented for Github.

Create a class to store the response data:

Create an HTTP client to make the request:

Create the user details mapper that pulls it together:

Adding support for authorization code flow with an OpenID provider is extremely easy with Micronaut.

Here is a high level diagram of how the authorization code grant flow works with an OpenID provider.

The requirements to allow authorization with an OpenID provider are:

The issuer URL will be used to discover the endpoints exposed by the provider.

See the following tables for the configuration options:

Because the OpenID standard returns a JWT token in the token response, it is possible to retrieve information about the user without having to make an additional call. In addition, the data stored in the JWT is standardized so you can use the same code to retrieve that information across providers.

A default implementation of OpenIdUserDetailsMapper has been provided for you to map the JWT token to a UserDetails. The default implementation will carry over any of the specific OpenID JWT claims, as well as potentially include other claims based on configuration. The original provider name will always be included in the JWT with the claim key "oauth2Provider". The following table explains the additional claims.

If the default implementation is not sufficient, it is possible to override the global default or provide an implementation specific to a provider.

To override the global default mapper, register a bean that replaces DefaultOpenIdUserDetailsMapper.

To override the user detail mapping behavior for a specific provider, register a bean with a named qualifier with a value equal to the name specified in the client configuration.

The OpenID specification for authorization requests allows for additional parameters beyond what is included in the OAuth 2.0 specification. Some of those parameters make sense to be provided by a bean and are described in this section. Other parameters are able to be controlled through configuration.

Here are the configuration option for authorization request parameters:

By default, this library will include a nonce parameter as described in the OpenID Connect specification in authentication requests.

Because the validation of the nonce requires the nonce to be stored somewhere temporarily, a NoncePersistence bean must be present to retrieve the nonce for validation. The default implementation stores the nonce in an HTTP cookie. To configure how the cookie is built, see the following configuration options:

You can provide your own implementation, however an implementation of nonce persistence that stores the nonce in an http session has also been provided.

To enable state persistence with an http session:

This library does not include an login hint by default with authorization requests. A LoginHintResolver bean can be registered that will be called when the authorization request is being built.

This library does not include an ID Token hint by default with authorization requests. A IdTokenHintResolver bean can be registered that will be called when the authorization request is being built.

A OpenIdTokenResponseValidator bean is responsible for validating the JWT token. The default implementation follows the guidelines described in the OpenID Connect specification regarding token validation where possible.

By default all implementations of GenericJwtClaimsValidator and OpenIdClaimsValidator are used to validate the token.

To allow for additional or custom validations, register an OpenIdClaimsValidator bean.

By default, this library will include a state parameter as described in RFC 6749 to authentication requests. A JSON serialized object is stored that contains a nonce value used for validation.

Because the validation of the state requires the state to be stored somewhere temporarily, a StatePersistence bean must be present to retrieve the state for validation. The default implementation stores the state in an HTTP cookie. To configure how the cookie is built, see the following configuration options:

You can provide your own implementation, however an implementation of state persistence that stores the state in an http session has also been provided.

To enable state persistence with an http session:

The resource owner password credentials grant is described in RFC 6749. In short, credentials are passed directly to the token endpoint and if authentication succeeds, the token endpoint responds with the appropriate token.

The process that handles the token response onward is the same for both authorization code and password grants. See the following high level flow diagrams:

OAuth 2.0 Provider

OpenID Provider

In Micronaut, the password grant is supported by setting the grant-type configuration option in the client configuration. For example:

When a client is configured for the password grant type, the authorization code endpoints will not be available and instead an AuthenticationProvider will be created that will participate in the normal login flow.

Part of the OpenID Connect specification includes a draft document titled Session Management. Because the specification is a draft, some providers have implemented it differently or not at all. See the following diagram for how end session works with default configuration:

If any configured OpenID provider supports end session behavior, a route will be registered that responds to /oauth/logout and redirects to the provider to log the user out. A parameter is also sent to the provider that indicates what URL the provider should redirect the user to after logging out. The default URL is /logout which will cause the local authentication to also be cleared and a final redirect issued according to the LogoutHandler.

All of the above is configurable through micronaut.security.oauth2.openid:

To enable the usage of the /logout endpoint, see the section on the Logout Endpoint.

This library supports end session for Auth0, AWS Cognito, and Okta out of the box. The EndSessionEndpointResolver is responsible for determining which EndSessionEndpoint will be used for a given provider, if any.

Before choosing any of the default providers, the endpoint resolver will first look for an EndSessionEndpoint bean with a named qualifier that matches the name of the client in configuration. If no bean is found then the default endpoints will be matched against the issuer URL.

If for example you are using one of the providers that is supported out of the box and you don’t want the end session support, it is possible to disable it per client.

It is possible to configure the introspection endpoint URL for OAuth 2.0 and OpenID providers, however Micronaut currently does not use this configuration in any way.

See the following configuration table:

It is possible to configure the revocation endpoint URL for OAuth 2.0 and OpenID providers, however Micronaut currently does not use this configuration in any way.

See the following configuration table:

It is possible to configure the user info endpoint URL for OpenID providers, however Micronaut currently does not use this configuration in any way.

See the following configuration table:

The center of the OAuth 2.0 authorization code grant support is the OauthClient for standard OAuth 2.0 and OpenIdClient for OpenID. The current implementation builds clients based on configuration. It is possible however to register a custom client and that client will automatically have the routes associated with it to enable the authorization code grant flow.

The OauthClient interface is simple and only requires three methods.

Because of how generic this interface is, it is possible to implement authentication for any provider that follows the redirect / redirect back pattern. For example one could implement support for OAuth 1.0a providers (looking at you, twitter).