Last updated: 2023-08-08
Security tab - backgrounds
The Security tab is available for projects in the Professional plan. This allows to configure a project with Spring Security, selecting between JWT, form-based authorization or Keycloak via OAuth/OIDC.
The Security tab with a selected user and role table
If one of the security options has been selected, the necessary libraries, configurations and classes are included in the generated code. For the code style you can choose between Annotation based and Config based. If Annotation based is selected, the required role for the endpoints is stored directly at the controllers: @PreAuthorize("hasAuthority('" + ROLE_USER + "')"). Otherwise, the JwtSecurityConfig / HttpSecurityConfig / OAuthSecurityConfig class includes a configuration so that all defined endpoints require a specific role.
For all security types, any roles can be specified as string constants. The first role is always assigned to the user and checked for at the protected endpoints. Alternatively, for JWT and form-based login, a field can be chosen from the database - from the current or a referenced table. If the target field is a string, the defined constants are used as a reference. If the target is a referenced table, a RoleLoader class is added, which initializes all defined roles at application startup.
Common backgrounds for JWT and form login
The connection to a user table is optional. If this is not specified at all or incompletely, the JwtUserDetailsService / HttpUserDetailsService will provide one static user with the username "bootify" and the password "Bootify!". If a username field is selected, it's recommended to make it unique at the entity - otherwise multiple users with the same login could be created, leading to unexpected errors.
If the registration option has been enabled, a RegistrationResource / RegistrationController is added to the generated code. This allows to add new users without authentication, either via the REST API or in the browser. If the user table has relations that are required, the generated code needs to be adjusted after the download.
If integration testing has been activated for the project, the BaseIT class is also extended providing the required authorization. If the setup with a user table was chosen, an additional SQL script is used to first create the test user before each test (password "Bootify!").
Backgrounds on JWT
With JWT, only requests with a valid JSON Web Token are accepted. They can be retrieved via calls to the AuthenticationResource. A deeper explanation of the technical backgrounds is available here.
The tokens are created in JwtTokenService using one of the selected algorithms. If a symmetric algorithm has been selected, a single secret is used for signing and validating the tokens using the HMAC512 algorithm. The secret is stored in application.properties / application.yml. That's a good option if no further party needs to validate the tokens and they are only used in our Spring Boot application.
If an assymetric algorithm has been selected, a private key is used for signing and a public key is used for validating the tokens, using the RSA256 algorithm. This way, the pubic key could be shared so that other parties can verify tokens as well. Although the secret and RSA keys are created individually for each project by Bootify, they should be changed after the download. A minimum length of 512 bits is required for the secret.
The BaseIT class will provide a method bearerToken(), which is included as a header in the individual tests. The test user has the same username and password as mentioned above - however the JWT is directly stored in the code for the tests.
If Swagger UI has been enabled for the project, a SwaggerConfig is also included in the project to add authorization to the OpenAPI Specification. This will allow us to authorize with the JWT in the Swagger UI client. The endpoints for Swagger itself together with the mentioned Controllers are excluded from authorization. Please check out this article for a short walkthrough on how to work with the tokens.
Backgrounds on form login
With the form-based authorization, an AuthenticationController is added to the code in order to show the Thymeleaf template authentication/login.html and provide required messages to the user. A RegistrationController is added as well if the respective option has been checked.
Generated controller when selecting form-based security type
The REST controllers are included in the protection by default, so browser-based login is required first before accessing the API. The BaseIT class will provide a method authenticatedSession(), performing a login transparently, so the tests can use a session with an authenticated user.
Backgrounds on Keycloak
Keycloak can also be selected if a frontend is available for the app. This integrates an external Keycloak server in the latest version 22.0.3 into our Spring Boot application using OAuth / OIDC - backgrounds are explained here.
Keycloak configuration in the Security tab
The specified realm and client should be available on the Keycloak server and the generated secret must be entered in application.yml / application.properties. The Keycloak realm can also be initialized for development using the provided keycloak-realm.json - be aware, a test user is already included here ("[email protected]" / "Bootify!"). If the option for Docker compose is activated, a Keycloak container is provided and initialized with the keycloak-realm.json file as well.
A user table can also be optionally selected here. After a successful login, the user is created via the UserSynchronizationService and identified via the unique, external ID. Email, first name and last name can be persisted as well - these fields are required by default when a new user registers itself in Keycloak.
When the integration tests are active for the project, a Docker image of Keycloak is started in the BaseIT class and initialized using the keycloak-realm.json. This allows to perform the OAuth flow before accessing the application and have an authenticated session available for the further requests.
See Pricing
or read quickstart
