In the era of microservices and cloud-native applications, securing your APIs is no longer optional—it’s essential. Micronaut Security Basics gives you a head start in understanding how to secure your Micronaut-based applications using built-in features like JWT authentication, HTTP Basic Auth, and role-based authorization.
Micronaut provides a robust and extensible security module that integrates seamlessly with modern authentication and authorization standards. In this post, we’ll cover everything from configuration to implementation with real-world examples using the package com.kscodes.micronaut.security
.

🔐 What is Micronaut Security?
Micronaut Security is a built-in module for handling authentication, authorization, and user management within Micronaut applications. It supports a variety of security mechanisms, including:
- HTTP Basic Authentication
- JWT (JSON Web Token)
- OAuth2/OpenID Connect
- LDAP
- Session-based Auth
It’s lightweight, fast, and ideal for microservice architectures.
🔧 Getting Started with Micronaut Security
1. Add Security Dependencies
Update your build.gradle
or pom.xml
to include Micronaut Security:
1 2 3 4 5 6 |
dependencies { implementation("io.micronaut.security:micronaut-security-jwt") } |
For Maven:
1 2 3 4 5 6 7 |
<dependency> <groupId>io.micronaut.security</groupId> <artifactId>micronaut-security-jwt</artifactId> </dependency> |
⚙️ Basic Security Configuration
Create application.yml
:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
micronaut: application: name: micronaut-security-demo security: enabled: true token: jwt: signatures: secret: generator: secret: "mysecretkey" authentication: bearer |
👤 Creating a Simple Authentication Controller
com.kscodes.micronaut.security.AuthController.java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
package com.kscodes.micronaut.security; import io.micronaut.http.annotation.*; import io.micronaut.security.authentication.*; import io.micronaut.security.token.jwt.render.BearerAccessRefreshToken; import jakarta.inject.Inject; import reactor.core.publisher.Mono; @Controller("/auth") public class AuthController { @Inject AuthenticationProviderUserPassword authProvider; @Post("/login") public Mono<BearerAccessRefreshToken> login(@Body UsernamePasswordCredentials credentials) { return Mono.from(authProvider.authenticate(null, credentials)) .map(auth -> new BearerAccessRefreshToken("myApp", auth.getName(), auth.getRoles())); } } |
👥 Custom Authentication Provider
com.kscodes.micronaut.security.BasicAuthProvider.java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
package com.kscodes.micronaut.security; import io.micronaut.security.authentication.*; import jakarta.inject.Singleton; import org.reactivestreams.Publisher; import reactor.core.publisher.Mono; import java.util.List; @Singleton public class BasicAuthProvider implements AuthenticationProvider { @Override public Publisher<AuthenticationResponse> authenticate(AuthenticationRequest<?, ?> request) { String identity = request.getIdentity().toString(); String secret = request.getSecret().toString(); if (identity.equals("admin") && secret.equals("admin123")) { return Mono.just(AuthenticationResponse.success(identity, List.of("ROLE_ADMIN"))); } else { return Mono.just(new AuthenticationFailed()); } } } |
🔒 Securing Endpoints with Role-Based Access
com.kscodes.micronaut.security.AdminController.java
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 |
package com.kscodes.micronaut.security; import io.micronaut.http.annotation.*; import io.micronaut.security.annotation.Secured; import io.micronaut.security.rules.SecurityRule; @Controller("/admin") public class AdminController { @Secured("ROLE_ADMIN") @Get("/dashboard") public String dashboard() { return "Welcome to the Admin Dashboard"; } } |
🧪 Testing the Flow
- Login with /auth/login using:
1 2 3 4 5 6 7 |
{ "username": "admin", "password": "admin123" } |
Use JWT token from the response to access /admin/dashboard
.
Unauthorized users will get 403 Forbidden
.
📌 Best Practices
- Store secrets securely (e.g., Vault, AWS Secrets Manager).
- Use HTTPS in production.
- Implement token expiration and refresh mechanisms.
- Integrate OAuth2 or external IdPs for scalable authentication.
📚 External References
✅ Conclusion
Micronaut Security Basics provide a clean and efficient way to secure your services. With built-in support for JWT and role-based access, you can protect your endpoints with minimal configuration. The com.kscodes.micronaut.security
package shown here is a great starting point to build scalable, secure applications.
Whether you’re building REST APIs or microservices, understanding Micronaut Security will give your applications the foundational layer of protection they need.