Prerequisites

You need to have an AWS account. If you are new to AWS, they offer a 12-month free tier account where you can explore many services as a developer.

Create an Amazon Cognito User Pool

Please refer to this article in the Create Amazon Cognito User Pool section to create a Cognito User Pool, note the Cognito User Pool ID and the App Client ID, and then continue with the following section.

Enable endpoint access management in API Gateway

As you can see, any frontend or API caller can send requests to these REST API endpoints without including an access token in the request header. We will implement a JWT token authorizer with the Amazon Cognito User Pool created earlier.

Let us open the API Gateway created in this article.

• Select a method (POST for instance (1)) then, in the Route details section, click on the Attach authorization button (2).

• On the Authorization page, ensure the method is still selected and click the Create and attach an authorizer button (1).

• On the Create authorizer page, choose the Authorizer type: JWT (1), and provide the Authorizer settings: Name: CRUD-API-COGNITO-AUTH (2), Identity source: $request.header.Authorization (3), Issuer URL: https://cognito-idp.[zoneId].amazonaws.com/[userPoolId] (4). For the Audience field, first click on the Add Audience button, then provide the Client ID (5) noted while creating the Amazon Cognito User Pool. Click the Create and attach button to attach the newly created authorizer to the API route method.

• To attach an existing authorizer to a method, select the method, then in the Route details section, click the Attach authorization button. Choose the existing authorizer (1) and click the Attach authorizer button (2).

Test and Wrap-Up

Follow the Test and Recap section of this article and the Test the Rest API section of this article to test what we have implemented.

This guide walks through implementing access management for a REST API using Amazon Cognito. Instructions include creating a Cognito User Pool, enabling endpoint access management in API Gateway, and configuring JWT token authorizers for secure token-based access. Follow these steps to protect your API endpoints effectively.

Thanks for reading 😊. Your suggestions and comments are welcome. Akpé kaka 🙏!

Prerequisites

