[ADR] API proposal for APIRule v1beta2

[werdes72]

APIRule v1beta2 API Proposal

Date: 2024-03-22

Status

• Accepted: 10.04.2024
• Proposed: 22.03.2024

Context

Due to the deprecation of Ory and the introduction of new features in API Gateway, the next version of APIRule resource needs to be defined.

Changes:

• accessStrategies field is replaced with extAuths, jwt and noAuth
• multiple hosts are allowed

Spec:

Field	Mandatory	Description	Validation
gateway	YES	Specifies the Istio Gateway.
corsPolicy	NO	Allows configuring CORS headers sent with the response. If corsPolicy is not defined, the default values are applied. If corsPolicy is configured, only the CORS headers defined in the APIRule are sent with the response. For more information, see the decision record.
corsPolicy.allowHeaders	NO	Specifies headers allowed with the Access-Control-Allow-Headers CORS header.
corsPolicy.allowMethods	NO	Specifies methods allowed with the Access-Control-Allow-Methods CORS header.
corsPolicy.allowOrigins	NO	Specifies origins allowed with the Access-Control-Allow-Origins CORS header.
corsPolicy.allowCredentials	NO	Specifies whether credentials are allowed in the Access-Control-Allow-Credentials CORS header.
corsPolicy.exposeHeaders	NO	Specifies headers exposed with the Access-Control-Expose-Headers CORS header.
corsPolicy.maxAge	NO	Specifies the maximum age of CORS policy cache. The value is provided in the Access-Control-Max-Age CORS header.
hosts	YES	Specifies the Service's communication address for inbound external traffic. If only the leftmost label is provided, the default domain name is used.	The full domain name or the leftmost label cannot contain the wildcard character *.
service.name	NO	Specifies the name of the exposed Service.
service.namespace	NO	Specifies the namespace of the exposed Service.
service.port	NO	Specifies the communication port of the exposed Service.
timeout	NO	Specifies the timeout for HTTP requests in seconds for all Access Rules. The value can be overridden for each Access Rule. If no timeout is specified, the default timeout of 180 seconds applies.	The maximum timeout is limited to 3900 seconds (65 minutes).
rules	YES	Specifies the list of Access Rules.
rules.service	NO	Services definitions at this level have higher precedence than the Service definition at the spec.service level.
rules.path	YES	Specifies the path of the exposed Service. If the configured path of a rule overlaps with the path of another rule, e.g. if a rule defines * in the path, the configuration of both rules is applied.	Value can be either exact path or a wildcard *.
rules.methods	NO	Specifies the list of HTTP request methods available for spec.rules.path. The list of supported methods is defined in RFC 9910: HTTP Semantics and RFC 5789: PATCH Method for HTTP.
rules.mutators	NO	Specifies the list of the request mutators.	Currently, the Headers and Cookie mutators are supported. For more information, see the documentation.
rules.noAuth	NO	Setting noAuth to true disables authorization.	When noAuth is set to true, it is not allowed to define jwt or extAuth on the same path.
rules.extAuths	NO	Specifies the list of external authorizers. For more information see below and the External Authorizer ADR.
rules.extAuth.name	NO	Specifies the name of the external authorizer.
rules.jwt	NO	Specifies the Istio JWT access strategy. For more information see JWT Access Strategy and the bellow table.
rules.jwt.authentications	YES	Specifies the list of authentication objects.
rules.jwt.authentications.issuer	YES	Identifies the issuer that issued the JWT. The value must be a URL. Although HTTP is allowed, it is recommended that you use only HTTPS endpoints.
rules.jwt.authentications.jwksUri	YES	Contains the URL of the provider’s public key set to validate the signature of the JWT. The value must be a URL. Although HTTP is allowed, it is recommended that you use only HTTPS endpoints.
rules.jwt.authentications.fromHeaders	NO	Specifies the list of headers from which the JWT token is extracted.
rules.jwt.authentications.fromHeaders.name	YES	Specifies the name of the header.
rules.jwt.authentications.fromHeaders.prefix	NO	Specifies the prefix used before the JWT token. The default is Bearer .
rules.jwt.authentications.fromParams	NO	Specifies the list of parameters from which the JWT token is extracted.
rules.jwt.authorizations	NO	Specifies the list of authorization objects.
rules.jwt.authorizations.requiredScopes	NO	Specifies the list of required scope values for the JWT.
rules.jwt.authorizations.audiences	NO	Specifies the list of audiences required for the JWT.
rules.timeout	NO	Specifies the timeout, in seconds, for HTTP requests made to spec.rules.path. Timeout definitions set at this level take precedence over any timeout defined at the spec.timeout level.	The maximum timeout is limited to 3900 seconds (65 minutes).

