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

For this project, you can find a list of releases (with release notes) here:

https://github.com/micronaut-projects/micronaut-security/releases

Micronaut Security includes the following new features and improvements.

This section will document breaking changes that may happen during milestone or release candidate releases, as well as major releases eg (1.x.x → 2.x.x).

To use the Micronaut’s security capabilities you must have the security dependency on your classpath:

By default Micronaut returns HTTP Status Unauthorized (401) for any endpoint invocation. Routes must be explicitly allowed through the provided mechanisms.

When you add the micronaut-security dependency, it contributes a Micronaut HTTP Server Filter - the SecurityFilter.

For each request, the filter evaluates the request against every bean of type AuthenticationFetcher. That evaluation may result in an instance of type Authentication being resolved.

Then, the optional authentication is evaluated against every bean of type SecurityRule to determine if the request is authorized. If not authorized, an AuthorizationException is thrown.

You can write your own bean of type AuthenticationFetcher. However, Micronaut Security ships with several built-in authentication fetchers:

BasicAuthAuthenticationFetcher parses the credentials from an HTTP Request using Basic Authentication. Then, it invokes every Authentication Provider using the parsed credentials.

TokenAuthenticationFetcher attempts to retrieve a token from the HTTP Request via the TokenResolver API, and then it tries to validate the token via the TokenValidator API.

You can write your own bean of type TokenReader. However, Micronaut Security ships with several built-in beans of type TokenReader.

BearerTokenReader attempts to read a RFC 6750 Bearer Token.

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

CookieTokenReader attempts to read token from a request cookie.

The following configuration properties are available to customize how the token will be read from a cookie:

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

Security rules return a publisher that should emit a single SecurityRuleResult. See the following table for a description of each result.

Security rules implement the ordered interface and so all of the existing rules have a static variable ORDER that stores the order of that rule. The rules they are executed in order from lower to higher values. You can use those variables to place your custom rule before or after any of the existing rules.

In the following table you can find the order and a short description of the behavior of built-in security rules. You can find more details about theese rules in their own guide sections.

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.

The IP patterns rule never explicitly allows requests, it only rejects requests if the address does not match. There must be other security rules that determine whether a resource should be accessed.

If the desired behavior is to allow access to all resources as long as the address matches, create a security rule that executes after this one that returns ALLOWED.

As illustrated below, you can use the @Secured annotation to control access to controllers or controller methods.

Alternatively, you can use Jakarta Annotations:

In combination with @Secured, you can use expressions, introduced in Micronaut Framework 4.0, to access the authenticated user:

user is of type Authentication

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.

You need to replace the default implementation SensitiveEndpointRule and implement SensitiveEndpointRule::checkSensitiveAuthenticated to allow authenticated users access to sensitive endpoints. For example, you may want to restrict access to users with a specific role:

Micronaut Security ships with several built-in Exception Handlers:

You may need to replace some of those beans to customize Micronaut Security exception handling to your needs.

The Security Filter section describes how for each request an Authentication maybe resolved. It maybe a token placed in an HTTP Header, in a cookie, or an HTTP session. How do you obtain such a token or how is the user saved into the HTTP Session in the first place?. In a Micronaut application, you can expose the LoginController.

To enable the LoginController, you need to have a bean of type LoginHandler. A custom implementation can, of course, be provided. However, several Login Handlers implementations are available out of the box.

You can configure the LoginController with:

The LoginHandler API defines how to respond to a successful or failed login attempt. For example, with the Login Controller or with OAuth 2.0 support.

To enable the logout controller you need a bean of type LogoutHandler. The behaviour of the controller is delegated to it. A custom implementation can, of course, be provided. However, several Logout Handlers implementations are available out of the box.

You can configure the logout endpoint with:

The LogoutHandler API defines how to respond to a logout attempt. For example, with the Logout Controller.

You can provide your own implementations of LoginHandler and LogoutHandler. However, Micronaut security modules ship with several implementations which you can enable by setting the configuration micronaut.security.authentication

These handlers allow you to set the following scenarios:

When you set micronaut.security.authentication=bearer, AccessRefreshTokenLoginHandler a bean of type LoginHandler is enabled.

When you set micronaut.security.authentication=session, SessionLoginHandler a bean of type LoginHandler and SessionLogoutHandler a bean of type LogoutHandler are enabled.

When you set micronaut.security.authentication=cookie, TokenCookieLoginHandler a bean of type LoginHandler and JwtCookieClearerLogoutHandler a bean of type LogoutHandler are enabled.