All you need is just an AWS account: no worries, if you are new to AWS, AWS offers you a 12-month free tier account where you can play with lots of services as a developer (isn't it cool? 😜)

Step-by-step guide to creating a Lambda integration HTTP API

Amazon API Gateway is an AWS service that helps you create and secure REST and HTTP APIs at any scale.

The following steps will show you how to create an HTTP API and set up a POST method for an API resource.

Let's use the AWS console to create the API Gateway.

• On the API Gateway dashboard menu, select APIs (1) and then click on the Create API (2) button.

• On the Create API page, click on the Build button (1) under HTTP API section.

• In the Create an API step, select Lambda (1) in the Create and configure integrations section, then choose us-east-1 as the AWS Region (2). Select the ***Lambda function:***arn:aws:lambda:us-east-1:xxx:function:sample-crud-func (3) we created in this post. Then, give the API name: sample-crud-api (4), and click Next (5).

• In the Configure routes step, select POST as the Method (1), type /api/items as the Resource path (2), select sample-crud-func as the Integration target (3) and then click Next (4).

• Provide the Stage name*: dev* (1) and then click Next (2) in the Configure stages step.

• 

• The last step is to review what we provided in the previous steps and click Create (1).

Setting up the HTTP GET method for an existing API Gateway Lambda integration

• Select the API we created early (sample-crud-func), on the API Gateway menu, choose Routes menu (1), then click Create (2).

• On the Create a route page, under the Route and method section, choose the GET method (1) and provide the route path: /api/items (2). Then, click on the Create button (3).

• On the Routes page, under the /api/items tree, choose the GET method (1). In the Route details section, click on Attach integration (2).

• Select the Integrations menu (1). In the Attach integrations to routes tab, choose GET (2) under the /api/items tree. In the Integration details for route section, choose the Lambda function: sample-crud-funcxxx (3), then click on the Attach integration button (4).

Update the Lambda function to handle the API HTTP methods

Let's update this lambda function to handle the GET and POST requests we created above.

As of the time we are writing this article, the version of the event payload format that API Gateway sends to Lambda is 2.0.

We will use the routeKey attribute value from the event payload to get the request route path. This will help direct traffic to the corresponding Lambda CRUD methods. Additionally, we will use the queryStringParameters attribute value to get request parameters.

The index.mjs file's handler function becomes this:

• An environment variable called TABLE is created to handle the DynamoDB table's name. We retrieve its value into the TABLE_NAME variable in line 4: const TABLE_NAME = process.env.TABLE;. More information about Lambda environment variables can be found here.

• In line 5, we get the routeKey value, which is the API request's path from the API Gateway. This value will be used in line 14 to call the suitable action implemented in the Lambda function.

• This pattern is called Lambda monolith: using a single backend Lambda function to dispatch incoming traffic to multiple implemented actions. It's used for simplicity and is more suitable for small applications or monolith applications migrated to AWS Lambda. Take a look at this documentation for the recommendation.

Recap and test

• Let's go back to the API Gateway and choose the sample-crud-apixxx, then choose the Stages menu (1) and dev stage (2) on the Stages page. In the Stages details section, copy the Invoke URL value (3).

• Open Postman, choose the POST method, paste the URL, and append /api/items.

• Select the Body tab, and past the payload data (3) then click Send (4) to get the result (5) if everything is ok.

In this post, we provided a step-by-step guide to creating an API Gateway HTTP API with Lambda proxy integrations, highlighting the Lambda monolith pattern. You can find the source code for the Lambda function here.

Thanks for reading 😊. Your suggestions and comments are welcome. Akpé kaka 🙏!

Prerequisites

To follow this tutorial, you need an AWS account. Thankfully, AWS offers a twelve-months free tier plan (isn't that cool? 😜).

Setting up the Lambda function

We'll use the AWS console to create the Lambda function.

• Choose your preferred region (1), type Lambda in the search field near Services (2), then click on Lambda under Services in the result list (3).

• On the Lambda dashboard, from the menu list on the left side, click on the Functions menu item (1), then click Create function (2).

• On the Create function page, select Author from scratch (1), enter the Function name: sample-crud-func (2), choose the Runtime: Node.js 20.x (3), then under Change default execution role, select Create a new role with basic Lambda permissions (4). Finally, click on the Create function button at the bottom.

• Once the function is ready, open the sample-crud-func function and test it.

  • Select the Test tab (1), then as the Test event action, choose the Create new event option (2). Provide the Event name: test (3), then click the Test button.

Creating the DynamoDB table

The basic Lambda function is now ready. Before we add more logic to it, let's create the DynamoDB table for data storage.

DynamoDB is a fully managed, serverless NoSQL database service provided by AWS for modern applications. There are no upfront costs to launch DynamoDB, and you only pay for what you use.

• Go to the DynamoDB page, and choose the region. Here, we select us-east-1: N. Virginia (1). In the page menu, select Tables (2), then click on Create table button(3).

  

• Provide the Table name (sampleCrudTable), type the Partition key (pk), and then the Sort key (sk). To keep things simple, use the default options and click Create table at the bottom of the page.

Grant Lambda access to the DynamoDB table

• Let's open the sample-crud-func Lambda function, go to the Configuration (1) tab then in the Execution role section, click on Role name (2) to open the created named role.

• On the sample-crud-xxx-role-xxx (1) role page, open the Permissions tab (2), then click on the AWSLambdaBasicExecutionRole-xxx policy name (3).

• On the AWSLambdaBasicExecutionRole-xxx policy page, open the Permissions tab (1), then click on Edit (2).

• In the Edit policy editor, add the below permission to the permissions list:

            {
                "Effect": "Allow",
                "Action": [
                    "dynamodb:PartiQLInsert",
                    "dynamodb:PartiQLUpdate",
                    "dynamodb:PartiQLDelete",
                    "dynamodb:PartiQLSelect"
                ],
                "Resource": [
                    "arn:aws:dynamodb:us-east-1:xxx:table/sampleCrudTable"
                ]
            }
  

• Note: Remember to replace xxx with your AWS account number.

• Finally, the Policy editor should look like this:

• Click on Next, then Save changes to grant the CRUD PartiQL for DynamoDB statements permissions to the Lambda function.

Perform a CRUD operation

• Head back to the Lambda function we created, open the code tab, and replace the content of the index.mjs file with the following code:

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import {
  DynamoDBDocumentClient,
  ExecuteStatementCommand,
} from "@aws-sdk/lib-dynamodb";

const client = new DynamoDBClient({});
const docClient = DynamoDBDocumentClient.from(client);

const ITEM_PK = "ITEM";

//-------SAVE ITEM FUNCTION-----------
const saveItem = async (tableName, data) => {
  const SK = ITEM_PK + "#" + data?.label; //format PK#label => manage default label sorting

  let result;
  try {
    const command = new ExecuteStatementCommand({
      Statement: `INSERT INTO ${tableName} value {'pk':?,'sk':?,'label':?, 'category':?, 'price':?}`,
      Parameters: [ITEM_PK, SK, data?.label, data?.category, data?.price],
    });

    result = await docClient.send(command);
  } catch (e) {
    console.error(JSON.stringify(e));
    return e;
  }

  return result;
};

export const handler = async (event) => {
  const tableName="sampleCrudTable";

  //Call save Item
  await saveItem(tableName, event)
    .then((res) => {
      console.log(JSON.stringify(res))
    })
    .catch((e) => {
      console.log(JSON.stringify(e.errorMessage));
    });

  const response = {
    statusCode: 200,
    body: JSON.stringify('Hello from Lambda!'),
  };
  return response;
};

• To test the function, open the Test tab, replace the Event JSON editor (1) content with the following code then click Test (2).

{
  "label": "Paquet de Crayons de couleurs",
  "price": 30,
  "category": {
    "id": 1,
    "label": "Fourniture scolaire"
  }
}

• Open the DynamoDB table, select Explore items (1) from the left menu, choose the sampleCrudTable table (2), and then click Run (3). You should see the created data (4).

In this article, we guided you through building a simple CRUD backend using AWS Lambda and DynamoDB. You learned how to set up a Lambda function, create a DynamoDB table, grant necessary permissions, and perform CRUD operations using JavaScript.

In the next articles, we'll learn how to secure and protect this backend using API Gateway and Amazon Cognito.

Please subscribe and share. Thanks!

Prerequisites

1. Have an AWS account

2. Know how to configure AWS credentials on the local machine

3. Be familiar with the Spring Boot project

Create MySQL DB instance using Amazon RDS

In this section, you will step-by-step create a MySQL DB instance using the AWS Management Console. At the end of this section you will have an online database ready to use :muscle:.

1. Go to AWS Management Console and sign in.

2. Choose the AWS Region you want and type RDS in the Search for services ... search bar and select it.

3. RDS console will open. In the navigation pane, choose Databases then Create database on the top-right of the Databases table to open the below page :

4. Choose a database creation method : Standard create

5. Engine options : MySQL

6. Templates : Free tier

7. DB instance identifier : mydemodb

8. Master username : admin

9. Master password & Confirm password : adminadmin

10. DB instance class : db.t2.micro

11. Public access : Yes

12. Click Additional configuration -> Initial database name : demodb

Step 12 will make RDS create a database named demodb

13. Leave all other options as is and then click Create database

Once the database is created, click on mydemodb in the Databases list to view its summary. We can use it at this point with basic information such as: endpoint, port, principal user name, principal password and database.

Create AWS Secrets to protect DB credentials

We have created the MySQL database, now, to avoid hard coding its credentials in our Spring Boot project, we'll use AWS proven service that helps easily rotate, manage, and retrieve database credentials, API keys, and other secrets through their lifecycle : AWS Secrets Manager.

1. Once more, sign in to the AWS Management Console and open the Amazon Secrets Manager console here then make sure you choose the same AWS Region as that of the MySQL database

2. In the navigation pane, choose Secrets then Store a new secret on the top-right of the Secrets table to open the below page:

3. Secret type : Credentials for Amazon RDS database

4. User name : admin

5. Password : adminadmin

For steps 4 and 5, use the same username and password as the database.

6. Database : choose mydemodb DB instance and click Next

7. Secret name : demodb/dev, leave default options and click Next

8. Leave all the default options again and click Next to go to the Review page.

9. Click Store

10. Once the Secret is created, click on it to preview its details.

Create a programmatic IAM user

Note*: If you have already configured AWS credentials on your machine locally, please skip this entire section and go to **Create Spring Boot**.*

In order to user AWS Secrets we've created, we need an AWS IAM user with AdministratorAccess policy. Please follow these steps to create an Admin IAM User and configure your local machine.

Create a Spring Boot Project

For this lab, clone the project here and open it in your IDE, then follow the explanations.

1. Let's explore some core dependencies necessary for the project in the pom.xml file :

<!-- Spring Boot JPA dependency -->
<dependency>         
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-data-jpa</artifactId>
</dependency>
<!-- MySQL dependency -->
<dependency>
    <groupId>mysql</groupId>
    <artifactId>mysql-connector-java</artifactId>
    <scope>runtime</scope>
</dependency>
<!-- AWS Secrets Manager dependency -->
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-java-sdk-secretsmanager</artifactId>
    <version>1.11.355 </version>
</dependency>

2. The SecretValue Java class in utils package SecretValue.java class aims to map the Secret value key/value data (DB credentials) retrieved from AWS Secrets Manager into a java object for use in the data source.

public class SecretValue {
    private String username;
    private String password;
    private String engine;
    private String host;
    private String port;
    private String dbname;
    private String dbInstanceIdentifier;

    // Add Getters & Setters
}

3. The JavaConfig.java class In this class, the retrieval of the secret value we created in AWS Secrets Manager is implemented.

Line 41: the secret name created in AWS Secrets Manager

Line 42: the AWS Region where the secret is created

Test the REST API

Our REST API is ready, in this section, we'll test it with Postman.

1. Build the project

• At the root of the project, run the following command line: mvn clean package

• If everything is configured correctly, the result should look like this:

2. Run the project Please run the API and make the following API call:

• Open Postman

• Make a POST request : localhost:8080/api/team/2022

• Make a GET request : localhost:8080/api/team/2022

Congratulations! You are almost at the end of the project.

Bonus: Deploy the CRUD REST API on AWS Fargate

As in production, we need to deploy our REST API, I suggest you try creating a docker container for the API, pushing it to the Docker hub, and deploying it to Amazon ECS using the AWS Fargate deployment option. Please follow these simple steps outlined in this article..

Note*: To allow ECS Task to access the AWS Secrets Manager service, make sure you have **AmazonECSTaskExecutionRolePolicy and SecretsManagerReadWrite as Permissions policies for the Task role**.*

Cleanups

After testing the REST API locally and remotely, sign in to the AWS Management Console and perform cleanups:

• Delete the IAM user we created in the IAM console if needed

• Delete the Secret in the AWS Secrets Manager console

• Delete the MySQL database in the RDS console.

In this post, we showed how to create a Spring Boot CRUD REST API and how to manage Spring Boot MySQL connection. We also saw how to use AWS Secrets Manager in Spring Boot to protect database credentials in your REST API code. Your suggestions are welcome. Thanks for reading!

In this post, we will show how to quickly deploy a Spring Boot Application on Amazon ECS with AWS Fargate deployment option. AWS Fargate is a Serverless compute engine that can be used to launch and run containers without having to provision or manage EC2 instances.

In the next lines, we will :

• See how to create a Spring Boot REST API Docker image

• Go through how to push a containerized API on the docker repository and deploy this containerized API on AWS

• Create an ECS Cluster

• Create a Fargate compatible Task Definition

• Run the configured Task to make the application available online

Prerequisites

1. Have a Docker repository account

2. Install Docker Desktop on your local machine

3. Have an AWS account

Create a Spring Boot REST API

Through this section, instead of creating a Spring Boot Web application, we will create a Spring Boot Rest API for simplicity. Notice that the deployment process is the same even for Spring Boot Web App and Spring Boot REST API. For demonstration purposes, you can clone the Git hub repository here and open it in your favorite IDE.

Create a Docker container image for the Spring Boot Application

1. Create a Docker file

In the project root, create a docker file named: Dockerfile (with no file extension). Paste the below content:

FROM openjdk:11
COPY ./target/docker-demo-0.0.1-SNAPSHOT.jar docker-demo- 
0.0.1-SNAPSHOT.jar
CMD ["java","-jar","docker-demo-0.0.1-SNAPSHOT.jar"]
EXPOSE 8080

Line 1: Instruction to build docker image from openjdk:11 image

Line 2: Instruction to copy the jar file into the Docker container file system while building

Line 3: is a java command to launch the jar file while executing the container

Line 4: informs Docker that the container listens on 8080 port at runtime.

2. Build the Docker image

Open the terminal and execute the following docker command in the project root:

docker image build -t docker-demo .

You should have a result like this:

3. Test the docker image locally

Open the terminal and execute the following command:

docker container run --name dockerDemoApp -p 8080:8080 -d 
docker-demo

Go to Docker Desktop, you should see this:

You can then paste this link http://localhost:8080/api/ in the browser to get the following result :

4. Push Docker image into Docker hub repository

In order to push the Docker local image into the Docker hub repository, you just need to execute the following command line:

docker push xxx/docker-demo-app:latest

Make sure to replace xxx with your user name.

Deploy the Spring Boot REST API on AWS Fargate

In this section, we will work step by step to finally get the REST API online.

1. Create Amazon ECS Cluster

• Sign in to the AWS Console, and type ECS in the Search bar.

Click on Create Cluster

• Step 1: On Select cluster template step, select Networking only option and click on Next Step

• Step 2: Provide the Cluster name : Demo-cluster, check Create VPC option, leave all other default options and click on Create.

• Click on View Cluster, and the Demo-cluster details should look like this:

2. Create a Task Definition

On the left side, click Task Definitions and Create new Task Definition to access the Create new Task Definition page.

a. Step 1: Select launch type compatibility

• Select FARGATE then click on Next Step

b. Step 2: Configure task and container definitions

• Type the Task definition name : docker-demo-task
• Leave Task role as is (an IAM role for ECS Task definition will be created on your behalf )
• Select Linux as Operating system family
• Task execution role, leave Create new role option
• Task memory (GB) : 1GB
• Task CPU (vCPU) : 0.5vCPU
• Click on Add Container, and the information below:

-- Container name : dockerDemoApp

-- Image : xxx/docker-demo-app:latest, the Docker hub image repository (xxx : your Docker hub user name)

-- Memory Limits (MiB) : Soft limit : 128

-- Port mappings : 80 -> tcp and 8080 -> tcp -- Click on Add to navigate back to Create new Task Definition page

• Leave all other options and click on Create

• Click on View task definition to see the created task definition details.

3. Run the Task Definition

In this last section, we are going to run our Docker container image.

Step 1

In the Task Definition: docker-demo-task:1 page, click on Actions then Run Task, the Run Task page will open.

Step 2

• Launch type : FARGATE
• Operating system family : Linux
• Task Definition : Familly -> docker-demo-task / Revision -> 1
• Platform version : LATEST
• Cluster : Demo-cluster
• Number of tasks : 1
• Cluster VPC : select your VPC
• Subnets : Choose un subnet
• Security groups : click on Edit to modify the default security group as follow :

-- Assigned security groups : Create new security group

-- Security group name : docker-demo-sg

-- Inbound rules for security group: Choose All Traffic Type and Anywhere Source

-- Click on Save, and you will be redirected to the Run Task page.

• Auto-assign public IP : ENABLED

• Leave all other default options and click on Run Task.

Access Spring Boot REST API via public address

Now that the deployed API's container is running, let's try to access it through a public IP address.

Step 1: Task details

• In the Demo-cluster details page, go to Tasks tab.

• In the listed tasks, click on the Task whose Task definition column is docker-demo-task:1, and the Task details page should open.

Step 2: Task public IP address

• In the Task details page, copy the Public IP address

• Open a browser or Postman, paste the IP address, and append the port and /api/ to see the magic happen!

4. Clean up

• In the Task Details page, click on Stop
• In the Demo-cluster page, click on Delete Cluster then follow the instructions to delete the Cluster

In Summary

Through this post, we saw how to easily and quickly deploy a Spring Boot Application on AWS using AWS Fargate by creating a Spring Boot REST API Docker container image, pushing it on the Docker hub repository, creating and configuring Amazon ECS Cluster and Task definition witch helped us to deploy and run our REST API container image on AWS Cloud. Thanks for the reading.

Usually, implementing Spring boot bearer token functionality for Rest API requires many lines of code, hours, and the need for user management. However, using Spring boot AWS authentication thanks to Amazon Cognito, things become very simple and very very fast. We no longer need to manage users, Amazon Cognito user pool takes care of that. Cognito also allows us to share users between many Rest APIs and front-ends (web, mobile).

Create Amazon Cognito User Pool

1. Sign in into Amazon console, and then search for: Cognito.

2. Click on Create User Pool.

3. In the Configure sign-in experience step, check User name, Email, and Allow users to sign in with a preferred user name options then click on Next.

4. In the Configure security requirements step, leave all the default options except MFA enforcement where you should choose No MFA instead of Require MFA - Recommended, then click on Next.

5. Step 3 : Configure sign-up experience, leave all default options, and click on Next.

6. Step 4: Configure message delivery, choose Send email with Cognito for Email provider and leave all other default options then click on Next.

7. Step 5: Integrate your app, provide the User pool name : Demo-user-pool, App client name: Dockerdemo-app, leave other default options, and click Next.

8. Step 6: Review and click on Create User Pool.

9. In the details page of the created user pool, click on App Integration tab -> Actions -> Create Cognito Domain and provide the domain name then click Create Cognito Domain.

10. Again, in the App Integration tab, navigate to the App client list section and click on Dockerdemo-app to preview its details.

11. In the App client details, scroll down to the Pinpoint analytics section and click on Edit, the Edit Hosted UI page will open.

12. In the Edit Hosted UI page, provide the Allowed callback URLs : https://example.com, check Cognito user pool in the Identity providers section, check all OpenID Connect scopes options then click Save changes.

13. Back to the App client details, the Pinpoint analytics section should look like the image below:

14. Make sure to save the Cognito domain from the Domain section, and the Client ID for the created client App from the App client list section.

Create Spring boot Rest API

In this section, we will create a spring boot Rest API. For demonstration purposes, you can clone the Git hub repository here and open it in your favorite IDE.

The idea here is to implement Spring Security Rest API authentication with OAuth 2.0 JWT Bearer Tokens. Instead of implementing the JWT authentication tokens generation mechanism, we will use Amazon Cognito to manage it.

1. Provide the needed dependencies in the pom.xml file for Spring Security OAuth 2.0 support

    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-security</artifactId>
    </dependency>
   
    <dependency>             
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-oauth2-resource- 
   server</artifactId>
    </dependency>
   

2. In the application.yaml file, specify the Authorization Server:

    spring:
      security:
        oauth2:
          resourceserver:
            jwt:
              issuer-uri: https://cognito-idp.[AWS REGION].amazonaws.com/[USER_POOL_ID]
   

3. Create a security configuration file.

    package com.wilkom.dockerdemo.security;
   
    import org.springframework.context.annotation.Bean;
    import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity;
    import org.springframework.security.config.annotation.web.builders.HttpSecurity;
    import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
    import org.springframework.security.web.SecurityFilterChain;
   
    @EnableWebSecurity // Enable Spring Security’s web 
      //security support
    @EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = true) // To configure method-level security
    public class SecurityConfig {
   
        @Bean
        public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
   
            http.cors().and().csrf().disable()
                .authorizeRequests(expressionInterceptUrlRegistry -> expressionInterceptUrlRegistry
                        .anyRequest().authenticated())
                .oauth2ResourceServer().jwt();
            return http.build();
        }
    }
   

   In the configuration class above, we have made each endpoint accessible only by OAuth 2.0 authenticated requests. That's all we have to do in our API Rest backend.