Examples

• Multiple hosts with external authorizers and jwt:

apiVersion: gateway.kyma-project.io/v1beta2
kind: APIRule
metadata:
  name: service-config
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - api1.example.com
    - api2.example.com
  service:
    name: httpbin
    port: 8000
  rules:
    - path: /headers
      methods: ["GET"]
      extAuths:
        - name: oauth2-proxy
        - name: geo-blocker
      jwt:
        authentications:
          - issuer: https://example.com
            jwksUri: https://example.com/.well-known/jwks.json
        authorizations:
          - audiences: ["app1"]

• One host with JWT:

apiVersion: gateway.kyma-project.io/v1beta2
kind: APIRule
metadata:
  name: service-config
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - app1.example.com
  service:
    name: httpbin
    port: 8000
  rules:
    - path: * # Should be warning user that it is not recommended, as it applies to all paths
      methods: ["GET"]
      jwt:
        authentications:
          - issuer: https://example.com
            jwksUri: https://example.com/.well-known/jwks.json
        authorizations:
          - audiences: ["app1"]

• One host with noAuth:

apiVersion: gateway.kyma-project.io/v1beta2
kind: APIRule
metadata:
  name: service-config
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - app1.example.com
  service:
    name: httpbin
    port: 8000
  rules:
    - path: /headers
      methods: ["GET"]
      noAuth: true

• Istio mutators:

apiVersion: gateway.kyma-project.io/v1beta2
kind: APIRule
metadata:
  name: service-config
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - app1.example.com
  service:
    name: httpbin
    port: 8000
  rules:
    - path: /headers
      methods: ["GET"]
      mutators:
        - handler: header
          config:
            headers:
              X-Custom-Auth: "%REQ(Authorization)%"
              X-Some-Data: "some-data"
        - handler: cookie
          config:
            cookies:
              user: "test"
      jwt:
        authentications:
          - issuer: https://example.com
            jwksUri: https://example.com/.well-known/jwks.json
        authorizations:
          - audiences: ["app1"]

• Multiple paths with different configurations:

apiVersion: gateway.kyma-project.io/v1beta2
kind: APIRule
metadata:
  name: service-config
spec:
  gateway: kyma-system/kyma-gateway
  hosts:
    - api1.example.com
  service:
    name: httpbin
    port: 8000
  rules:
    - path: /test
      noAuth: true
    - path: /login
      extAuths:
        - name: geoBlocking
    - path: /headers
      jwt:
        authentications:
          - issuer: https://example.com
            jwksUri: https://example.com/.well-known/jwks.json
        authorizations:
          - audiences: ["app1"]
    - path: /image
      extAuths:
        - name: oauth2-proxy

[pbochynski]

Why do external authorizers have authentications and authorizations? Is it just for oauth2_proxy?

[strekm]

@pbochynski it was decided in previous specific to extAuth ADR that within we also allow to restrict access based on JWT (additional AP)

[werdes72]

Proposal 3

No more accessStrategy field, we can use jwt and extAuths fields instead.

rules:
  - path: test
    extAuths:
      - name: geoBlocking
    jwt:
      authentications:
        - issuer: https://example.com
          jwksUri: https://example.com/.well-known/jwks.json
      authorizations:
        - audiences: ["app1"]

rules:
  - path: test
    extAuths:
      - name: oauth2-proxy
      - name: geoBlocking
    jwt:
      authentications:
        - issuer: https://example.com
          jwksUri: https://example.com/.well-known/jwks.json
      authorizations:
        - audiences: ["app1"]
  - path: headers
    noAuth: true

rules:
  - path: test
    noAuth: true
  - path: * # Should be warning user that it is not recommended, as it applies to all paths
    extAuths:
      - name: geoBlocking
  - path: headers
    jwt:
      authentications:
        - issuer: https://example.com
          jwksUri: https://example.com/.well-known/jwks.json
      authorizations:
        - audiences: ["app1"]
  - path: image
    extAuths:
      - name: oauth2-proxy

extAuth + noAuth - cannot be together
jwt + noAuth - cannot be together

[pbochynski]

Proposal 3

No more accessStrategy field, we can use jwt and extAuths fields instead.

Now it looks much better! :)
Thanks.