When you set micronaut.security.authentication=idtoken, IdTokenLoginHandler a bean of type LoginHandler and JwtCookieClearerLogoutHandler a bean of type LogoutHandler are enabled.

The following global configuration options are available:

By default, when you include Micronaut security the app returns 401 or 403 even for non existing routes. The behavior prevents attackers from discovering what endpoints are available in your application. However, if you wish to return 404 for non found routes you can set micronaut.security.reject-not-found: false in your configuration.

By default, Micronaut requires just one Authentication Provider to return a successful authentication response. You can set micronaut.security.authentication-provider-strategy: ALL to require all AuthenticationProviders to return a successful authentication response.

Some built-in handlers respond with a 303 (See other) response to the urls defined in the Redirection Configuration If you disable redirection configuration with by setting micronaut.security.redirect.enabled to false, these handlers respond with 200 responses instead.

Several security flows (e.g. session based authentication, Cookie Token authentication) may involve redirection after the user logs in.

You can configure the redirection destinations with:

To authenticate users you must provide implementations of ReactiveAuthenticationProvider or HttpRequestReactiveAuthenticationProvider.

The following code snippet illustrates a naive implementation:

The ReactiveAuthenticationProvider interface is a reactive API. If you prefer an imperative style, you can instead implement the AuthenticationProvider or HttpRequestAuthenticationProvider interface:

The built-in Login Controller uses every available authentication provider. The first provider that returns a successful authentication response will have its value used as the basis for the JWT token or session state.

Basic authentication which is implemented as an AuthenticationFetcher will also trigger the available AuthenticationProviders.

Micronaut comes with authentication providers for LDAP (LdapAuthenticationProvider) and the OAuth 2.0 password grant authentication flow (OauthPasswordAuthenticationProvider and OpenIdPasswordAuthenticationProvider). For any custom authentication, an authentication provider must be created.

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. Basic authentication is enabled by default. You can disable it by setting micronaut.security.basic-auth.enabled to false.

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:

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:

The following sequence illustrates the authentication flow:

Check the Redirection configuration 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:

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.

You can inject a bean of type The JsonWebTokenParser to parse a JWT token. The parser decrypts the token if encrypted.

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

Micronaut’s JWT validation supports multiple signature configurations. Thus, you can validate JSON Web tokens signed by different issuers in the same application.

To verify the signature of JWT tokens, you need beans of type SignatureConfiguration or ReactiveSignatureConfiguration

The easiest way is to create a bean of type SignatureConfiguration is to have in your app a bean of type RSASignatureConfiguration, ECSignatureConfiguration, or SecretSignatureConfiguration which must be qualified with @Named since the configuration beans are used by factories (html, ECSignatureConfiguration) or other beans (SecretSignature) which use @EachBean to drive configuration.

The APIs JsonWebTokenSignatureValidator, and ReactiveJsonWebTokenSignatureValidator allows you to validate the signature of a JWT token.

ReactiveJsonWebTokenSignatureValidator validates the signature using both SignatureConfiguration or ReactiveSignatureConfiguration.

JsonWebTokenSignatureValidator validates the signature using beans of type SignatureConfiguration.

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 ReactiveJwksSignature bean with a awscognito name qualifier.

If you have the Micronaut HTTP Client on the classpath, then it will be used to retrieve the remote JWK Set. This allows for the configuration settings of the HTTP Client to be applied when fetching the resource. If a named service-specific client exists and the name of the service matches the name of the configured JWKS provider name, then that specific client instance will be used, otherwise a default Http Client instance (with any global configuration settings from micronaut.http.client.* applied) will be used. If the Micronaut HTTP Client is not on the classpath, then the implementation will fall back to the internal resource fetching mechanism of the external JWT library dependency.

For example, to use an HTTP proxy for the fetching of the JWK Set from the above example:

Note that the same approach will be applied when using a jwks_uri supplied via Open ID Connect metadata.

The Micronaut HTTP Client based implementation can be explicitly disabled in favor of the JWT library’s internal resource fetching implementation by explicitly setting micronaut.security.token.jwt.signatures.jwks-client.http-client.enabled=false. For example:

Json Web Key Set (JWKS) fetched from a remote web server are cached. By default, they are cached via the internal bean ReactorCacheJwkSetFetcher using Project Reactor’s Mono::cacheInvalidateIf. You can configure the cache expiration with micronaut.security.token.jwt.signatures.jwks.*.cache-expiration. It defaults to 60 seconds.