Test the Rest API

We will use Postman to test our Rest API.

1. Signup user into the Amazon Cognito

• Open Postman and provide values from Amazon Cognito User provider settings:

  2/ Callback URL: https://example.com (make sure to provide the exact callback URL you set in the Cognito)

  3/ Auth URL: https://xxxxx.auth.us-east-1.amazoncognito.com/login (remember to append /login)

  4/ Access Token URL : https://xxxxx.auth.us-east-1.amazoncognito.com/oauth2/token (remember to append /oauth2/token)

  5/ Client ID : Dockerdemo-app App Client ID

• Then click on Get New Access Token at the bottom, and the Sign-in screen will open, click on Sign up link at the bottom the get the signup screen as follow:

  Enter the user name, valid email and password then click on Sign-up.

• The verification code screen should appear, open the valid email box to get the verification code:

• If the code verification is successful, a token will be generated, click on Use Token:

2. Make API call

• Now, you can run the Spring boot app.

• Go to Postman, enter a GET endpoint URL,

localhost:8080/api/

• Make sure the token is in use in the Authorization OAuth 2.0 tab and click on Send:

PS: In a real project, the Signup and Sign-in processes will be implemented in the front-end apps, please see this guide to do so.

As you can see, Amazon Cognito is an amazing AWS service that simplifies Spring boot backend Rest API user management.

