Using JWT-based access control

You can use JWTs (Java Web Tokens) to authorize access to endpoints by adding the identity information needed to verify the JWT into your config.yaml file.

If you're using an OpenID based identity provider, then it is as simple as adding your JWKS URL to your config.yaml as shown in the following example:

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

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

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

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 an RSA CERT in PKCS1PublicKey format (usually encoded as "RSA PUBLIC KEY" PEM blocks). An X.509 PEM encoded certificate will work as well (.crt files, "BEGIN CERTFICTATE" PEM block). The 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. You might want to consult with IBM Support about your unique requirements.

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

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

This definition requires that the issuer and audience match, and that 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. API Connect for GraphQL 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.