Access control with JWKS

Airlock Microgateway supports authorization based on JWT in the premium edition. Restrictions for token claims can be applied and roles required for accessing mappings can be extracted from the token. If any extraction method is enabled, a matching token sent with the request will be verified and decoded. If the JWT is missing (if mandatory), invalid, violates any claim restrictions, or does not provide the needed credentials to access the mapping, the request will be rejected. For a configured redirect, this will result in a redirect to the denied access URL, all other authentication flows result in a response with HTTP status code 403.

  • Configuration of JWKS requires settings for:
  • JWKS Providers for local or remote JWKS sources.
  • Configuration of access control using a JWKS source in mappings.

JWKS can be configured using the DSL options starting with jwks_providers. For details on all available options, refer to the DSL reference.

JWKS providers can be configured as a static source deployed with the gateway (jwks_providers.local[]) or as an external service (jwks_providers.remote[]).

Configuration of local JWKS providers

Local JWKS providers can be configured in the config.yaml using inline JSON code or by referencing a mounted JWKS file.

JWKS contain sensitive information. Please make sure that access to the config.yaml is restricted appropriately if you use the inline configuration style for local JWKS providers.

The following code snippet is an example of an inline JWKS configuration for a local provider:

# local jwks service using an inline JWKS
 jwks_providers:
   local:
     - name: echoserver-jwks
       jwks: |
         {
             "keys": 
                [     
                {
                    "kty": "oct",
                    "use": "sig",
                    "alg": "HS512",
                    "k": "VW5kZXJzd...",
                    "key_ops": ["verify"]
                },
                {
                    "kty": "oct",
                    "use": "enc",
                    "alg": "dir",
                    "k": "CTwn8ujB...",
                    "key_ops": ["decrypt"]
                }
            ]
        }

The following code snippet is an example of a configuration for a local JWKS provider using a reference to a mounted JWKS file:

# local jwks service using a reference to a mounted JWKS file.                     
jwks_providers:
  local:
    - name: jwks_local
      jwks_file:  /config/jwks/jwks.json

Configuration of remote JWKS providers

  • For a remote JWKS provider:
  • The service_url needs to point to a JSON file. See JWKS and JWK selection by filtering for information about the content of such a file.
  • A remote JWKS source requires a secured connection with additional SSL/TLS settings. DSL options for SSL/TLS settings start with jwks_providers.remote[].tls.

The following code snippet is an example of a simple remote provider configuration:

# remote services use certificates at the default location, if not specified otherwise
# see DSL reference for details
jwks_providers:
  refresh_interval: 60  
  remote:    
    - name: jwks_remote
      service_url: https://httpd/jwks.json

In the example above we have configured a refresh_interval in seconds and a service_url that points to a remote jwks.json file. This allows to automatically fetch the JSON file to periodically update the JWKS.

How do remote JWKS providers work?

  • The JWKS is cached on the gateway.
  • The provider service is invoked whenever the gateway configuration is being loaded or reloaded or when the refresh interval is reached.
  • If the provider service invocation fails, the last JWKS fetched will be used until the service can be invoked successfully again.

Note that the option refresh_interval is not applied to local JWKS providers.

Configuration of access control in mappings

  1. The mapping configuration consists of the following parts:
  2. Configuration of token extraction rules.
  3. Configuration of the JWKS providers to use.
  4. Optional configuration of role extraction rules.
  5. Optional configuration of access restrictions based on user roles or request properties.

The following code shows a simple example mapping with access control based on user roles extracted from the access token:

apps:
  - virtual_host:
    mappings:
      - backend_path: /
        backend:
          hosts:
            - name: echo
              protocol: 'http'
              port: 8080
# configuration of access token and role extraction 
# signature verification uses the local jwks service
        access_token:
          mandatory: true
          extraction:
            mode: header
            header:
              regex:
                pattern: "^Authorization: Bearer (.*)$"
              substitution: $1
          signature_mandatory: true
          jwks_providers: 
            - jwks_local   
          roles:
            - claim: roles
              extraction:
                regex:
                  pattern: ^(myrole)$
                substitution: $1
# configuration of access control based on user roles extracted from the access token
        auth:
          flow: deny_access
          access:
            - roles
              - myrole