Thanks for reading.

In this previous tutorial, we secured our backend RESTful API using Spring Security and JWT. Now we are going to handle errors/exceptions in the RESTful API.

Problem

Until now, all eventual error messages thrown in our RESTful API are not user-friendly. For example, when you try to log in with invalid credentials, you should have a similar message in Postman:

In the following lines, we'll use one of the smart solutions Spring provides to make the API throw understandable error messages.

Solution: Spring Global Exception Handling

1 - ExceptionResponse.java

This java class will be the custom error message class to return by the API when an error occurs. Create it in the com.codeurinfo.easytransapi.exception package.

package com.codeurinfo.easytransapi.exception;

import com.fasterxml.jackson.annotation.JsonFormat;
import java.time.LocalDateTime;
import org.springframework.http.HttpStatus;

public class ExceptionResponse {

  private HttpStatus status;

  @JsonFormat(shape = JsonFormat.Shape.STRING, pattern = "dd-MM-yyyy hh:mm:ss")
  private LocalDateTime timestamp;

  private String message;
  private String description;

  public ExceptionResponse() {
    this.timestamp = LocalDateTime.now();
  }

  public ExceptionResponse(HttpStatus status) {
    this();
    this.status = status;
    this.message = "An error occured";
  }

  public ExceptionResponse(String message) {
    this();
    this.message = message;
  }

  public ExceptionResponse(HttpStatus status, String message, Throwable ex) {
    this();
    this.status = status;
    this.message = message;
    this.description = ex.getLocalizedMessage();
  }

  public LocalDateTime getTimestamp() {
    return this.timestamp;
  }

  public void setTimestamp(LocalDateTime timestamp) {
    this.timestamp = timestamp;
  }

 // getters and setters

}

2 - GlobalControllerExceptionHandler.java

Let's create this class in com.codeurinfo.easytransapi.exception package to handle all the errors in the RESTful API.

package com.codeurinfo.easytransapi.exception;

import io.jsonwebtoken.ExpiredJwtException;
import org.springframework.dao.DataIntegrityViolationException;
import org.springframework.http.HttpStatus;
import org.springframework.security.access.AccessDeniedException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;
import org.springframework.web.bind.annotation.RestControllerAdvice;

@RestControllerAdvice
public class GlobalControllerExceptionHandler {

  @ExceptionHandler({ DataIntegrityViolationException.class })
  @ResponseStatus(value = HttpStatus.CONFLICT)
  public ExceptionResponse handleDIVException(
    DataIntegrityViolationException e
  ) {
    return new ExceptionResponse(
      HttpStatus.CONFLICT,
      "Data integrity error.",
      e
    );
  }

  @ExceptionHandler({ Exception.class })
  @ResponseStatus(value = HttpStatus.INTERNAL_SERVER_ERROR)
  public ExceptionResponse handleException(Exception e) {
    return new ExceptionResponse(
      HttpStatus.INTERNAL_SERVER_ERROR,
      e.getLocalizedMessage(),
      e
    );
  }

  @ExceptionHandler({ AccessDeniedException.class })
  @ResponseStatus(value = HttpStatus.FORBIDDEN)
  public ExceptionResponse handleForbiddenException(AccessDeniedException e) {
    return new ExceptionResponse(
      HttpStatus.FORBIDDEN,
      e.getLocalizedMessage(),
      e
    );
  }


}

• Spring @RestControllerAdvice annotation is used on a global class to make all its methods annotated with @ExceptionHandler be accessible across all the controllers in the RESTful API.

• @ExceptionHandler annotation is used upon methods to handle specific Exceptions.

• Thus, we use @ExceptionHandler({ DataIntegrityViolationException.class }) on the handleDIVException method to handle all DataIntegrityViolation Exceptions occurred in @RepositoryRestResource annotated repository interfaces.

• @ResponseStatus is used to send the corresponding HTTP status code for the JSON response.

• For unknown exceptions handling, we use @ExceptionHandler({ Exception.class }) on the handleException method and provide a HttpStatus.INTERNAL_SERVER_ERROR status code to return.

• Similarly, we use @ExceptionHandler({ AccessDeniedException.class }) and provide HttpStatus.FORBIDDEN on the handleForbiddenException method to handle URL access denied exception.

3 - Tests

1 - Log in with bad credentials

• POST request : http://localhost:8000/api/auth/login
• Body:

{
    "userName": "user",
    "password": "user1"
}

• Response

2 - Try to access an unauthorized resource

Suppose you logged in with user/user good credentials, following our API logic, a user with username user is not allowed to make a routeByName search request

• POST request: http://localhost:8000/api/routes/search/routesByName?name=Rex-Adidogome
• Provide Authorization token value (token generated when log in was successful)
• Response

In the next post, we'll add new features to our EasyTrans app. Hope you learned something new. If so, don't forget to hit the Like button and subscribe to this blog to be up to date with new posts.

We added some security features to our REST API in previous post thanks to Spring Security and JWT. In this tutorial, we'll be validating token and secure the API endpoints.

Overview

Here are what we'll be doing in this post:

• JWT token validation

• How to grant/deny access to Spring Data REST Repository method

JWT Token validation

In order to catch and validate token coming from a client, we have to create a request Filter class extending the Spring Web Filter OncePerRequestFilter class. For any incoming request, this Filter class will be executed. It checks if the request has a valid JWT token. If it has a valid JWT Token, then it sets the authentication in context to specify that the current user is authenticated.

Create a class, AuthRequestFilter.java in security.filter package.

package com.codeurinfo.easytransapi2.security.filter;

import com.codeurinfo.easytransapi2.security.UserDetailsImpl;
import com.codeurinfo.easytransapi2.security.UserDetailsServiceImpl;
import com.codeurinfo.easytransapi2.security.util.JwtUtil;
import java.io.IOException;
import javax.servlet.FilterChain;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

@Component
public class AuthRequestFilter extends OncePerRequestFilter {

  @Autowired
  private UserDetailsServiceImpl userDetailsService;

  @Autowired
  private JwtUtil jwtUtil;

  @Override
  protected void doFilterInternal(
    HttpServletRequest request,
    HttpServletResponse response,
    FilterChain chain
  )
    throws ServletException, IOException {
    final String authorizationHeader = request.getHeader("Authorization");

    String username = null;
    String jwt = null;

    if (
      authorizationHeader != null && authorizationHeader.startsWith("Bearer ")
    ) {
      // get the jwt token
      jwt = authorizationHeader.substring(7);// authorizationHeader is like "Bearer jwttoken", so 7 caracters before jwttoken
      username = jwtUtil.extractUsername(jwt);// get username for the given token
    }

    if (
      username != null &&
      SecurityContextHolder.getContext().getAuthentication() == null
    ) {
      UserDetailsImpl userDetails =
        (UserDetailsImpl) this.userDetailsService.loadUserByUsername(username);

      if (jwtUtil.validateToken(jwt, userDetails)) {
        UsernamePasswordAuthenticationToken usernamePasswordAuthenticationToken = new UsernamePasswordAuthenticationToken(
          userDetails,
          null,
          userDetails.getAuthorities()
        );
        usernamePasswordAuthenticationToken.setDetails(
          new WebAuthenticationDetailsSource().buildDetails(request)
        );
        SecurityContextHolder
          .getContext()
          .setAuthentication(usernamePasswordAuthenticationToken);
      }
    }
    chain.doFilter(request, response);
  }
}

