Share on:

REST API Security: OAuth OIDC Authorization, OpenAPI Swagger Compliance Validation, Service Level Monitoring

What This Article Is About

This article provides a step-by-step guide to securing a REST service using the open-source OpenIG gateway. In this article, we will do the following:

Deploy the Spring Pet Clinic demo REST service.
Secure the service with the OpenIG gateway:
1. Configure access authorization using the OAuth 2.0 protocol. We will use OpenAM as the OAuth 2.0 server.
2. We will configure validation of the service’s requests and responses to ensure they comply with the OpenAPI specification.
3. We will configure request throttling for each us

For demonstration purposes, we will deploy all services in Docker containers using Docker Compose.

What Threats does this Solution Address?

Without validation at the gateway, the backend receives any data from the client and returns any data from its responses to the client. This opens up several attack vectors:

Mass assignment — an attacker passes fields that are not specified (isAdmin: true, role: superuser), and the backend may process them if it is not protected at the code level.
Injection via non-standard fields — there is no validation of types or formats, meaning strings can be passed where a number is expected, or special characters can be inserted into fields without pattern restrictions.
Data leakage via responses — the backend may accidentally return fields that are not included in the contract (internal identifiers, password hashes, operational metadata). Response validation detects this.
Exploitation of undocumented endpoints — requests to paths not specified in the contract will be rejected by the gateway before reaching the backend.

Moving these checks to the gateway offloads the backend from security logic and provides a single point of control for all services behind the gateway.

You can download the full source code for this solution at the following link: openig-openam-openapi-example

Preparation

Create a docker-compose.yml file and add the Spring Pet Clinic service to it:

services:
  petclinic:
    image: springcommunity/spring-petclinic-rest:4.0.2
    ports:
      - 9966:9966

Start the container using the docker compose up command

Once the service has started, verify that it is running:

$ curl http://localhost:9966/petclinic/actuator/health 
{"groups":["liveness","readiness"],"status":"UP"}

Download the OpenAPI specification for the service; we’ll need it later to validate requests and responses:

curl -v http://localhost:9966/petclinic/v3/api-docs.yaml -H "Host: petclinic:9966" | grep -v extensions > petclinic.yml

Настройка OpenIG

Add OpenIG to the list of services in docker-compose.yml and close the port for the petclinic service. Now all requests to it will go through OpenIG.

services:
  petclinic:
    image: springcommunity/spring-petclinic-rest:4.0.2
  openig:
    image: openidentityplatform/openig:latest
    ports: 
      - 8081:8080
    volumes:
      - ./openig/config:/usr/local/openig-config:ro
    environment:
      CATALINA_OPTS: -Dopenig.base=/usr/local/openig-config -Dpetclinic=http://petclinic:9966

In the directory containing the docker-compose.yml file, create a directory named openapi, and within it, create two directories: config and openapi.

In the config directory, create two files, admin.json and config.json, with the following content:

admin.json

{
  "prefix" : "openig",
  "mode": "PRODUCTION"
}

config.json

{
  "heap": [
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
      ],
      "handler": {
        "type": "Router",
        "name": "_router",
        "capture": "all",
        "config": {
            "directory": "${system['openig.base']}/config/routes",
          "openApiValidation": {
            "enabled": true,
            "failOnResponseViolation": false
          }
        }
      }
    }
  }
}

Note: The directory parameter in the Router object’s configuration specifies the location of the route files.

Configuring a Route to the Pet Clinic Service

Now let’s add a route to the Spring Pet Clinic service

In the config directory, create a routes directory and add the OpenAPI specification file petclinic.yml to it.

Run OpenIG and verify that the route works:

docker compose up

