/images/resources/code-examples/code-examples-kotlin.jpg

Securing a Kotlin API with JWTs

On this page

Overview

This tutorial explains how to integrate the jose4j security library and use it to validate JWTs in a plain Kotlin API. We will also use Spark Java as a minimal REST API stack.

Note

Curity Identity Server is used in this example, but other OAuth servers can also be used.

Create a Kotlin API

Create your own Kotlin API according to a Spark Tutorial of your choice. Our API will have a simple entry point function which ensures that a valid access token has been provided before any API routes are allowed to run:

kotlin
12345678910111213
fun main() {
val configuration = Configuration()
port(configuration.getPortNumber())
val filter = OAuthFilter(configuration)
before("*") { request, response ->
filter.doFilter(request.raw(), response.raw(), null)
}
val routes = ApiRoutes()
get("/api/data", routes::getData)
}

Configuration

The code sample uses the Java configuration system and the following properties. The jose4j library will download token signing public keys from the Authorization Server's JWKS endpoint, then use them to verify the signature of received JWTs. The library will also reject any access tokens whose issuer and audience claims do not match the API's configured values:

1234
port=3000
jwks_endpoint=https://idsvr.example.com/oauth/v2/oauth-anonymous/jwks
issuer_claim=https://idsvr.example.com/oauth/v2/oauth-anonymous
audience_claim=api.example.com

Security Library Integration

Next get the latest version of the jose4j library, which will perform the security work for us. When the OAuth filter is created it constructs global objects to manage downloading JWKS keys:

kotlin
12
private val _httpsJkws = HttpsJwks(_configuration.getJwksEndpoint())
private val _httpsJwksKeyResolver = HttpsJwksVerificationKeyResolver(_httpsJkws)

Note that these classes also manage caching of JWKS keys in a thread safe manner. Any subsequent requests to the API with JWTs having the same kid value, do not trigger additional HTTPS calls to the JWKS endpoint, so that API behavior is efficient.

Next the token validation behavior is configured, and note that allowed algorithms are restricted to those expected from clients, as recommended in JWT Security Best Practices.

kotlin
123456789
val jwtConsumer = JwtConsumerBuilder()
.setVerificationKeyResolver(_httpsJwksKeyResolver)
.setJwsAlgorithmConstraints(
AlgorithmConstraints.ConstraintType.PERMIT,
AlgorithmIdentifiers.RSA_USING_SHA256
)
.setExpectedIssuer(_configuration.getIssuerExpectedClaim())
.setExpectedAudience(_configuration.getAudienceExpectedClaim())
.build()

Finally the OAuth filter calls the jose4j processToClaims method, and for valid tokens this results in a claims object being returned, which is then attached to the request object so that it can be used in API routes:

kotlin
12
val jwtClaims = jwtConsumer.processToClaims(jwt)
request.setAttribute("principal", jwtClaims)

Using Claims and Scopes

Once the token is validated, the API can access its scopes and claims via the Java request object. A real world API would then use the scopes and claims from the JWT to authorize access to business data, according to the below articles:

Our sample API simply returns scopes and claims back to the client, and in this example the JWT contains a custom claim called role:

kotlin
12345678910111213
class ApiRoutes {
fun getData(request: Request, response: Response): String {
val claims = request.attribute<JwtClaims>("principal")
val role = claims.getClaimValueAsString("role")
val scope = claims.getClaimValueAsString("scope")
val data = DataResponse("API Request has role: $role and scope: $scope")
return Gson().toJson(data)
}
}

Test the API

The API's clients will call it via HTTP requests with an access token in the Authorization header, and this can be easily tested via a CURL request:

.."
1
curl -i http://localhost:3000/api/data -H "Authorization: Bearer eyJraWQiOiIyMTg5NTc5MTYiLC ..."

In the event of a problem validating the JWT, an error reason can be returned to the client. The sample returns a generic error in the WWW-Authenticate response header, though a custom response object could be returned instead:

text
123456
HTTP/1.1 401 Unauthorized
Date: Mon, 12 Apr 2021 16:01:07 GMT
WWW-Authenticate: Bearer, error=invalid_token, error_description=Access token is missing, invalid or expired
Content-Type: text/html;charset=utf-8
Transfer-Encoding: chunked
Server: Jetty(9.4.31.v20200723)

Logging and Error Handling

The sample API also shows how to capture jose4j internal log messages and how to work with its error objects. In real world APIs you will want to quickly diagnose any reasons for token validation failures or problems connecting to the Authorization Server.

kotlin
123456789
catch (e: InvalidJwtException) {
_logger.info("JWT validation failed")
for (item in e.errorDetails) {
_logger.debug("${item.errorCode} : ${item.errorMessage}")
}
this.unauthorizedResponse(httpResponse)
}

Conclusion

Integrating the jose4j library is an easy way to implement OAuth security in Java or Kotlin APIs. Once done you have full access to the access token's scopes and claims, so that your API can secure access to its data.