Caching via Micronaut Cache

To cache JWKS with Micronaut Cache, you need to add an implementation of Micronaut Cache (E.g. Caffeine, Redis, Ehcache, Hazelcast, Coherence, Infinispan, EclipseStore, or MicroStream) and configure the expiration.

For example, you could add Caffeine implementation:

The cache name is jwks. You can configure the cache expiration with:

You can specify a path starting with classpath: or file: to serve a JSON JWKS from anywhere on disk or in the classpath. For example to serve static resources from src/main/resources/jwks/certs.json, you would use classpath:jwks/certs.json as the path.

The APIs JsonWebTokenValidator, and ReactiveJsonWebTokenValidator allows you to validate a JWT token.

The validation performs the following steps:

JsonWebTokenValidator will not use remote signature configuration. E.g. it will not validate the signature with remote JWKs. Only, ReactiveJsonWebTokenValidator implements TokenValidator.

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

The following configuration options are available:

To generate a signed JWT you need to have in your app a bean of type RSASignatureGeneratorConfiguration, ECSignatureGeneratorConfiguration, , or SecretSignatureConfiguration which must be qualified with @Named generator since the configuration beans are used by factories ( RSASignatureGeneratorFactory, ECSignatureGeneratorFactory) or other beans (SecretSignature) which use @EachBean to drive configuration.

You can setup a SecretSignatureConfiguration qualified with @Named generator easily via configuration:

You can supply the secret with Base64 encoding.

A programmatic setup of a RSA signature generation may look like

Signed claims prevent an attacker from tampering with 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 contain sensitive information, you can use a JSON Web Encryption algorithm to prevent them from being decoded.

Micronaut’s JWT validation supports multiple encryption configurations.

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

Those beans need to be qualified with @Named since the configuration beans are used by factories (RSAEncryptionFactory, ECEncryptionFactory) or other beans (SecretEncryptionFactory) which use @EachBean to drive configuration.

Use generator as the @Named qualifier if you want to use encryption configuration in the tokens your app generates.

The API JsonWebTokenEncryption allows you to decrypt an encrypted token.

Setup a SecretSignatureConfiguration through configuration properties

Generate a 2048-bit RSA private + public key pair:

To parse the PEM key, use a collaborator as described in OpenSSL key generation.

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

The claims of a JSON Web Token are validated using every bean of type GenericJwtClaimsValidator.

Micronaut Security includes some validators by default:

If you are using micronaut.security.authentication: idtoken, IdTokenClaimsValidator, a bean of type GenericJwtClaimsValidator, is registered in the bean context as well. IdTokenClaimsValidator validates points 2-5 of the ID Token Validation section of the OpenID Connect Spec. You can disable it by setting micronaut.security.token.jwt.claims-validators.openid-idtoken to false.

When you use bearer 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.

Read the following guides to learn more about JSON Web Token and JSON Web Keys:

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

LDAP authentication can be globally disabled by setting micronaut.security.ldap.enabled to false, or on a provider basis, eg micronaut.security.ldap.default.enabled: false.

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 Security supports using X.509 client certificates with HTTPS to enable mutual authentication.

Once you have configured HTTPS in your application, users can install X.509 browser certificates to provide authentication information and access restricted URLs.

When X.509 is enabled, in addition to the client (e.g. browser or API client) verifying that the server certificate is valid (i.e. that it was issued and signed by a trusted certificate authority (CA)), the server can also verify the client with the certificate from the client SSL handshake. If the client certificate is valid and contains a username/principal that corresponds to an application user, access will be granted.

All authorization strategies implement the AuthenticationFetcher interface. The contract is designed to return an Authentication from the request. To implement custom logic to retrieve the currently logged in user, simply create a bean that implements the contract and it will be picked up automatically.

For example, if you use a product like SiteMinder that handles authentication for you, you can trust that users access your application are authenticated, and you can access their username via the SM_USER request header and build an Authentication from that:

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.

When a request is rejected, the security filter emits an AuthorizationException. The default implementation (DefaultAuthorizationExceptionHandler) redirects based on the redirect configuration only if the request accepts text/html:

For an unauthorized request, a 401 http response will be sent if unauthorized.enabled is false, or the request does not accept text/html.

For a rejected request, a 403 http response will be sent if forbidden.enabled is false, or the request does not accept text/html.

To fully customize the behavior, replace the relevant bean with your own implementation.

For example:

Cross-Site Request Forgery (CSRF):

