CredentialsJWT

public class CredentialsJWT<C> : CredentialsPluginProtocol, CredentialsTokenTTL where C : Claims

A plugin for Kitura-Credentials supporting authentication using JSON Web Tokens.

This plugin requires that the following HTTP headers are present on a request:

• Authorization: the JWT string, optionally prefixed with Bearer

If you wish to use multiple Credentials plugins, then additionally the header:

• X-token-type: must equal JWT.

The Swift-JWT library is used to decode JWT strings. To successfully decode it, you must specify the Claims that will be present in the JWT. One claim (by default, sub) will be used to represent the identity of the bearer. You can choose a different claim by supplying the subject option when creating an instance of CredentialsJWT, and you can further customize the resulting UserProfile by defining a UserProfileDelegate.

 Usage Example

To use CredentialsJWT using the default options:

import Credentials
import CredentialsJWT
import SwiftJWT

// Defines the claims that must be present in a JWT.
struct MyClaims: Claims {
    let sub: String
}

// Defines the method used to verify the signature of a JWT.
let jwtVerifier = .hs256(key: "<PrivateKey>".data(using: .utf8)!)

// Create a CredentialsJWT plugin with default options.
let jwtCredentials = CredentialsJWT<MyClaims>(verifier: jwtVerifier)

let authenticationMiddleware = Credentials()
authenticationMiddleware.register(plugin: jwtCredentials)
router.get("/myProtectedRoute", middleware: authenticationMiddleware)

Following successful authentication, the UserProfile will be minimally populated with the two required fields - id and displayName - both with the value of the JWT’s sub claim. The provider will be set to JWT.

Usage Example - custom claims

To customize the name of the identity claim, and further populate the UserProfile fields, specify the subject and userProfileDelegate options as follows:

import Credentials
import CredentialsJWT
import SwiftJWT

// Defines the claims that must be present in a JWT.
struct MyClaims: Claims {
    let id: Int
    let fullName: String
    let email: String
}

struct MyDelegate: UserProfileDelegate {
    func update(userProfile: UserProfile, from dictionary: [String:Any]) {
        // `userProfile.id` already contains `id`
        userProfile.displayName = dictionary["fullName"]! as! String
        let email = UserProfile.UserProfileEmail(value: dictionary["email"]! as! String, type: "home")
        userProfile.emails = [email]
    }
}

// Defines the method used to verify the signature of a JWT.
let jwtVerifier = .hs256(key: "<PrivateKey>".data(using: .utf8)!)

// Create a CredentialsJWT plugin with default options.
let jwtCredentials = CredentialsJWT<MyClaims>(verifier: jwtVerifier, options: [CredentialsJWTOptions.subject: "id", CredentialsJWTOptions.userProfileDelegate: MyDelegate])

let authenticationMiddleware = Credentials()
authenticationMiddleware.register(plugin: jwtCredentials)
router.get("/myProtectedRoute", middleware: authenticationMiddleware)

Following successful authentication, the UserProfile will be populated as follows:

• id: the id claim (converted to a String),
• displayName: the fullName claim,
• emails: an array with a single element, representing the email claim.