Add permissions handling (#3)

mduesterhoeft · web-flow · commit 84d5c67f608b · 2019-04-25T11:33:59.000+02:00
* Add permissions handling

* Add documentation

* Add hint about JWT verification

* Use constant to avoid duplicating default values

* Use equals with ignoreCase switch
diff --git a/README.md b/README.md
@@ -111,6 +111,85 @@ override val router = router {
 }
 ```
 
+### Permissions
 
+Permission handling is a cross-cutting concern that can be handled outside the regular handler function.
+The routing DSL also supports expressing required permissions:
+
+```kotlin
+override val router = router {
+    GET("/some", controller::get).requiringPermissions("A_PERMISSION", "A_SECOND_PERMISSION")
+}
+```
+
+For the route above the `RequestHandler` checks if *any* of the listed permissions are found on a request.
+
+Additionally we need to configure a strategy to extract permissions from a request on the `RequestHandler`.
+By default a `RequestHandler` is using the `NoOpPermissionHandler` which always decides that any required permissions are found.
+The `JwtPermissionHandler` can be used to extract permissions from a JWT token found in a header.
+
+```kotlin
+class TestRequestHandlerAuthorization : RequestHandler() {
+    override val router = router {
+       GET("/some", controller::get).requiringPermissions("A_PERMISSION")
+    }
+
+    override fun permissionHandlerSupplier(): (r: APIGatewayProxyRequestEvent) -> PermissionHandler =
+        { JwtPermissionHandler(
+            request = it,
+            //the claim to use to extract the permissions - defaults to `scope`
+            permissionsClaim = "permissions",
+            //separator used to separate permissions in the claim - defaults to ` `
+            permissionSeparator = ","
+        ) }
+}
+```
+
+Given the code above the token is extracted from the `Authorization` header.
+We can also choose to extract the token from a different header:
+
+```kotlin
+JwtPermissionHandler(
+    accessor = JwtAccessor(
+        request = it,
+        authorizationHeaderName = "custom-auth")
+)
+```
+
+:warning: The implementation here assumes that JWT tokens are validated on the API Gateway. 
+So we do no validation of the JWT token.
+
+### Protobuf support
+
+
+### Open API validation support
+
+The module `router-openapi-request-validator` can be used to validate a request against an [OpenAPI](https://www.openapis.org/) specification.
+Internally we use the [swagger-request-validator](https://bitbucket.org/atlassian/swagger-request-validator) to achieve this task.
+
+This library validates:
+- if the resource used is documented in the OpenApi specification
+- if request and response can be successfully validated against the request and response schema
+- ...
+
+```
+testImplementation 'com.github.moia-dev.lambda-kotlin-request-router:router-openapi-request-validator:0.3.1'
+```
+
+```kotlin
+    val validator = OpenApiValidator("openapi.yml")
+
+    @Test
+    fun `should handle and validate request`() {
+        val request = GET("/tests")
+            .withHeaders(mapOf("Accept" to "application/json"))
+
+        val response = testHandler.handleRequest(request, mockk())
+
+        validator.assertValidRequest(request)
+        validator.assertValidResponse(request, response)
+        validator.assertValid(request, response)
+    }
+```
 
 
diff --git a/router-openapi-request-validator/src/test/kotlin/io/moia/router/openapi/OpenApiValidatorTest.kt b/router-openapi-request-validator/src/test/kotlin/io/moia/router/openapi/OpenApiValidatorTest.kt
@@ -69,11 +69,7 @@ class OpenApiValidatorTest {
 
         override val router = Router.router {
             GET("/tests") { _: Request<Unit> ->
-                ResponseEntity.ok(
-                    TestResponseInvalid(
-                        "Hello"
-                    )
-                )
+                ResponseEntity.ok(TestResponseInvalid("Hello"))
             }
         }
     }
diff --git a/router/build.gradle.kts b/router/build.gradle.kts
@@ -4,7 +4,7 @@ dependencies {
     compile(kotlin("stdlib-jdk8"))
     compile(kotlin("reflect"))
     compile("com.amazonaws:aws-lambda-java-core:1.2.0")
-    compile("com.amazonaws:aws-lambda-java-events:2.2.5")
+    compile("com.amazonaws:aws-lambda-java-events:2.2.6")
     
     compile("org.slf4j:slf4j-api:1.7.26")
     compile("com.fasterxml.jackson.core:jackson-databind:2.9.8")
diff --git a/router/src/main/kotlin/io/moia/router/APIGatewayProxyEventExtensions.kt b/router/src/main/kotlin/io/moia/router/APIGatewayProxyEventExtensions.kt
@@ -56,9 +56,9 @@ fun APIGatewayProxyResponseEvent.withLocationHeader(request: APIGatewayProxyRequ
 
 fun APIGatewayProxyResponseEvent.location() = getHeaderCaseInsensitive("location")
 
-private fun getCaseInsensitive(key: String, map: Map<String, String>): String? =
-    map.entries
-        .firstOrNull { it.key.toLowerCase() == key.toLowerCase() }
+private fun getCaseInsensitive(key: String, map: Map<String, String>?): String? =
+    map?.entries
+        ?.firstOrNull { key.equals(it.key, ignoreCase = true) }
         ?.value
 
 fun APIGatewayProxyResponseEvent.bodyAsBytes() = Base64.getDecoder().decode(body)
diff --git a/router/src/main/kotlin/io/moia/router/PermissionHandler.kt b/router/src/main/kotlin/io/moia/router/PermissionHandler.kt
@@ -0,0 +1,73 @@
+package io.moia.router
+
+import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent
+import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper
+import com.fasterxml.jackson.module.kotlin.readValue
+import java.util.Base64
+
+interface PermissionHandler {
+
+    fun hasAnyRequiredPermission(requiredPermissions: Set<String>): Boolean
+}
+
+class NoOpPermissionHandler : PermissionHandler {
+    override fun hasAnyRequiredPermission(requiredPermissions: Set<String>) = true
+}
+
+open class JwtAccessor(
+    private val request: APIGatewayProxyRequestEvent,
+    private val authorizationHeaderName: String = "authorization"
+) {
+
+    private val objectMapper = jacksonObjectMapper()
+
+    fun extractJwtToken(): String? =
+        // support "Bearer <token>" as well as "<token>"
+        request.getHeaderCaseInsensitive(authorizationHeaderName)?.split(" ")?.toList()?.last()
+
+    fun extractJwtClaims() =
+        extractJwtToken()
+            ?.let { token -> token.split("\\.".toRegex()).dropLastWhile { it.isEmpty() } }
+            ?.takeIf { it.size == 3 }
+            ?.let { it[1] }
+            ?.let { jwtPayload ->
+                try {
+                    String(Base64.getDecoder().decode(jwtPayload))
+                } catch (e: Exception) {
+                    return null
+                }
+            }
+            ?.let { objectMapper.readValue<Map<String, Any>>(it) }
+}
+open class JwtPermissionHandler(
+    val accessor: JwtAccessor,
+    val permissionsClaim: String = defaultPermissionsClaim,
+    val permissionSeparator: String = defaultPermissionSeparator
+) : PermissionHandler {
+
+    constructor(
+        request: APIGatewayProxyRequestEvent,
+        permissionsClaim: String = defaultPermissionsClaim,
+        permissionSeparator: String = defaultPermissionSeparator
+    ) : this(JwtAccessor(request), permissionsClaim, permissionSeparator)
+
+    override fun hasAnyRequiredPermission(requiredPermissions: Set<String>): Boolean =
+        extractPermissions().any { requiredPermissions.contains(it) }
+
+    internal open fun extractPermissions(): Set<String> =
+        accessor.extractJwtClaims()
+            ?.let { it[permissionsClaim] }
+            ?.let {
+                when (it) {
+                    is List<*> -> (it as List<String>).toSet()
+                    is String -> it.split(permissionSeparator).map { s -> s.trim() }.toSet()
+                    else -> null
+                }
+            }
+            ?: emptySet()
+
+    companion object {
+        private const val defaultPermissionsClaim = "scope"
+        private const val defaultPermissionSeparator: String = " "
+    }
+}
diff --git a/router/src/main/kotlin/io/moia/router/RequestHandler.kt b/router/src/main/kotlin/io/moia/router/RequestHandler.kt
@@ -29,6 +29,9 @@ abstract class RequestHandler : RequestHandler<APIGatewayProxyRequestEvent, APIG
             val matchResult = routerFunction.requestPredicate.match(input)
             log.debug("match result for route '$routerFunction' is '$matchResult'")
             if (matchResult.match) {
+                if (!permissionHandlerSupplier()(input).hasAnyRequiredPermission(routerFunction.requestPredicate.requiredPermissions))
+                    return createApiExceptionErrorResponse(input, ApiException("unauthorized", "UNAUTHORIZED", 401))
+
                 val handler: HandlerFunction<Any, Any> = routerFunction.handler
                 return try {
                     val requestBody = deserializeRequest(handler, input)
@@ -56,12 +59,16 @@ abstract class RequestHandler : RequestHandler<APIGatewayProxyRequestEvent, APIG
             objectMapper
         )
     )
+
     open fun deserializationHandlers(): List<DeserializationHandler> = listOf(
         JsonDeserializationHandler(
             objectMapper
         )
     )
 
+    open fun permissionHandlerSupplier(): (r: APIGatewayProxyRequestEvent) -> PermissionHandler =
+        { NoOpPermissionHandler() }
+
     private fun deserializeRequest(
         handler: HandlerFunction<Any, Any>,
         input: APIGatewayProxyRequestEvent
diff --git a/router/src/main/kotlin/io/moia/router/RequestPredicate.kt b/router/src/main/kotlin/io/moia/router/RequestPredicate.kt
@@ -7,18 +7,29 @@ data class RequestPredicate(
     val method: String,
     val pathPattern: String,
     var produces: Set<String>,
-    var consumes: Set<String>
+    var consumes: Set<String>,
+    var requiredPermissions: Set<String> = emptySet()
 ) {
 
     fun consuming(vararg mediaTypes: String): RequestPredicate {
         consumes = mediaTypes.toSet()
         return this
     }
+
     fun producing(vararg mediaTypes: String): RequestPredicate {
         produces = mediaTypes.toSet()
         return this
     }
 
+    /**
+     * Register required permissions for this route.
+     * The RequestHandler checks if any of the given permissions are found on a request.
+     */
+    fun requiringPermissions(vararg permissions: String): RequestPredicate {
+        requiredPermissions = permissions.toSet()
+        return this
+    }
+
     internal fun match(request: APIGatewayProxyRequestEvent) =
         RequestMatchResult(
             matchPath = pathMatches(request),
diff --git a/router/src/main/kotlin/io/moia/router/Router.kt b/router/src/main/kotlin/io/moia/router/Router.kt
@@ -20,44 +20,24 @@ class Router {
         ).also { routes += RouterFunction(it, handlerFunction) }
 
     fun <I, T> POST(pattern: String, handlerFunction: HandlerFunction<I, T>) =
-        RequestPredicate(
-            method = "POST",
-            pathPattern = pattern,
-            consumes = defaultConsuming,
-            produces = defaultProducing
-        ).also {
-            routes += RouterFunction(it, handlerFunction)
-        }
+        defaultRequestPredicate(pattern, "POST", handlerFunction)
 
     fun <I, T> PUT(pattern: String, handlerFunction: HandlerFunction<I, T>) =
-        RequestPredicate(
-            method = "PUT",
-            pathPattern = pattern,
-            consumes = defaultConsuming,
-            produces = defaultProducing
-        ).also {
-            routes += RouterFunction(it, handlerFunction)
-        }
+        defaultRequestPredicate(pattern, "PUT", handlerFunction)
 
     fun <I, T> DELETE(pattern: String, handlerFunction: HandlerFunction<I, T>) =
-        RequestPredicate(
-            method = "DELETE",
-            pathPattern = pattern,
-            consumes = defaultConsuming,
-            produces = defaultProducing
-        ).also {
-            routes += RouterFunction(it, handlerFunction)
-        }
+        defaultRequestPredicate(pattern, "DELETE", handlerFunction)
 
     fun <I, T> PATCH(pattern: String, handlerFunction: HandlerFunction<I, T>) =
+        defaultRequestPredicate(pattern, "PATCH", handlerFunction)
+
+    private fun <I, T> defaultRequestPredicate(pattern: String, method: String, handlerFunction: HandlerFunction<I, T>) =
         RequestPredicate(
-            method = "PATCH",
+            method = method,
             pathPattern = pattern,
             consumes = defaultConsuming,
             produces = defaultProducing
-        ).also {
-            routes += RouterFunction(it, handlerFunction)
-        }
+        ).also { routes += RouterFunction(it, handlerFunction) }
 
     companion object {
         fun router(routes: Router.() -> Unit) = Router().apply(routes)
diff --git a/router/src/test/kotlin/io/moia/router/JwtPermissionHandlerTest.kt b/router/src/test/kotlin/io/moia/router/JwtPermissionHandlerTest.kt
@@ -0,0 +1,77 @@
+package io.moia.router
+
+import com.amazonaws.services.lambda.runtime.events.APIGatewayProxyRequestEvent
+import org.assertj.core.api.BDDAssertions.then
+import org.junit.jupiter.api.Test
+
+class JwtPermissionHandlerTest {
+
+    /*
+    {
+        "sub": "1234567890",
+        "name": "John Doe",
+        "iat": 1516239022,
+        "scope": "one two"
+    }
+    */
+    val jwtWithScopeClaimSpace = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJzY29wZSI6Im9uZSB0d28ifQ.2tPrDymXDejHfVjNlVh4XUj22ZuDrKHP6dvWN7JNAWY"
+    /*
+    {
+      "sub": "1234567890",
+      "name": "John Doe",
+      "iat": 1516239022,
+      "userRights": "one, two"
+    }
+     */
+    val jwtWithCustomClaimAndSeparator = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyLCJ1c2VyUmlnaHRzIjoib25lLCB0d28ifQ.49yk0fq39zMF77ZLJsXH_6D6I3iSDpy-Qk3vZ_PssIY"
+
+    @Test
+    fun `should extract permissions from standard JWT contained in bearer auth header`() {
+        val handler = permissionHandler("Bearer $jwtWithScopeClaimSpace")
+
+        thenRecognizesRequiredPermissions(handler)
+    }
+
+    @Test
+    fun `should extract permissions from standard JWT contained in auth header`() {
+        val handler = permissionHandler(jwtWithScopeClaimSpace)
+
+        thenRecognizesRequiredPermissions(handler)
+    }
+
+    @Test
+    fun `should extract permissions from custom permissions claim`() {
+        val handler = JwtPermissionHandler(
+            accessor = JwtAccessor(APIGatewayProxyRequestEvent()
+                .withHeader("Authorization", jwtWithCustomClaimAndSeparator)),
+            permissionsClaim = "userRights",
+            permissionSeparator = ","
+        )
+
+        thenRecognizesRequiredPermissions(handler)
+    }
+
+    @Test
+    fun `should work for missing header`() {
+        val handler = JwtPermissionHandler(JwtAccessor(APIGatewayProxyRequestEvent()))
+
+        then(handler.extractPermissions()).isEmpty()
+    }
+
+    @Test
+    fun `should work for not jwt auth header`() {
+        val handler = permissionHandler("a.b.c")
+
+        then(handler.extractPermissions()).isEmpty()
+    }
+
+    private fun thenRecognizesRequiredPermissions(handler: JwtPermissionHandler) {
+        then(handler.hasAnyRequiredPermission(setOf("one"))).isTrue()
+        then(handler.hasAnyRequiredPermission(setOf("two"))).isTrue()
+        then(handler.hasAnyRequiredPermission(setOf("nope"))).isFalse()
+    }
+
+    private fun permissionHandler(authHeader: String) =
+        JwtPermissionHandler(JwtAccessor(APIGatewayProxyRequestEvent()
+            .withHeader("Authorization", authHeader)))
+}
diff --git a/router/src/test/kotlin/io/moia/router/NoOpPermissionHandlerTest.kt b/router/src/test/kotlin/io/moia/router/NoOpPermissionHandlerTest.kt
diff --git a/router/src/test/kotlin/io/moia/router/RequestHandlerTest.kt b/router/src/test/kotlin/io/moia/router/RequestHandlerTest.kt
diff --git a/router/src/test/kotlin/io/moia/router/RouterTest.kt b/router/src/test/kotlin/io/moia/router/RouterTest.kt

Original file line number	Diff line number	Diff line change
`@@ -69,11 +69,7 @@ class OpenApiValidatorTest {`
`69`	`69`
`70`	`70`	`override val router = Router.router {`
`71`	`71`	`GET("/tests") { _: Request<Unit> ->`
`72`		`- ResponseEntity.ok(`
`73`		`- TestResponseInvalid(`
`74`		`- "Hello"`
`75`		`- )`
`76`		`- )`
	`72`	`+ ResponseEntity.ok(TestResponseInvalid("Hello"))`
`77`	`73`	`}`
`78`	`74`	`}`
`79`	`75`	`}`