Then, let's add this Filter to the SecurityConfig.java class in the configure method like this:

@Override
  protected void configure(HttpSecurity http) throws Exception {
    http
      .csrf()
      .disable()
      .authorizeRequests()
      .antMatchers("/api/auth/**").permitAll() // Grant access to every /api/auth based url
      .anyRequest().authenticated() // All other based url wil be allowed if authenticated
      .and()
      .sessionManagement()
      .sessionCreationPolicy(SessionCreationPolicy.STATELESS);//Force server not to never create an HttpSession
    http.addFilterBefore(
      authRequestFilter,
      UsernamePasswordAuthenticationFilter.class
    );
  }

Reminder: You must first declare authRequestFilter as a variable in the SecurityConfig.java class

@Autowired
  private AuthRequestFilter authRequestFilter;

At this point, our REST API is almost secured. Let's run and test it in Postman.

1 . Make a simple GET request

http://localhost:9000/api/routes

As you can see, we have an Access Denied error.

2 . Make a login POST request

http://localhost:9000/api/auth/login

Remember to use the same credentials you set up for users in the preload DatabaseLoader.java If a valid username/password is provided, a JWT token is returned.

3 . Try a simple GET request again

http://localhost:9000/api/routes

• Before execute the GET request in Postman, copy the JWT token returned in step 2
• Open Header tab, add a key : Authorization, type the value: Bearer yourCopiedToken
• Execute the request, you might have a good result as below.

From now on, you must add the Authorization key and value in the Header tab before executing any other request apart from the login

4 . Make a POST request to save a route

http://localhost:8000/api/routes

• Open the Header tab and Authorization key and value as proceed in step 3
• Open the Body tab to add your payload data

{
    "name": "Rex-Adidogome",
    "start": "Grand marche - Rex",
    "terminus": "Adidogome"
}

• Then execute to have a result as below:

Congratulations! You configured Spring Security and JWT to secure a REST API so that only authenticated consumers can access endpoints for requests.

But ... in the real world, every logged-in user should have the ability to access some endpoints while others no. Let's strengthen our API security.

Spring Security: method level security

Remember, we added @EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = true) annotation to the SecurityConfig.java class. This annotation enables method level security.

In the RouteRepository.java class, suppose we want only ROLE_ADMIN users to have the ability to access the findRoutesByName method.

Add @PreAuthorize("hasRole('ROLE_ADMIN')") annotation to that method to grant access to ROLE_ADMIN users. Updated code of RouteRepository.java:

package com.codeurinfo.easytransapi.repository;

import com.codeurinfo.easytransapi.model.Route;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;
import org.springframework.data.rest.core.annotation.RestResource;
import org.springframework.security.access.prepost.PreAuthorize;

@RepositoryRestResource
public interface RouteRepository extends JpaRepository<Route, Long> {

  @PreAuthorize("hasRole('ROLE_ADMIN')")
  @RestResource(path = "routesByName")
  Optional<Route> findRoutesByName(@Param("name") String name);
}

Let's test the API again.

1 . Make sure you preloaded two different users, one with the ROLE_ADMIN and the other no.

2 . Make a POST request to log in with the admin user credentials, then copy the token

3 . Try to make a POST request to save route, GET request to search route, etc. using the Authorization token in Header tab, you should have successful responses.

4 . Now login with the simple user (who had no ROLE_ADMIN role) credentials and copy the token

5 . Using Authorization token in Header tab, all POST and GET methods should be successful except the GET request for search route!

http://localhost:9000/api/routes/search/routesByName?name=Rex-Adidogome

We got a Forbidden error stating that the logged-in user is not allowed to query this method.

In the next post, we will be adding new features to our EasyTrans app. Hope you learned something new. If so, don't forget to hit the Like button and subscribe to this blog to be up to date with new posts.

In the previous tutorial, we have set up the CRUD operations in our REST API. In this tutorial we're going to secure the REST API using Spring security and Json Web Token a.k.a JWT. Reminder : this tutorial is part of series covering a full-stack app development.

What we'll cover here

• How to customize Spring security to fetch users from database
• How to implement JWT token management in Spring boot REST API
• How to expose a REST POST API /login to generate a JWT token

User entity and repository

We are going to create an enum class to manage static roles for simplicity purpose. Let's create a package: security.model, then, in the model package create ERole.java class as follow:

package com.codeurinfo.easytransapi.security.model;

public enum ERole {
  ROLE_ADMIN,
  ROLE_USER,
}

Here, we have two roles: ROLE_ADMIN for administrator role and ROLE_USER for a simple user role. you can add more roles as needed.

Once roles class coded, we gonna create a custom user class in the same package as ERole.java, we'll annotated it as an entity.

package com.codeurinfo.easytransapi.security.model;


import java.util.Objects;
import java.util.Set;

import javax.persistence.ElementCollection;
import javax.persistence.Entity;
import javax.persistence.EnumType;
import javax.persistence.Enumerated;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "users")
public class User {

  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private Long id;

  private String userName;
  private String password;
  private String name;
  @ElementCollection (targetClass = ERole.class)
  @Enumerated(EnumType.STRING)
  private Set<ERole> roles;

  public User() {}

  public User(
    String userName,
    String password,
    String name,
    Set<ERole> roles
  ) {
    this.userName = userName;
    this.password = password;
    this.name = name;
    this.roles = roles;
  }
/**
   * getters and setters
   */

@ElementCollection is used to map the ERole.java enum list which is not an entity while @Enumerated(EnumType.STRING), especially ( EnumType.STRING ) tells JPA to persist Enum names instead of their index numbers in the DB.

Now, let's create the repository to manage the User.class in a new package : security.repository .

package com.codeurinfo.easytransapi.security.repository;

import com.codeurinfo.easytransapi.security.model.User;

import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource
public interface UserRepository extends JpaRepository<User, Long> {
  Optional<User> findByUserName(String userName);
}

findByUserName is a query method to fetch user by a given userName. You can read more about Spring Data JPA query methods here.

User entity is now ready to be used, in the following sections, we are going to implement very interesting spring security features.

Dependency management

Open the pom.xml file and add following dependencies:

<!-- Spring security -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>

        <!-- JWT  -->
        <dependency>
            <groupId>io.jsonwebtoken</groupId>
            <artifactId>jjwt</artifactId>
            <version>0.9.1</version>
        </dependency>

        <!-- very important while using java 11 and above -->
        <dependency>
            <groupId>javax.xml.bind</groupId>
            <artifactId>jaxb-api</artifactId>
            <version>2.3.1</version>
        </dependency>

Customize Spring security to fetch user from DB (H2 database)

In order to use custom user management in Spring Security, we must first implement Spring security core UserDetails interface to map our custom User detail class to Spring security User class and then implement Spring security core UserDetailsService interface so that Spring can query users from the DB.

Within security package, create a class named UserDetailsImpl.java :

package com.codeurinfo.easytransapi.security;

import com.codeurinfo.easytransapi.security.model.User;
import com.fasterxml.jackson.annotation.JsonIgnore;
import java.util.Collection;
import java.util.List;
import java.util.Objects;
import java.util.stream.Collectors;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

public class UserDetailsImpl implements UserDetails {

  private Long id;

  private String username;

  @JsonIgnore
  private String password;

  private Collection<? extends GrantedAuthority> authorities;

  public UserDetailsImpl(
    Long id,
    String username,
    String password,
    Collection<? extends GrantedAuthority> authorities
  ) {
    this.id = id;
    this.username = username;
    this.password = password;
    this.authorities = authorities;
  }