curl -v  --location "http://localhost:8081/petclinic/api/pets"
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8081...
* Connected to localhost (::1) port 8081
> GET /petclinic/api/pets HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.7.1
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 200 
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Date: Mon, 23 Mar 2026 12:29:33 GMT
< Expires: 0
< Pragma: no-cache
< Vary: Origin
< Vary: Access-Control-Request-Method
< Vary: Access-Control-Request-Headers
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 0
< Content-Type: application/json
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
[{"name":"Leo","birthDate":"2010-09-07","type":{"name":"cat","id":1},"id":1,"visits":[],"ownerId":1}
....

Configuring Authentication

Deploy the OpenAM authentication server.

Add the openam service to docker-compose.yml

services:
...

  openam:
    image: openidentityplatform/openam
    container_name: openam
    restart: always
    hostname: openam.example.org
    ports:
      - "8080:8080"
    volumes:
      - openam-data:/usr/openam/config

volumes:
  openam-data:

Start the OpenAM service

docker compose up openam

Add the hostname for OpenAM to the hosts file. On Windows systems, the hosts file is located in the C:\\Windows/System32/drivers/etc/hosts directory; on Linux or Mac OS, it is located in /etc/hosts.

127.0.0.1    openam.example.org

Perform the initial OpenAM configuration:

docker exec -w '/usr/openam/ssoconfiguratortools' openam bash -c \
'echo "ACCEPT_LICENSES=true
SERVER_URL=http://openam.example.org:8080
DEPLOYMENT_URI=/$OPENAM_PATH
BASE_DIR=$OPENAM_DATA_DIR
locale=en_US
PLATFORM_LOCALE=en_US
AM_ENC_KEY=
ADMIN_PWD=passw0rd
AMLDAPUSERPASSWD=p@passw0rd
COOKIE_DOMAIN=example.org
ACCEPT_LICENSES=true
DATA_STORE=embedded
DIRECTORY_SSL=SIMPLE
DIRECTORY_SERVER=openam.example.org
DIRECTORY_PORT=50389
DIRECTORY_ADMIN_PORT=4444
DIRECTORY_JMX_PORT=1689
ROOT_SUFFIX=dc=openam,dc=example,dc=org
DS_DIRMGRDN=cn=Directory Manager
DS_DIRMGRPASSWD=passw0rd" > conf.file && java -jar openam-configurator-tool*.jar --file conf.file'

Wait for the command to finish.

Open the OpenAM console at http://openam.example.org:8080/openam/console. In the User Name and Password fields, enter the administrator’s username and password. In this case, these are amadmin and passw0rd, respectively.

OpenAM Realms

Next, Configure OAuth Provider.

OpenAM: Configure OAuth Provider

Then select the Configure OAuth 2.0 option.

OpenAM: Configure OAuth 2.0

In the form that opens, you can leave the default settings as they are. Click Create.

OpenAM: Configure OAuth 2.0 Settings

In the Realm settings, select Services from the menu on the left and open the OAuth2 Provider settings.

OpenAM Realm Services

Add the value uid to the Scopes and Default Clients Scopes settings.

Add an OAuth 2.0 client application.

In the admin console, select Top Level Realm and, in the menu on the left, navigate Applications → OAuth 2.0.

OpenAM Realm Applications

Create a new application with the name (client_id) petstore-app. Set the password (client_secret) to passw0rd.

OpenAM New OAuth 2.0 Application

Open the app settings and add the uid scope to the Scope(s) and Default Scope(s) settings. Save your changes.

Open the config.json configuration file and add the OAuth2ResourceServerFilter filter to the heap object. This filter will not allow unauthenticated requests to pass through. Add the filter to the route’s filter chain:

{
  "heap": [
    {
      "name": "OAuth2ResourceServerFilter",
      "type": "OAuth2ResourceServerFilter",
      "config": {
        "requireHttps": false,
        "providerHandler": "ClientHandler",
        "scopes": [
          "uid"
        ],
        "tokenInfoEndpoint": "${system['openam'].concat('/oauth2/tokeninfo')}"
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        "OAuth2ResourceServerFilter"
      ],
      "handler": {
        "type": "Router",
        "name": "_router",
        "capture": "all",
        "config": {
            "directory": "${system['openig.base']}/config/routes",
          "openApiValidation": {
            "enabled": true,
            "failOnResponseViolation": false
          }
        }
      }
    }
  }
}

Restart OpenIG using the command:

docker compose restart openig

Let’s test an unauthenticated request:

curl -v -X GET --location "http://localhost:8081/petclinic/api/pets"
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8081...
* Connected to localhost (::1) port 8081
> GET /petclinic/api/pets HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.7.1
> Accept: */*
> 
* Request completely sent off
< HTTP/1.1 401 
< WWW-Authenticate: Bearer realm="OpenIG"
< Content-Length: 0
< Date: Mon, 23 Mar 2026 07:25:27 GMT
< 
* Connection #0 to host localhost left intact

Now let’s obtain an access_token from OpenAM for the application and test an authenticated request:

curl \
--request POST \
--user "petstore-app:passw0rd" \
--data "grant_type=password&username=demo&password=changeit&scope=uid" \    
http://openam.example.org:8080/openam/oauth2/access_token
{"access_token":"c2270aa6-f1e1-47a2-a27f-3654af2f88d7","scope":"uid","token_type":"Bearer","expires_in":3599}%     

 curl -v -X GET --location "http://localhost:8081/petclinic/api/pets" \
    -H "Authorization: Bearer c2270aa6-f1e1-47a2-a27f-3654af2f88d7"       
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8081...
* Connected to localhost (::1) port 8081
> GET /petclinic/api/pets HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.7.1
> Accept: */*
> Authorization: Bearer c2270aa6-f1e1-47a2-a27f-3654af2f88d7
> 
* Request completely sent off
< HTTP/1.1 200 
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Date: Mon, 23 Mar 2026 07:29:03 GMT
< Expires: 0
< Pragma: no-cache
< Vary: Origin
< Vary: Access-Control-Request-Method
< Vary: Access-Control-Request-Headers
< X-Content-Type-Options: nosniff
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 0
< Content-Type: application/json
< Transfer-Encoding: chunked
< 
* Connection #0 to host localhost left intact
[{"name":"Leo","birthDate":"2010-09-07","type":{"name":"cat","id":1},"id":1,"visits":[],"ownerId":1},
....

More details on authorisation control are described in the article: https://github.com/OpenIdentityPlatform/OpenAM/wiki/How-to-Add-Authorization-and-Protect-Your-Application-With-OpenAM-and-OpenIG-Stack

Requests and Responses Validation

Let’s check that requests and responses from the Pet Clinic service comply with the OpenAPI specification.

Note. The Router object parameter openApiValidation.failOnResponseViolation: false means that invalid backend responses will be logged but not blocked. This is a safe mode for initial deployment: you can see deviations from the server response specification.

After auditing the logs and resolving any discrepancies between the code and the specification, set this to true. In this case, responses that violate the specification will not reach the client.

Restart the OpenIG container:

docker compose restart openig

Let’s check an invalid pet update request:

curl -v -X PUT --location "http://localhost:8081/petclinic/api/owners/10/pets/12" \
    -H "Content-Type: application/json" \
    -d "{
          \"birthDate\": \"2010-06-24\",
          \"badname\": \"Lucky\",
          \"type\": {
            \"id\": 2,
            \"name\": \"dog\"
          }
        }"
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8081...
* Connected to localhost (::1) port 8081
> PUT /petclinic/api/owners/10/pets/12 HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.7.1
> Accept: */*
> Content-Type: application/json
> Content-Length: 157
> 
* upload completely sent off: 157 bytes
< HTTP/1.1 400 
< Content-Type: text/plain;charset=UTF-8
< Content-Length: 183
< Date: Mon, 23 Mar 2026 12:34:50 GMT
< Connection: close
< 
* Closing connection
Request validation failed: [ERROR - Object instance has properties which are not allowed by the schema: ["badname"]: [], ERROR - Object has missing required properties (["name"]): []]

Check the OpenIG log; it contains a similar validation error message:

[http-nio-8080-exec-1] INFO  o.f.o.f.OpenApiValidationFilter - 
  Request validation failed for PUT http://petclinic:9966/petclinic/api/owners/10/pets/12: 
  [ERROR - Object instance has properties which are not allowed by the schema: ["badname"]: [], 
   ERROR - Object has missing required properties (["name"]): []]

Adding API Throttling

Finally, let’s add API throttling to ensure that a single user does not exceed the allowed number of requests to the service per unit of time.

Add the ThrottlingFilter filter to the heap object in the config.json configuration file:

{
  "heap": [
...
    {
      "type": "ThrottlingFilter",
      "name": "ThrottlingFilter",
      "config": {
        "requestGroupingPolicy": "${context.accessToken.info.uid}",
        "rate": {
          "numberOfRequests": 5,
          "duration": "5 s"
        }
      }
    }
  ],
  "handler": {
    "type": "Chain",
    "config": {
      "filters": [
        "OAuth2ResourceServerFilter",
        "ThrottlingFilter"
      ],
      "handler": {
        "type": "Router",
        "name": "_router",
        "capture": "all",
        "config": {
            "directory": "${system['openig.base']}/config/routes",
          "openApiValidation": {
            "enabled": true,
            "failOnResponseViolation": false
          }
        }
      }
    }
  }
}

And add it to the filter chain

Please note the requestGroupingPolicy setting. This setting allows requests to be grouped for bandwidth control based on the user ID obtained from the access_token included in the Authorization header of the HTTP request.

Send multiple requests using the same access_token. If the limit is exceeded, OpenIG will return a 429 status code: Too Many Requests

curl -v -X GET --location "http://localhost:8081/petclinic/api/pets" \
    -H "Authorization: Bearer c2270aa6-f1e1-47a2-a27f-3654af2f88d7"
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:8081 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:8081...
* Connected to localhost (::1) port 8081
> GET /petclinic/api/pets HTTP/1.1
> Host: localhost:8081
> User-Agent: curl/8.7.1
> Accept: */*
> Authorization: Bearer c2270aa6-f1e1-47a2-a27f-3654af2f88d7
> 
* Request completely sent off
< HTTP/1.1 429 
< Retry-After: 1
< Retry-After-Partition: demo
< Retry-After-Rate: 5/5 SECONDS
< Retry-After-Rule: ThrottlingFilter
< Content-Length: 0
< Date: Mon, 23 Mar 2026 07:38:03 GMT

More details on configuring throughput control are provided in the article: https://github.com/OpenIdentityPlatform/OpenIG/wiki/How-to-Setup-API-Throughput-Control-(Throttling)

Conclusion

In this article, we configured validation of requests and responses against the OpenAPI specification, added authentication validation using the OAuth 2.0 protocol, and set quotas on the number of requests to the service per account.

You can read more about OpenIG configuration in the documentation at https://doc.openidentityplatform.org/openig/.