JWT-based access control

You can use JWTs to authorize access to StepZen endpoints by adding the identity information needed to verify the JWT to your config.yaml.

If you're using an OpenID based identity provider, then it is as simple as adding your JWKS URL, i.e. https://SITE/.well-known/jwks.json, to your config.yaml

Copy
deployment:
  identity:
    jwksendpoint: https://SITE/.well-known/jwks.json

In fact, this should work with any OAuth system that supports a jwksendpoint which often referred to as the JWKS URL or URI.

There is a mechanism to add individual keys to the endpoint identity. It is only recommended except for testing, debugging, and as a fallback.

Copy
deployment:
  identity:
    keys:
    # do not recommend the use of HS256 except for simple testing
    - algorithm: HS256
      key: sesame-test-open
      keyid: 1
    - algorithm: RS256
      # ParsePKCS1PublicKey is the preferred format
      key: PEMBlock
      keyid: 2

The preferred form of the RS256 key is a RSA CERT in PKCS1PublicKey format (usually encoded as "RSA PUBLIC KEY" PEM blocks). A X.509 PEM encoded certificate will work as well (.crt files, "BEGIN CERTFICTATE" PEM block). keyid is required if more than one key is specified as through identity.key and will be used to match the JWT's keyid. The algorithms available in this mode are limited, but include RS384 and RS512. This document is not complete on this topic and you may wish to consult with the StepZen team as to your unique requirements.

All reserved claims are checked as appropriate. So a claim with a invalid exp will be rejected, etc. In addition, you will need to restrict the endpoint to having certain reserved claims or claim values. To do so, add those to your identity definition. This:

Copy
deployment:
  identity:
    ....
    issuer:   "http://domainname",
    audience: "https://domainname",
    claims:   ["nbf", "iat", "exp"],

would force the issuer, audience to match and for the listed claims (not before, issued at, and expiration) to exist. Only a single issuer or audience are checked for an endpoint.

JWT tokens often have custom (private) claims. Custom private claims are typically name spaced. StepZen does not predefine custom claims and allows you to model against your unique requirements. In referencing these custom claims, we'll use $jwt.CUSTOM.x where CUSTOM represents your namespace.

Note: StepZen's JWT mechanisms do not require the use of access or identity tokens, the choice is up to you. https://auth0.com/blog/id-token-access-token-what-is-the-difference/