Add the Micronaut Security CSRF dependency to protect against CSRF:

The core of Micronaut Security CSRF implementation is io.micronaut.security.csrf.filter.CsrfFilter. A Server Filter which attempts to resolve a CSRF Token with every bean of type CsrfTokenResolver and validates it with beans of type CsrfTokenValidator.

The following configuration options are available for the CSRF Filter:

Syncronizer Token Pattern.

If you use Session-Based Authentication and Micronaut Security CSRF, a CSRF token is automatically generated upon login and saved into the HTTP Session. Micronaut Session provides an implementation CsrfTokenRepository which fetches the CSRF token from the user’s HTTP session. Thus, when the application sends new request to the sever with a CSRF token (e.g. in a hidden form field or HTTP Header), the server validates the supplied token against the value stored in the HTTP Session.

You can disable the CSRF Session repository by setting micronaut.security.csrf.repositories.session.enabled to false.

Double Submit Cookie Pattern.

In a double-submit cookie pattern, the server generates a CSRF token, and it sends the CSRF token to the client in a cookie.

Then, the server only needs to verify that following requests cookie’s value matches the CSRF token sent in a request parameter (a hidden form field) or header. This process is stateless, as the server doesn’t need to store any information about the CSRF token.

When you use Micronaut Security Authentication cookie, or idtoken a CSRF Token is saved in a Cookie upon login.

You can configure different cookie attributes. For example, by default the cookie name uses a __Host- Cookie prefix, can extend security protections against CSRF Attacks.

To do sign the CSRF Token, set the property micronaut.security.csrf.signature-key.

The following configuration options are available for CSRF:

Micronaut Security CSRF resolves a CSRF Token with beans of type CsrfTokenResolver

Micronaut Security CSRF ships a io.micronaut.security.csrf.resolver.HttpHeaderCsrfTokenResolver an implementation of CsrfTokenResolver which looks for a CSRF Token in a Request’s HTTP Header.

You can disable it by setting micronaut.security.csrf.token-resolvers.http-header.enabled=false

The HTTP Header name used by HttpHeaderCsrfTokenResolver can be configured. It is recommended to use a custom HTTP Header Name. By using a custom HTTP Header name, it will not be possible to send them cross-origin without a permissive CORS implementation.

Moreover, If possible, we recommend you to send the CSRF token via an HTTP Header instead of a form field as it is harder to attack.

For example, Turbo sends the CSRF token via a custom HTTP Header upon form submission. You can find information about Micronaut Turbo integration.

Micronaut Security CSRF ships a io.micronaut.security.csrf.resolver.FieldCsrfTokenResolver an implementation of CsrfTokenResolver which looks for a CSRF Token in a Request’s form-url-encoded field.

You can disable it by setting micronaut.security.csrf.token-resolvers.field.enabled=false

The main APIs for CSRF protection are:

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 HttpHeaderTokenPropagator 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:

Several configuration options are available:

For propagation via an HTTP Header, you can configure:

Refresh tokens can be used to obtain a new access token. By default, refresh tokens are not generated.

The RefreshTokenGenerator API is responsible for generating the token that gets included in the response. The RefreshTokenValidator is responsible for validating the refresh token. Note that this validation step is not related to the persistence of the token, but instead is intended to verify the token is not a random/guessed value.

An implementation of both RefreshTokenGenerator and RefreshTokenValidator has been provided by default. The SignedRefreshTokenGenerator creates and verifies a JWS (JSON web signature) encoded object whose payload is a UUID with a hash-based message authentication code (HMAC). See the following configuration options:

To enable it, you must provide a secret:

After a token is generated, this library has no knowledge of it. The value is not cached or stored anywhere. It is up to each application to decide how to store the token, support revocation, and retrieve user details when given a token.

In addition to the above requirements, each application must provide an implementation of RefreshTokenPersistence.

The RefreshTokenPersistence implementation will receive an event when a refresh token is generated and then is responsible for persisting the token along with a link to the user that it was generated for. The user information and the token are both available in the RefreshTokenGeneratedEvent.

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.

To enable the KeysController you have to provide at least a bean of type: JwkProvider.

Moreover, you can configure it with:

The Introspection endpoint exposes an endpoint to inquire the current state of a token.

Moreover, you can access a secured GET endpoint which responds the introspection response for the authenticated user:

responds:

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.

You can create a custom argument binder to bind the authenticated user to a custom class tailored to your application needs.

If, in your application, the authenticated user has an email address, you can create a class such as:

