[ADR] API proposal for configuration of External Authorizer based authorization in API Rule

[barchw]

API proposal for configuration of External Authorizer based authorization in APIRules

Status

Proposed: 13.03.2024
Accepted: 27.03.2024

Details

We are going to introduce a new handler for APIRules that allows configuring External Authorizer for services exposed by the user.

The new access strategy will be called extAuth, which follows the camel case naming convention used for previous strategies. The no_auth access strategy will also change its name to noAuth in the future.

Considerations

Should we support combining the extAuth and jwt access strategies?

The Authorization Policy that enables External Authorizer uses action: CUSTOM. This allows the External Authorizer handler to be used alongside other handlers, especially Istio-based JWT. The reason such a configuration is possible is because the CUSTOM actions are evaluated independently, as described in the Istio Authorization Policy documentation. By taking advantage of this, the customer could have a setup that performs both authentication with an OAuth2 Authorization code flow as well as authorization based on the presented JWT.

For example, it is possible to use the following configuration:

• An AuthorizationPolicy enabling External Authorizer:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: ext-authz
spec:
  action: CUSTOM
  provider:
    name: oauth2-proxy
  rules:
  - to:
    - operation:
        paths:
        - /headers

• and an AuthorizationPolicy restricting the access on a claim-based strategy:

apiVersion: security.istio.io/v1
kind: AuthorizationPolicy
metadata:
  name: require-claim
spec:
  action: ALLOW
  rules:
  - to:
      - operation:
        paths:
          - /headers
    when:
      - key: request.auth.claims[some_claim]
        values:
          - some_value

• and an additional RequestAuthentication ensuring that Istio recognizes the issuer:

apiVersion: security.istio.io/v1beta1
kind: RequestAuthentication
metadata:
  name: httpbin
spec:
  jwtRules:
  - issuer: https://example.com
    jwksUri: https://example.com/.well-known/jwks.json

Decision
We decided to enforce that the user must use one and only one accessStrategy per every entry in spec.rules. Therefore, we don't support combining both extAuth and jwt access strategies.
Instead, we would like to enable configuration within the extAuth strategy scope and allow the creation of an ALLOW AuthorizationPolicy based on that configuration.
As a result, the proposed API would look as follows:

accessStrategy: # Validation: there needs to be one access strategy and only one
  extAuth: # There can be multiple external authorizers configured
    - name: oauth2-proxy
      # Will most likely configure the same fields as in `jwt` access strategy
      authentications:
        - issuer: https://example.com
          jwksUri: https://example.com/.well-known/jwks.json            
      authorizations:
        - audiences: ["app1"]

Should we support multiple External Authorizers?

We must consider whether a configuration that uses multiple external authorizers on one path is valuable. Technically, such configuration would be possible, as all CUSTOM policies must result in the allow response for the request to be allowed.

Decision
We decided to support multiple External Authorizers. Since there are some useful configurations that our users might want to have.

API Proposal

We have discussed how the API would be structured to support future versions, specifically v1beta2/v1. We decided that accessStrategy will hold a single entry, either extAuth, jwt, or noAuth. The user must define only one access strategy in every rule of the spec.rules field.

See the following sample, which uses the proposed API:

apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: service-secured
spec:
  gateway: kyma-system/kyma-gateway
  host: httpbin
  service:
    name: httpbin
    port: 8000
  rules:
    - path: /headers
      methods: ["GET"]
      mutators:
        - ***
      accessStrategy: # Validation: there needs to be one access strategy, and only one
        extAuth: # There can be multiple external authorizers configured
          - name: oauth2-proxy # Validation: Check if there is that authorizer in Istio mesh config
             authentications:
               - issuer: https://example.com
               jwksUri: https://example.com/.well-known/jwks.json            
             authorizations:
                - audiences: ["app1"]
        ## OR
        jwt:
          authentications:
            - issuer: https://example.com
              jwksUri: https://example.com/.well-known/jwks.json            
          authorizations:
            - audiences: ["app1"]
        ## OR
        noAuth: true

[pbochynski]

I have a question about a use case I am currently on. I want to add an external authorizer for geo-blocking (prevent access from embargoed countries). Such an authorizer should be triggered on all paths and methods. Can your API proposal model this use case?

[barchw]

In this case you could use the following selector:

path: "/.*"
methods: ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT",  "OPTIONS", "TRACE", "PATCH"]
accessStrategy:
  extAuth:
    name: geo-blocker

Geo-blocking could be a part of the external authoriser logic (with the name of geo-blocker).
Or the external authoriser could provide a JWT that would contain a claim based on the user country, and authorizations would restrict the access based on the claim.

[pbochynski]

Can you confirm that with such configuration request to header path will execute both authorizers (geo-blocking and oauth2-proxy)?

apiVersion: gateway.kyma-project.io/v1beta1
kind: APIRule
metadata:
  name: service-secured
spec:
  gateway: kyma-system/kyma-gateway
  host: httpbin
  service:
    name: httpbin
    port: 8000
  rules:
    - path: "/.*"
      methods: ["GET", "HEAD", "POST", "PUT", "DELETE", "CONNECT",  "OPTIONS", "TRACE", "PATCH"]
      accessStrategy:
        extAuth:
          name: geo-blocker
    - path: /headers
      methods: ["GET"]
      mutators:
        - ***
      accessStrategy: # Validation: there needs to be one access strategy, and only one
        extAuth:
          name: oauth2-proxy # Validation: Check if there is that authorizer in Istio mesh config
          restrictions:
            authentications:
              - issuer: https://example.com
                jwksUri: https://example.com/.well-known/jwks.json            
            authorizations:
              - audiences: ["app1"]

[werdes72]

Updated the ADR - extAuth field is now an array. It can be configured in the following way:

      accessStrategy: # Validation: there needs to be one access strategy, and only one
        extAuth: # There can be multiple external authorizers configured
          - name: oauth2-proxy # Validation: Check if there is that authorizer in Istio mesh config
            restrictions:
              authentications:
                - issuer: https://example.com
                  jwksUri: https://example.com/.well-known/jwks.json            
              authorizations:
                - audiences: ["app1"]
          - name: geo-blocker

[pbochynski]

Thanks for update. Looks good to me!