  /**
   * Static method to expose UserDetailsImpl object created by given user
   * @param user
   * @return UserDetailsImpl object
   */
  public static UserDetailsImpl build(User user) {
    // Map user roles list to Spring Security GrantedAuthority list
    List<GrantedAuthority> authorities = List
      .copyOf(user.getRoles())
      .stream()
      .map(role -> new SimpleGrantedAuthority(role.name()))
      .collect(Collectors.toList());

    return new UserDetailsImpl(
      user.getId(),
      user.getUserName(),
      user.getPassword(),
      authorities
    );
  }

  @Override
  public Collection<? extends GrantedAuthority> getAuthorities() {
    return authorities;
  }

  public Long getId() {
    return id;
  }

  @Override
  public String getPassword() {
    return password;
  }

  @Override
  public String getUsername() {
    return username;
  }

  @Override
  public boolean isAccountNonExpired() {
    return true;
  }

  @Override
  public boolean isAccountNonLocked() {
    return true;
  }

  @Override
  public boolean isCredentialsNonExpired() {
    return true;
  }

  @Override
  public boolean isEnabled() {
    return true;
  }

  @Override
  public boolean equals(Object o) {
    if (this == o) return true;
    if (o == null || getClass() != o.getClass()) return false;
    UserDetailsImpl user = (UserDetailsImpl) o;
    return Objects.equals(id, user.id);
  }
}

Now, we can implement the UserDetailsService. Create UserDetailsServiceImpl.java class in security package as follow:

package com.codeurinfo.easytransapi.security;

import com.codeurinfo.easytransapi.security.model.User;
import com.codeurinfo.easytransapi.security.repository.UserRepository;
import java.util.ArrayList;

import javax.transaction.Transactional;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.security.core.userdetails.UserDetails;
import org.springframework.security.core.userdetails.UserDetailsService;
import org.springframework.stereotype.Service;

@Service
public class UserDetailsServiceImpl implements UserDetailsService {

  @Autowired
  private UserRepository userRepository;

  /**
   * Override this method to fetch user by userName from th db
   * using the UserRepository
   * @Transactional is used to manage User & roles collection lazy loading
   */
  @Override
  @Transactional
  public UserDetails loadUserByUsername(String userName) {

    User user = userRepository.findByUserName(userName).orElse(null);

    return UserDetailsImpl.build(user);
  }
}

Create a JWT utility class

In the security package, create a package util and create JwtUtil.class.

package com.codeurinfo.easytransapi.security.util;

import com.codeurinfo.easytransapi.security.UserDetailsImpl;
import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.function.Function;
import org.springframework.stereotype.Service;

@Service
public class JwtUtil {

  // Give a secret key for JWT token generating & validation
  private String SECRET_KEY = "secret";

  // get username from the provided token
  public String extractUsername(String token) {
    return extractClaim(token, Claims::getSubject);
  }

  //get the token expiration time
  public Date extractExpiration(String token) {
    return extractClaim(token, Claims::getExpiration);
  }

  // get token infos
  public <T> T extractClaim(String token, Function<Claims, T> claimsResolver) {
    final Claims claims = extractAllClaims(token);
    return claimsResolver.apply(claims);
  }

  private Claims extractAllClaims(String token) {
    return Jwts
      .parser()
      .setSigningKey(SECRET_KEY)
      .parseClaimsJws(token)
      .getBody();
  }

  private Boolean isTokenExpired(String token) {
    return extractExpiration(token).before(new Date());
  }

  public String generateToken(UserDetailsImpl userDetails) {
    Map<String, Object> claims = new HashMap<>();
    return createToken(claims, userDetails.getUsername());
  }

  /**
   * Generate a token for the provided subject (username)
   * @param claims
   * @param subject
   */
  private String createToken(Map<String, Object> claims, String subject) {
    return Jwts
      .builder()
      .setClaims(claims)
      .setSubject(subject)
      .setIssuedAt(new Date(System.currentTimeMillis()))
      .setExpiration(new Date(System.currentTimeMillis() + 1000 * 60 * 60 * 10)) //Expiration in 36,000,000 ms (10 hours)
      .signWith(SignatureAlgorithm.HS256, SECRET_KEY) // signing with HS256 algorythm
      .compact();//According to JWS Compact Serialization(https://tools.ietf.org/html/draft-ietf-jose-json-web-signature-41#section-3.1)
      //   compaction of the JWT to a URL-safe string 
  }

  /**
   * Validate token
   */
  public Boolean validateToken(String token, UserDetailsImpl userDetails) {
    final String username = extractUsername(token);

    return (
      username.equals(userDetails.getUsername()) && !isTokenExpired(token)
    );
  }
}

Providing a /login REST API POST endpoint

In this section, we'll be coding a controller to expose an authentication endpoint to our REST API.

Let's create AuthenticationRequest.java class in security.model package in order to hold the username and password coming from our REST API consumer's http request payload.

package com.codeurinfo.easytransapi.security.model;

import java.util.Objects;

public class AuthenticationRequest {

  private String userName;
  private String password;

  public AuthenticationRequest() {}

  public AuthenticationRequest(String userName, String password) {
    this.userName = userName;
    this.password = password;
  }

 // Getters and setters

}

Create another class named AuthenticationResponse.java to send the response containing the JWT token to the client.

package com.codeurinfo.easytransapi.security.model;

import java.util.Objects;

public class AuthenticationResponse {

  private String jwt;

  public AuthenticationResponse() {}

  public AuthenticationResponse(String jwt) {
    this.jwt = jwt;
  }

  // getters and setters

To expose a /login endpoint that will accept an AuthenticationRequest object and return an AuthenticationResponse object to the client, let's create AuthController.java class in the security package.

package com.codeurinfo.easytransapi;

import com.codeurinfo.easytransapi.security.UserDetailsImpl;
import com.codeurinfo.easytransapi.security.UserDetailsServiceImpl;
import com.codeurinfo.easytransapi.security.model.AuthenticationRequest;
import com.codeurinfo.easytransapi.security.model.AuthenticationResponse;
import com.codeurinfo.easytransapi.security.repository.UserRepository;
import com.codeurinfo.easytransapi.security.util.JwtUtil;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.http.ResponseEntity;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.context.SecurityContextHolder;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AuthController {

  @Autowired
  private AuthenticationManager authenticationManager;

  @Autowired
  private UserDetailsServiceImpl userDetailsService;

  @Autowired
  private JwtUtil jwtUtil;

  @PostMapping("/api/auth/login")
  public ResponseEntity createAuthenticationToken(
    @RequestBody AuthenticationRequest request
  )
    throws Exception {
    Authentication authentication = null;
    try {
      // Use AuthenticationManager to verify the provided username/password
      authentication =
        authenticationManager.authenticate(
          new UsernamePasswordAuthenticationToken(
            request.getUserName(),
            request.getPassword()
          )
        );
    } catch (Exception exception) {
      throw new Exception("Incorrect username or password");
    }
    //if username/password valid, put the Authentication created object in the SecurityContextHolder's context
    SecurityContextHolder.getContext().setAuthentication(authentication);

    // Retrieve the user from the UserDetailsServiceImpl
    final UserDetailsImpl userDetails = (UserDetailsImpl) userDetailsService.loadUserByUsername(
      request.getUserName()
    );

    // Generate the token from the JWT util class
    String jwt = jwtUtil.generateToken(userDetails);

    // Send AuthenticationResponse response to client
    return ResponseEntity.ok(new AuthenticationResponse(jwt));
  }
}

We can now create SecurityConfig.java class, a configuration class to extends WebSecurityConfigurerAdapter class.

package com.codeurinfo.easytransapi.security;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.security.authentication.AuthenticationManager;
import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.method.configuration.EnableGlobalMethodSecurity;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
import org.springframework.security.config.annotation.web.configuration.WebSecurityConfigurerAdapter;
import org.springframework.security.config.http.SessionCreationPolicy;
import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.security.web.authentication.UsernamePasswordAuthenticationFilter;

@EnableWebSecurity // Enable Spring Security’s web security support
@EnableGlobalMethodSecurity(securedEnabled = true, prePostEnabled = true) //To configure method-level security
public class SecurityConfig extends WebSecurityConfigurerAdapter {

  @Autowired
  private UserDetailsServiceImpl customUserDetailsService;


  @Override
  protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    auth.userDetailsService(customUserDetailsService).passwordEncoder(passwordEncoder());
  }