and then a TypedRequestArgumentBinder:

Then you can bind it in a controller method parameter:

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 provides integration with Micronaut Data for automatically capturing the identity of the user that created or updated a particular entity.

The annotations @CreatedBy and @UpdatedBy annotations are provided for application to your Micronaut Data entities. The annotated fields will be automatically populated with the currently authenticated user’s identity. For example:

A PrincipalToStringConverter is provided to map the current Authentication object to the annotated String fields. The default implementation maps the value of Principal.getName() to the fields. To customize this mapping, you can provide your own TypeConverter implementation that replaces PrincipalToStringConverter. For example:

The type conversion mechanism could also be used to map Authentication to more complex field types other than String, such as a custom domain-specific User object.

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 LoginHandler 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, several Login Handlers implementations 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 OauthAuthenticationMapper 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 Authentication. 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 Authentication 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 OpenIdAuthenticationMapper has been provided for you to map the JWT token to a Authentication. 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 DefaultOpenIdAuthenticationMapper.

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.

Micronaut ships with two implementations of NoncePersistence. One implementation to store it in a HTTP cookie (CookieNoncePersistence) and another one to persist it with a HTTP Session (SessionNoncePersistence).

You can configure which implementation to use:

If you use the default implementation, which stores the nonce in a HTTP cookie, you can configure how the cookie is built. See the following configuration options:

To use (SessionNoncePersistence`). which stores the nonce in a 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:

Using OpenID Connect Discovery by setting micronaut.security.oauth2.clients.*.openid.issuer and the Authorization server specifies via code_challenge_methods either plain, S256, or both, Micronaut security automatically sends a code challenge in the authorization request as specified in Proof Key for Code Exchange (PKCE) Spec.

Using manual OAuth 2.0 Client configuration, you can specify the challenge method supported by setting micronaut.security.oauth2.clients.*.authorization.code-challenge-method.

If the built-in implementation does not fulfill your needs, you can provide a replacement of bean CodeVerifierGenerator or PkceGenerator.

You can obtain a bean of type ClientCredentialsClient to request an access token via a Client Credentials Grant for your OAuth 2.0 Clients.

For example:

You can obtain a bean of type ClientCredentialsClient for any of the OAuth 2.0 clients using a Name Qualifier.

or

ClientCredentialsClient caches the token response. If the cached access token is expired, they renew it automatically.

Micronaut Security includes ClientCredentialsHttpClientFilter. This HTTP Client Filter allows you to automatically include an access token to an outgoing request HTTP Header. It obtains the access token via a Client Credentials request.

For example, the next configuration adds an access token to the requests' HTTP Headers done via the HTTP Client inventory. It obtains the access token with a Client Credentials request with the OAuth 2.0 client companyauthserver.

The following configuration options are available per OAuth 2.0 client:

Read the following guides to learn more abut Client Credentials Flow:

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).

Read the following guides to learn more abut OAuth:

Micronaut Security offers several ahead-of-time optimizations.

With Micronaut Gradle Plugin, you can use aotPlugins configuration to declare additional AOT modules to be used:

for Micronaut Maven Plugin you will need to do:

When you use OpenID Connect in a Micronaut application, the application constructs a URL by appending .well-known/openid-configuration to the value you specify for each OAuth 2.0 client via micronaut.security.oauth2.clients.*.openid.issuer. It visits the URL to fetch OpenID Connect metadata related to the specified authorization server and configure itself.

However, this is a network request which may be slow. Moreover, the application will probably need to execute this network request to serve the first request.

You can use Micronaut Security ahead-of-time build optimizations to do the request at build-time.

To enable this optimization, add micronaut.security.openid-configuration.enabled=true to aot.properties.

Learn about Micronaut Maven Plugin AOT configuration and Micronaut Gradle Plugin AOT Configuration.

Micronaut security supports JWKS (JSON Web Key Sets) either specifying them directly or via the jwks_uri obtained when fetching the OpenID Connect metadata. Micronaut security uses JWKS to validate the signature of tokens issued by another application or an authorization server.

Micronaut applications need to make a network request to fetch JWKS. You can use Micronaut Security ahead-of-time build optimizations to make the request at build-time.

To enable this optimization, add micronaut.security.jwks.enabled.enabled=true to aot.properties.

Learn about Micronaut Maven Plugin AOT configuration and Micronaut Gradle Plugin AOT Configuration.

You can find the source code of this project in this repository:

https://github.com/micronaut-projects/micronaut-security