Kitura-JWT

An implementation of JSON Web Token

Summary

An implementation of JSON Web Token

Table of Contents

• Getting started
• Supported algorithms
• Usage
• License

Getting started

macOS

Install OpenSSl:

$ brew install openssl

Download Kitura-JWT and run:

$ swift package fetch

Edit Packages/OpenSSL-<version>/Package.swift, change the pkgConfig to "openssl", i.e. the file should contain:

import PackageDescription

let package = Package(
        name: "OpenSSL",
        pkgConfig: "openssl",
        providers: [
                .Brew("openssl"),
        ]
)

Set PKG_CONFIG_PATH:

$ export PKG_CONFIG_PATH=/usr/local/opt/openssl/ib/pkgconfig/

And build Kitura-JWT:

$ swift build

Supported algorithms

At the moment the supported algorithms are: RSA with 256, 384 and 512 bits.

They are listed in Algorithm. In order to check if an algorithm is supported and whether it requires a key or a secret, call:

public static func isSupported(name: String) -> Supported

where name is a textual representation of an algorithm, e.g., "rs256" or "RS256".

Supported is an enum with the following cases: unsupported, supportedWithKey (RSA falls into this category), and supportedWithSecret (HMAC, which is currently unsupported).

Usage

Add

import KituraJWT

to your application.

Sign a JWT

The sign method encodes header and claims of a JWT instance, creates a signature, and returns a String containing a signed JSON Web Token.

let jwt = JWT(header: Header([.typ:"JWT"]), claims: Claims([.name:"Kitura"]))
let signedJWT = jwt.sign(using: .rs256(key, .privateKey))

signedJWT will be of the form

<encoded header>.<encoded claims>.<signature>

Note, that sign sets the alg field of the header.

Decode a JSON Web Token

A static function JWT.decode creates an instance of JWT for a String containing JSON Web Token:

let jwt = decode(encodedAndSignedJWT)

Note, that this method doesn't verify the signature of the token.

Verify signature of a JSON Web Token

A static function JWT.verify verifies the signature of a JSON Web Token given as a String:

if !verify(encodedAndSignedJWT, using: .rs512(key, .publicKey)) {
    print("Verification failed")
}

Validate claims

validateClaims method validates the claims of a JWT instance. The following claims are validated if they are present in the Claims object:

• iss
• aud
• azp
• at_hash
• exp
• nbf
• iat

Various validations require an input. In these cases, if the claim in question exists and the input is provided, the validation will be performed. Otherwise, the validation is skipped.

The method returns ValidateClaimsResult - an enum that list the various reasons for validation failure. If the validation succeeds ValidateClaimsResult.success is returned.

let validationResult = validateClaims(issuer: issuer, audience: clientID, accessToken: accessToken)
if validationResult != .success {
  print("Claims validation failed: ", validationResult)
}

License

This library is licensed under Apache 2.0. Full license text is available in LICENSE.