  @Override
  protected void configure(HttpSecurity http) throws Exception {
    http
      .csrf()
      .disable()
      .authorizeRequests()
      .antMatchers("/api/auth/**").permitAll() // Grant access to every /api/auth based url
      .anyRequest().authenticated() // All other based url wil be allowed if authenticated
      .and()
      .sessionManagement()
      .sessionCreationPolicy(SessionCreationPolicy.STATELESS);//Force server not to never create an HttpSession

  }

  @Override
  @Bean
  public AuthenticationManager authenticationManagerBean() throws Exception {
    return super.authenticationManagerBean();
  }

  @Bean
  public PasswordEncoder passwordEncoder() {
    return new BCryptPasswordEncoder();
  }
}

You can learn more about the SecurityConfig.java class here.

Once more class to code before we can test our API. For simplicity purpose, we'll be preloading users into the database and try to log in with their corresponding cridentials.

Thanks to Spring boot's CommandLineRunner interface, we can create a preload class DatabaseLoader.java like this:

package com.codeurinfo.easytransapi;

import com.codeurinfo.easytransapi.security.model.ERole;
import com.codeurinfo.easytransapi.security.model.User;
import com.codeurinfo.easytransapi.security.repository.UserRepository;
import java.util.Arrays;
import java.util.Set;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.CommandLineRunner;
import org.springframework.security.crypto.password.PasswordEncoder;
import org.springframework.stereotype.Component;

@Component
public class DatabaseLoader implements CommandLineRunner {

  @Autowired
  UserRepository userRepository;

  @Autowired
  PasswordEncoder encoder;

  @Override
  public void run(String... args) throws Exception {
    // remember we use PasswordEncoder to configure the AuthenticationManagerBuilder in the SecurityConfig class
    // thus you must encode  pwd using the same encoder (BCryptPasswordEncoder) before persit
    String pwd1 = encoder.encode("will");
    String pwd2 = encoder.encode("user");
    userRepository.save(
      new User(
        "will",
        pwd1,
        "Wilson",
        Set.copyOf(Arrays.asList(ERole.ROLE_ADMIN, ERole.ROLE_USER))
      )
    );
    userRepository.save(
      new User(
        "user",
        pwd2,
        "Adjowa",
        Set.copyOf(Arrays.asList(ERole.ROLE_USER))
      )
    );
  }
}

Run the project, go to Postman and make a POST request to this endpoint :

http://localhost:8000/api/auth/login

You must have a result like this:

Voila, through our REST API we can log in once and get a token to use in http request headers for the next 10 hours. In the next tutorial, we'll see how to validate client request header token and how to grant access to endpoints according to users roles.

Hope you learned something new. If so, don't forget to hit the Like button and subscribe to this blog to be up to date with new posts.

We will learn how to :

• Create entity

• Create repository and expose it as REST endpoints without using any other controller component

• Create queries

• Custom query url
• Custom REST API base path

Entity & repository creation

Create a package named : model, and create a class: Route.java such as shown below:

package com.codeurinfo.easytransapi.model;

import java.util.Objects;
import javax.persistence.Column;
import javax.persistence.Entity;
import javax.persistence.GeneratedValue;
import javax.persistence.GenerationType;
import javax.persistence.Id;
import javax.persistence.Table;

@Entity
@Table(name = "routes")
public class Route {

  @Id
  @GeneratedValue(strategy = GenerationType.AUTO)
  private Long id;

  @Column(unique = true)
  private String name;

  private String start;
  private String terminus;

public Route() {}

  public Route(String name, String start, String terminus) {
    this.name = name;
    this.start = start;
    this.terminus = terminus;
  }

/**
Getters and Setters
*/

}

A simple class like that.

@Entity annotation is to tell database that this class is going to be an entity whereas @Table is used to give the custom name for the corresponding table in the DB. You can visit this blog for more information about these two annotations. We add a constraint @Column(unique = true) to avoid name duplication.

Next, we're going to create the repository, so create a package named: repository in which you create a class: RouteRepository.java:

package com.codeurinfo.easytransapi.repository;

import com.codeurinfo.easytransapi.model.Route;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;

@RepositoryRestResource
public interface RouteRepository extends JpaRepository<Route, Long> {
  Optional<Route> findRoutesByName(@Param("name") String name);
}

• We use @RepositoryRestResource instead of @Repository because it directly exposes the repository interface as a REST endpoint, so there would be no need for another REST controller like in our case.

Now, our backend REST API is ready! Let's test it using Postman.

1. Run the main class (EasytransApiApplication.java in our case)

2. Got to Postman and make a http GET request against this url : http://localhost:9000/routes

As result, you'll notice that routes array is empty, that's right because we have no records persisted; also Spring Data Rest generated useful links through "_links" object. We'll later make use of "http://localhost:9000/routes/search" for different seach queries

3 . In the Postman again, let's make Http POST request against this url: http://localhost:9000/routes In Body tab, select raw and JSON, then past the body below:

{
    "name": "Rex-Adetikope",
    "start": "Grand marche - Rex",
    "terminus": "Adetikope"
}

Clic Send to persist the data.

4 . Let's try our previous GET request against : http://localhost:9000/routes Now the routes array contains the persited data.

5 . Now that our REST API allows us to list routes and to persist some route objects, let's make search queries.

• Find a specific route providing its name in the GET request :

