fixes #266 add skipVerifyScopeWithoutSpec flag to openapi-security.yml (#267)

Author: stevehu

openapi-security/src/main/java/com/networknt/openapi/JwtVerifyHandler.java

@@ -20,6 +20,7 @@
 import com.networknt.exception.ExpiredTokenException;
 import com.networknt.handler.Handler;
 import com.networknt.handler.MiddlewareHandler;
+import com.networknt.handler.config.HandlerConfig;
 import com.networknt.httpstring.AttachmentConstants;
 import com.networknt.httpstring.HttpStringConstants;
 import com.networknt.oas.model.Operation;
@@ -81,6 +82,9 @@ public JwtVerifyHandler() {
         // And the basePath is the correct one from the OpenApiHandler helper or helperMap if multiple is used.
         config = SecurityConfig.load(OPENAPI_SECURITY_CONFIG);
         jwtVerifier = new JwtVerifier(config);
+        // in case that the specification doesn't exist, get the basePath from the handler.yml for endpoint lookup.
+        HandlerConfig handlerConfig = (HandlerConfig) Config.getInstance().getJsonObjectConfig(HANDLER_CONFIG, HandlerConfig.class);
+        this.basePath = handlerConfig == null ? "/" : handlerConfig.getBasePath();
     }
 
     @Override
@@ -168,6 +172,12 @@ public void handleRequest(final HttpServerExchange exchange) throws Exception {
                     OpenApiOperation openApiOperation = (OpenApiOperation) auditInfo.get(Constants.OPENAPI_OPERATION_STRING);
                     Operation operation = this.getOperation(exchange, openApiOperation, auditInfo);
                     if(operation == null) {
+                        if(config.isSkipVerifyScopeWithoutSpec()) {
+                            if (logger.isDebugEnabled()) logger.debug("JwtVerifyHandler.handleRequest ends without verifying scope due to spec.");
+                            Handler.next(exchange, next);
+                        } else {
+                            // this will return an error message to the client.
+                        }
                         return;
                     }
 
@@ -271,7 +281,9 @@ protected Operation getOperation(HttpServerExchange exchange, OpenApiOperation o
             final Optional<NormalisedPath> maybeApiPath = OpenApiHandler.getHelper(exchange.getRequestPath()).findMatchingApiPath(requestPath);
 
             if (maybeApiPath.isEmpty()) {
-                setExchangeStatus(exchange, STATUS_INVALID_REQUEST_PATH);
+                if(!config.isSkipVerifyScopeWithoutSpec()) {
+                    setExchangeStatus(exchange, STATUS_INVALID_REQUEST_PATH);
+                }
                 return null;
             }
 

openapi-security/src/main/resources/config/openapi-security.yml

@@ -3,15 +3,30 @@
 # same server instance. If this file cannot be found, the generic security.yml will be
 # loaded for backward compatibility.
 ---
-# Enable JWT verification flag.
+# Enable the JWT verification flag. The JwtVerifierHandler will skip the JWT token verification
+# if this flag is false. It should only be set to false on the dev environment for testing
+# purposes. If you have some endpoints that want to skip the JWT verification, you can put the
+# request path prefix in skipPathPrefixes.
 enableVerifyJwt: ${openapi-security.enableVerifyJwt:true}
 
 # Extract JWT scope token from the X-Scope-Token header and validate the JWT token
 enableExtractScopeToken: ${openapi-security.enableExtractScopeToken:true}
 
-# Enable JWT scope verification. Only valid when enableVerifyJwt is true.
+# Enable JWT scope verification. This flag is valid when enableVerifyJwt is true. When using the
+# light gateway as a centralized gateway without backend API specifications, you can still enable
+# this flag to allow the admin endpoints to have scopes verified. And all backend APIs without
+# specifications skip the scope verification if the spec does not exist with the skipVerifyScopeWithoutSpec
+# flag to true. Also, you need to have the openapi.yml specification file in the config folder to
+# enable it, as the scope verification compares the scope from the JWT token and the scope in the
+# endpoint specification.
 enableVerifyScope: ${openapi-security.enableVerifyScope:true}
 
+# Users should only use this flag in a shared light gateway if the backend API specifications are
+# unavailable in the gateway config folder. If this flag is true and the enableVerifyScope is true,
+# the security handler will invoke the scope verification for all endpoints. However, if the endpoint
+# doesn't have a specification to retrieve the defined scopes, the handler will skip the scope verification.
+skipVerifyScopeWithoutSpec: ${openapi-security.skipVerifyScopeWithoutSpec:false}
+
 # Enable JWT scope verification. 
 # Only valid when (enableVerifyJwt is true) AND (enableVerifyScope is true)
 enableVerifyJwtScopeToken: ${openapi-security.enableVerifyJwtScopeToken:true}

openapi-security/src/test/resources/config/openapi-security.yml

@@ -3,15 +3,30 @@
 # same server instance. If this file cannot be found, the generic security.yml will be
 # loaded for backward compatibility.
 ---
-# Enable JWT verification flag.
+# Enable the JWT verification flag. The JwtVerifierHandler will skip the JWT token verification
+# if this flag is false. It should only be set to false on the dev environment for testing
+# purposes. If you have some endpoints that want to skip the JWT verification, you can put the
+# request path prefix in skipPathPrefixes.
 enableVerifyJwt: ${openapi-security.enableVerifyJwt:true}
 
 # Extract JWT scope token from the X-Scope-Token header and validate the JWT token
 enableExtractScopeToken: ${openapi-security.enableExtractScopeToken:true}
 
-# Enable JWT scope verification. Only valid when enableVerifyJwt is true.
+# Enable JWT scope verification. This flag is valid when enableVerifyJwt is true. When using the
+# light gateway as a centralized gateway without backend API specifications, you can still enable
+# this flag to allow the admin endpoints to have scopes verified. And all backend APIs without
+# specifications skip the scope verification if the spec does not exist with the skipVerifyScopeWithoutSpec
+# flag to true. Also, you need to have the openapi.yml specification file in the config folder to
+# enable it, as the scope verification compares the scope from the JWT token and the scope in the
+# endpoint specification.
 enableVerifyScope: ${openapi-security.enableVerifyScope:true}
 
+# Users should only use this flag in a shared light gateway if the backend API specifications are
+# unavailable in the gateway config folder. If this flag is true and the enableVerifyScope is true,
+# the security handler will invoke the scope verification for all endpoints. However, if the endpoint
+# doesn't have a specification to retrieve the defined scopes, the handler will skip the scope verification.
+skipVerifyScopeWithoutSpec: ${openapi-security.skipVerifyScopeWithoutSpec:false}
+
 # Enable JWT scope verification. 
 # Only valid when (enableVerifyJwt is true) AND (enableVerifyScope is true)
 enableVerifyJwtScopeToken: ${openapi-security.enableVerifyJwtScopeToken:true}