Last updated: 2024-03-20
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 authentication, Keycloak resource server 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.
If Angular has been selected as the frontend, components for login and registration are provided. The authentication.service.ts is connected to the provided API. The authentication.injectable.ts automatically adds the token to all outgoing requests to the API. The actual verification of the token takes place in the backend - however, the client can check in advance whether a login is required by looking up the required roles in the app.routes.ts.
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 authentication, 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
If one of the options for Keycloak has been selected, an external Keycloak server in the latest version 24.0.1 is integrated into our Spring Boot application. The Keycloak resource server option protects the REST API and prepares the application to act as a resource server, validating incoming tokens - backgrounds here. If Keycloak client has been selected, the Thymeleaf frontend is protected using OAuth / OIDC - backgrounds here.
If Angular and the Keycloak resource server have been selected, the client is also directly integrated with Keycloak via OAuth/OIDC. This means that after successful login, the browser client has a token that is sent to the REST API within authentication.injectable.ts. The token is automatically renewed in authentication.service.ts when required. As with the JWT option, the client can already check the required roles from the data.roles field in the app.routes.ts. Backgrounds on the technical approach 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 successful authentication, 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 or request a fresh token before accessing the application and have an authenticated session available for the further requests.
See Pricing
or read quickstart