  http://localhost:9000/routes/search/findRoutesByName?name=Rex-Adetikope
  

• Notice, after the search url provided by Spring Data Rest, we add the query method signature (findRoutesByName) followed by the attribute specified in the @Param, which here is name.

Search url customization

Instead of using findRoutesByName in the search url, let's use a shorter name: routesByName .

To do so, go to the repository interface and add the annotation @RestResource(path = "routesByName"), our interface must look like this:

package com.codeurinfo.easytransapi.repository;

import com.codeurinfo.easytransapi.model.Route;
import java.util.Optional;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.repository.query.Param;
import org.springframework.data.rest.core.annotation.RepositoryRestResource;
import org.springframework.data.rest.core.annotation.RestResource;

@RepositoryRestResource
public interface RouteRepository extends JpaRepository<Route, Long> {
  @RestResource(path = "routesByName")
  Optional<Route> findRoutesByName(@Param("name") String name);
}

Save and make a GET request against this url:

http://localhost:9000/routes/search/routesByName?name=Rex-Adetikope

As you can see we have the expected result using routesByName instead of findRoutesByName.

Setting up a base path

In real project, most REST API root path begin with domain/api/path-to-resources, but as you can see, we directely call path-to-resources after the domain name.

To add the /api before any path-to-resource, open the application.yml file and add a spring base-path key and it's value like this:

spring:
  data:
    rest:
      base-path: /api

Save the yml file, try one of the pervious GET request, you we'll notice a 404 resource not found error.

This because from now, our REST API will be consumed using a base path /api/ before any other resource-path. So: http://localhost:9000/routes -> http://localhost:9000/api/routes etc.

Here is ! Congratulations you have built a basic Java Spring Boot REST API, hope you have learned something new. If so, don't forget to hit the Like button and subscribe to this blog to be notified of new posts.

In the next article, we will add new features to our EasyTrans app. Thank you for being part of this fullStack Java & React developer journey!

There are many tutorials dealing with topics such as spring boot, react.js, react native, etc. So it's usually a challenge to make a tutorial about these themes. Fortunately, most of these tutorials are chunks of code, which can be a trap for beginners when it comes to joining them. So in this series, we are going to learn how to join pieces of code to make a really beautiful project. We think this will help someone on their developer journey!

Project Architecture

Project description

We'll build a transport company app, for this purpose we'll call it: EasyTrans App.

1. Backend : API EasyTrans-api

Technical specifications: Spring boot, Spring Data REST

2. Mobile App: EasyTrans-app

Technical specifications: React Native

In the next tutorials, we'll build each of these modules and host them on AWS Cloud for production.

In this tutorial, we'll set up the backend. What you'll learn here are:

• How to initialize a Spring boot app using the official Spring boot initializer and
• How to customize a spring boot app port.

Project set up

Our backend API will be named : Easytrans-api. Let's use Spring initializer to initalize the project.

Initialize the project

1. Go to : https://start.spring.io/
2. Choose Maven Project , language Java, Spring boot version (2.5.2 while I am writing this article)
3. In the Project Metadata section, type :

• Group name : com.codeurinfo; (reminder, conventionally, a maven group id is the project reverse domain name, here our domain name is : codeurinfo.com)
• Artifact : easytrans-api
• Name : easytrans-api
• Description : a beautifull description of yours
• Package name : com.codeurinfo.easytransapi
• Packaging : Jar (we'll make use of the embeded tomcat server in spring boot)
• Java : 8

4 . As for dependencies, we just need four, so in Dependencies section, hit ADD DEPENDENCIES ... and choose these below:

• Rest Repositories, for Spring Data Rest
• Spring Data JPA, for JPA
• H2 Database, embeded database
• Spring Boot DevTools

Everything must look like this picture:

You just need to hit GENERATE CTRL+ ... to generate the zip file of the project.

Now, unzip the zip file :) in your prefered directory and open it in your IDE.

Using VS Code, just open your editor and go to File -> Open folder then select the project folder.

Our project is ready and must look like this:

Notice the 4 dependencies in the pom.xml file!

Test project

Our project is ready, before we run it, let's remove the application.properties file and add application.yml file in the src/main/resources folder.

Let's configure our app port to 9000. So, open the application.yml file and add the below code snipet:

server:
  port: 9000

Now we can run our app, in VS Code, you just open the main java class with @SpringBootApplication annotation and clic Run above the public static void main instruction.

As result, you must have a similar console:

Bravo, our backend is ready. Hope you've learnt something here, if yes please give a like to this tutorial and share it. In the next tutorial, we'll add entity classes and make REST call.

In this post I will share, through a demo project, how you can easily implement this feature in your Gatsby website.

Prerequisites

• You need an AWS account

Configure Amazon SNS

• Open AWS console and Sign In
• In Services menu, choose Simple Notification Service
• On SNS page, choose Create Topic
• Give a Name (here it's : GatsbyNewsletterTopic)
• Give a Display name (here : Gatsby Newsletter Topic)
• Leave optional configurations and hit Create topic
• Note the ARN (here, arn:aws:sns:us-east-1:...:GatsbyNewsletterTopic)

Create a AWS programmatic user for aws-sdk

• In the same AWS console with the same signed In user for above sns topic, choose IAM in Services menu
• Choose Users in the IAM Dashboard and clic on Add user
• Give the user name (here : SnsUser)
• Select : programmatic access and clic Next permission
• In the Set permissions tab, select Attach existing policies directly
• In the Policies table, search for AmazonSNSFullAccess and check it
• Then hit Next - Next - create.
• Copy or download the created user's cridentials (Access key ID and Secret Access key) for next steps.

Setting up the Gatsby website project

Now that we've created the sns subscription endpoint and the according user on AWS, we are going to setup our project.

• Create a new project : gatsby new my-gatsby-project https://github.com/gatsbyjs/gatsby-starter-default

• In the root of the project, type gatsby develop to run

• Open the browser and type : http://localhost:8000

Create Subscription component

• In the component folder, create : subscribeform.js file
• Install aws-sdk in the gatsby project npm install -save aws-sdk
• Install Formik and Yup schema builder npm install formik yup
• Copy and paste the below code snipet

import React from "react"
import { useFormik } from "formik"
import * as Yup from "yup"
export default function SubscribeForm() {
    const formik = useFormik({
    initialValues: {
      email: "",
    },
    validationSchema: Yup.object({
      email: Yup.string().email().required(),
    }),
    onSubmit(values, { resetForm }) {
      const { email } = values    
    },
  })
  return (
    <form onSubmit={formik.handleSubmit}>
      <input
        type="email"
        name="email"
        placeholder="Your email"
        onChange={formik.handleChange}
        value={formik.values.email}
      />
      {formik.errors.email ? (
        <span className="errorText">{formik.errors.email}</span>
      ) : null}
      <input type="submit" value="Subscribe" />
    </form>
  )
}

• Add subscribeform.js component in the index page, index.js must look like this :

import React from "react"
import { Link } from "gatsby"

import Layout from "../components/layout"
import Image from "../components/image"
import SEO from "../components/seo"
import SubscribeForm from "../components/subscribeform"

const IndexPage = () => (
  <Layout>
    <SEO title="Home" />
    <h1>Hi people</h1>
    <p>Welcome to your new Gatsby site.</p>
    <p>Now go build something great.</p>
    <div style={{ maxWidth: `300px`, marginBottom: `1.45rem` }}>
      <Image />
    </div>
    <div style={{ maxWidth: `300px`, marginBottom: `1.45rem` }}>
      <SubscribeForm />
    </div>
    <Link to="/page-2/">Go to page 2</Link> <br />
    <Link to="/using-typescript/">Go to "Using TypeScript"</Link>
  </Layout>
)

export default IndexPage

• Our webpage should have this look : note the email input and the subscribe button

Add subscription method

So far, everything works well as expected, but if you clic on subscribe button, nothing happens 🤣, yes, because we haven't done anything so great, everbody who've gone through Gatsby tutorials could have done what we did! Let's add some codes to our subscribeform.js.

• Add a config.json file in the root for AWS cridentials, it should look like this:

{ 
    "accessKeyId": "secret", 
    "secretAccessKey": "secret", 
    "region": "secret" 
}

Nota bene : You must replace "secret" with the corresponding accessKeyId , secretAccessKey and region values you've got in the Create a AWS programmatic user for aws-sdk section.

Warning : It is not a best practice to put app cridentials in a project, I'll have a post for how to do that, but for this subscription purpose, we'll not follow this best practice 🤦‍♂️. Let's move on!

• In the subscribeform.js , under the last import instruction, add the following lines:

import AWS from "aws-sdk"

const AWSConf = require('../../config.json');
AWS.config.update(AWSConf);

• In the onSubmit() method add the following instructions after const {email}=values line :

var params = {
        Protocol: "EMAIL" /* required */,
        TopicArn: "yourArn" /* required */,
        Endpoint: email,
      }

      var subscribePromise = new AWS.SNS({ apiVersion: "2010-03-31" })
        .subscribe(params)
        .promise()

      subscribePromise
        .then(function (data) {
          resetForm() //reset the form
        })
        .catch(function (err) {
          console.error(err, err.stack)
        })

Nota bene : In the TopicArn: "yourArn" instruction, replace yourArn by the ARN generated through Configure Amazon SNS section. Voilà! You've done the great thing 👍.

• The subscribeform.js code should look like this :

import React from "react"
import { useFormik } from "formik"
import * as Yup from "yup"
import AWS from "aws-sdk"

const AWSConf = require('../../config.json');
AWS.config.update(AWSConf);

export default function SubscribeForm() {
    const formik = useFormik({
    initialValues: {
      email: "",
    },
    validationSchema: Yup.object({
      email: Yup.string().email().required(),
    }),

    onSubmit(values, { resetForm }) {
      const { email } = values
      var params = {
        Protocol: "EMAIL" /* required */,
        TopicArn: "yourArn" /* required */,
        Endpoint: email,
      }

      var subscribePromise = new AWS.SNS({ apiVersion: "2010-03-31" })
        .subscribe(params)
        .promise()

      subscribePromise
        .then(function (data) {
          resetForm()  //reset the form
        })
        .catch(function (err) {
          console.error(err, err.stack)
        })

    },
  })

  return (
    <form onSubmit={formik.handleSubmit}>
      <input
        type="email"
        name="email"
        placeholder="Your email"
        onChange={formik.handleChange}
        value={formik.values.email}
      />
      {formik.errors.email ? (
        <span className="errorText">{formik.errors.email}</span>
      ) : null}
      <input type="submit" value="Subscribe" />
    </form>
  )
}

• Refresh the browser and put a valid email address then submit. The input field will be automatically reset on success, and a Subscription Confirmation email will be sent to the provided email address.

Conclusion

Well done! You have implemented an Amazon SNS email newsletter subscription in your Gatsby website.

You can find the source code here .