This library handles decoding and validating a JSON Web Token (JWT) issued by an Okta authorization server. It provides an easy-to-use and customizable interface for ID Token validation based on OIDC 3.1.3.7 for iOS applications.
OktaJWT is available through CocoaPods. To install it, simply add the following line to your Podfile
:
pod 'OktaJWT'
To add a package dependency to your Xcode project using Swift Package Manager, select in Xcode File
> Swift Packages
> Add Package Dependency
and enter the repository URL:
https://github.com/okta/okta-ios-jwt.git
To integrate this SDK into your Xcode project using Carthage, specify it in your Cartfile
:
github "okta/okta-ios-jwt"
This library supports validating JWTs by extending the JSONWebToken Swift library. By default, it will fetch the public keys from the OAuth 2.0 /keys
endpoint of the specified authorization server, validate the JWT signature, and verify the token against given assertions.
First, create a dictionary of verification options and instantiate the OktaJWTValidator
:
let options = [
"issuer": "https://{yourOktaDomain}.com/oauth2/default,
"audience": "{aud}", // More info below
...
] as [String: Any]
let validator = OktaJWTValidator(options)
Finally, check to see if the JWT is valid:
let jwtString = "ey...."
do {
let valid = try validator.isValid(jwtString)
print("Valid: \(valid)")
} catch let error {
print("Error: \(error)")
}
When using OpenID Connect as an authentication mechinism, it is important to verify the idToken
returned from the /token
endpoint. To ensure the token is valid, include the following in your verification options:
issuer
: OAuth 2.0 authorization server minting theidToken
.audience
: TheclientID
of your OpenID Connect Application. See Implementing Authentication - Auth Code Flow (Okta) for more information.exp
: The JWT hasn't expired.iat
: The JWT was not issued in the future.nonce
: Cryptographic string generated at the time of authorization.
To learn more about the verification cases and Okta's tokens, take a look at Working with OAuth 2.0 Tokens.
let options = [
"issuer": "https://{yourOktaDomain}.com/oauth2/default",
"audience": "0abc123..",
"exp": true,
"iat": true,
"leeway": 3000, // allow ~5 minutes for clock drift (exp and iat),
"nonce": "1a2b3c4d..."
] as [String: Any]
let validator = OktaJWTValidator(options)
let idToken = "ey..."
do {
let valid = try validator.isValid(idToken)
print("Valid: \(valid)")
} catch let error {
// Misc Error: {error}
}
To ensure proper error handling, you can catch, handle, and recover from specific errors:
do {
let valid = try validator.isValid(idToken)
print("Valid: \(valid)")
} catch OktaJWTVerificationError.malformedJWT {
// Malformed idToken -> "ey.xx"
} catch OktaJWTVerificationError.nonSupportedAlg(let algType) {
// Algorithm type {algType} not supported
} catch OktaJWTVerificationError.invalidIssuer {
// idToken issuer != given issuer
} catch OktaJWTVerificationError.invalidAudience {
// idToken audience != given audience
} catch OktaJWTVerificationError.invalidSignature {
// Invalid signature
} catch OktaJWTVerificationError.expiredJWT {
// idToken expired!
} catch OktaJWTVerificationError.issuedInFuture {
// idToken issued in the future
} catch OktaJWTVerificationError.invalidNonce {
// Invalid nonce
} catch OktaAPIError.noWellKnown {
// Could not retrieve well-known metadata
} catch OktaAPIError.noJWKSEndpoint {
// Unable to capture jwks_uri from well-known
} catch OktaAPIError.noKey {
// Unable to find JWK for Key ID
} catch OktaAPIError.offline {
// Internet connection has not been established (device is offline)
} catch let error {
// Misc Error: {error}
}
You can ask the verifier to assert a custom set of claims, provided that it can be validated as a String.
let options = [
"issuer": "https://{yourOktaDomain}.com/oauth2/default",
"audience": "0abc123..",
"exp": true,
"iat": true,
"preferred_username": "username"
] as [String: Any]
let validator = OktaJWTValidator(options)
let jwtString = "ey..."
do {
let valid = try validator.isValid(jwtString)
print("Valid: \(valid)")
} catch OktaJWTVerificationError.invalidClaim(let claim) {
// Claim {claim} not present
} catch let error {
// Misc Error: {error}
}
jwk
: Pass a JSON Web Key (JWK) to be used over the ones provided by the/keys
endpoint.RSAKey
: Use an existingRSAKey
let options = [
"issuer": "https://{yourOktaDomain}.com/oauth2/default",
"audience": "0abc123..",
...
] as [String: Any]
let jwtString = "ey..."
// Use custom JWK
let givenJWK = [
"alg": "RS256",
"e": "AQAB",
"n": "kR7T4d_6RrTLQ4rdhdexVsGs6D0UwY9gZotmC7BEMvFovvnB0U3fy7WpmUn3aL9ooUJuDj19h17l3" +
"gENKTaZOLucmLVq6HlK8coukxzk8_zhllrWXXFVwB3TlB-zR2EfWi_FKnyHHrSQ0lb1RfO7wberhy" +
"_FK6n6WA5lCMYVfOGVm3aV6vfAojS7y1QzyimytitCRsOnIW7QmlZ1ZtKcEKb0pGdwSAAj-OSldZL" +
"uLBj9B_t6HMq0xPVNhWgtYGDFNARaCIcvuP236VpGsw3EH4zfeKVMpScHC2j3y5JvMefn_iVgBzW7" +
"9qs6QPbC6Y1_yCJv-ZRfur3Tk92Hq82B4w",
"kid": "someKeyId",
"kty": "RSA",
"use": "sig"
] as [String: Any]
let validator = OktaJWTValidator(options, jwk: givenJWK)
do {
let valid = try validator.isValid(jwtString)
print("Valid: \(valid)")
} catch let error {
// Misc Error: {error}
}
// -- OR --
// Use existing RSAKey
let rsaKey = RSAKey.registeredKeyWithTag("myKeyTag")
let validator = OktaJWTValidator(options, key: rsaKey)
do {
let valid = try validator.isValid(jwtString)
print("Valid: \(valid)")
} catch let error {
// Misc Error: {error}
}
We are happy to accept contributions and PRs! Please see the contribution guide to understand how to structure a contribution.