TokenExchange

microgateway.airlock.com/v1alpha1

TokenExchange defines an OAuth Token Exchange (RFC 8693).
This feature may be used when the upstream backend requires a different token than the downstream JWT or OIDC Access Token.

​
apiVersion: microgateway.airlock.com/v1alpha1
kind: TokenExchange
metadata:
  name: token-exchange-example
spec:
  tokenEndpoint:
    endpoint:
      uri: https://iam.airlock.com/token
      tls:
        protocol:
          minimum: TLSv1_3
      timeouts:
        connect: 2s
    credentials:
      clientPassword:
        method: BasicAuth
        clientID: my-id
        clientSecret:
          secretRef:
            name: client-password

  requestedTokenType: urn:ietf:params:oauth:token-type:jwt
  audiences:
  - "https://api.airlock.com/realms/a"
  - my-audience
  resources:
  - https://resource.airlock.com/

  scopes:
    - db

TokenExchange

Field Description Type Required Default Allowed Values
metadata defines the resource’s metadata ObjectMeta yes
spec defines the desired token exchange configuration. object yes

TokenExchange.spec

Field Description Type Required Default Allowed Values
audiences specifies target audiences for which the token is requested. string[] no
requestedTokenType specifies to request a specific token type (URN), e.g., “urn:ietf:params:oauth:token-type:jwt”.
See https://datatracker.ietf.org/doc/html/rfc8693#name-token-type-identifiers for more information.		 string no
resources specifies target resources for which the token is requested. string[] no
scopes specifies the scopes to request for the exchanged token. string[] no
subjectTokenType specifies the type (URN) of the token being exchanged.
If not specified, the type is inferred based on the issued token type of the previous token exchange or based on the configured authentication method, i.e. urn:ietf:params:oauth:token-type:jwt for JWT and urn:ietf:params:oauth:token-type:access_token for OIDC.

See https://datatracker.ietf.org/doc/html/rfc8693#name-token-type-identifiers for more information.		 string no
tokenEndpoint specifies how to connect to the token endpoint of the OAuth2 authorization server handling the token exchanges. object yes

TokenExchange.spec.tokenEndpoint

Field Description Type Required Default Allowed Values
credentials used for client authentication with the endpoint. object yes clientPassword{}, none{}
endpoint configuration. object yes

TokenExchange.spec.tokenEndpoint.credentials

Field Description Type Required Default Allowed Values
clientPassword authenticates with clientID (username) and clientSecret (password). object no
none specifies to not supply any client credentials.
Note: This is only valid for servers allowing unauthenticated access, which is not recommended.		 object no {}

TokenExchange.spec.tokenEndpoint.credentials.clientPassword

Field Description Type Required Default Allowed Values
clientID specifies the client_id (username). string yes
clientSecret specifies the client_secret (password). object yes
method specifies in which format the client secret is sent with the authorization request. enum no BasicAuth BasicAuth, FormURLEncoded

TokenExchange.spec.tokenEndpoint.credentials.clientPassword.clientSecret

Field Description Type Required Default Allowed Values
secretRef specifies the kubernetes secret containing the client password with key “client.secret”. object yes

TokenExchange.spec.tokenEndpoint.credentials.clientPassword.clientSecret.secretRef

Field Description Type Required Default Allowed Values
name of the resource string yes

TokenExchange.spec.tokenEndpoint.endpoint

Field Description Type Required Default Allowed Values
timeouts specifies the timeouts when interacting with the Token endpoint. object no
tls defines TLS settings. object no
uri specifies the endpoint address. string yes

TokenExchange.spec.tokenEndpoint.endpoint.tls

Field Description Type Required Default Allowed Values
certificateVerification specifies how the certificate presented by the server is verified. object no publicCAs{...} custom{}, disabled{}, publicCAs{}
ciphers defines a list of the supported TLS cipher suites. For details on cipher list refer to the envoy documentation on cipher_suites in common tls configuration. string[] no
protocol defines the supported TLS protocol versions. object no

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification

Field Description Type Required Default Allowed Values
custom explicitly specifies how the server certificate should be verified.
Typical use cases include specifying a custom CA and SAN match when working with self-signed certificates or pinning a specific public key.		 object no
disabled specifies to trust any certificate without verification.
THIS IS INSECURE AND SHOULD ONLY BE USED FOR TESTING.		 object no {}
publicCAs specifies to only accept certificates with a SAN matching “uri” and which are signed by a CA which is either directly or indirectly trusted by any of the root CA certificates shipped with the Airlock Microgateway Engine’s base image. object no {}

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom

Field Description Type Required Default Allowed Values
allowedSANs is a list of matchers to verify the Subject Alternative name. If specified, it will verify that the
Subject Alternative Name of the presented certificate matches one of the specified matchers. The matching uses “any” semantics,
that is to say, the SAN is verified if at least one matcher is matched.
AllowedSANs requires trustedCA to be set.		 object[] no
certificatePinning defines constraints the presented certificate must fulfill.
If more than one constraint is configured only one must be satisfied.
At least one of allowedSPKIs and allowedHashes must be set.		 object no
crl defines the Certificate Revocation List (CRL) settings. object no
trustedCA defines which CA certificates are trusted. object no

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.allowedSANs[]

Field Description Type Required Default Allowed Values
matcher defines the string matcher for the SAN value. object yes contains{}, exact{}, prefix{}, regex{}, suffix{}
sanType defines the type of SAN matcher. enum yes DNS, Email, IPAddress, URI

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.allowedSANs[].matcher

Field Description Type Required Default Allowed Values
contains defines a substring match on the substring specified here. Empty contains match is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
ignoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). bool no false true, false
prefix defines a prefix match on the prefix specified here. Empty prefix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
regex defines a regex match on the regular expression specified here. Google’s RE2 regex engine is used.
The regex matches only single-line by default, even with “.*”. To match a multi-line string prepend (?s) to your regex.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no
suffix defines a suffix match on the suffix specified here. Empty suffix is not allowed, please use regex instead.
Only one of exact, prefix, suffix, regex or contains can be set.		 string no

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.crl

Field Description Type Required Default Allowed Values
lists defines the list of secretRefs containing Certificate Revocation Lists. object[] no
validationMode defines whether only the leaf certificate or also the CA certs should be checked. enum no VerifyChain VerifyChain, VerifyLeafCertOnly

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.crl.lists[]

Field Description Type Required Default Allowed Values
secretRef defines the reference to a secret containing one or more CRL’s (in PEM format) under the key ‘ca.crl’. object yes

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.crl.lists[].secretRef

Field Description Type Required Default Allowed Values
name of the resource string yes

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.certificatePinning

Field Description Type Required Default Allowed Values
allowedHashes is a list of hex-encoded SHA-256 hashes.
If specified, it will verify that the SHA-256 of the DER-encoded presented certificate matches one of the specified values.		 string[] no
allowedSPKIs is a list of base64-encoded SHA-256 hashes.
If specified, it will verify that the SHA-256 of the DER-encoded Subject Public Key Information (SPKI) of the presented certificate matches one of the specified values.		 string[] no

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.trustedCA

Field Description Type Required Default Allowed Values
certificates defines the list of secretRefs containing trusted CA certificates. object[] yes
verificationDepth specifies the hops in the certificate chain at which validation is performed.
1 means that either the leaf or the signing CA must be in the set of trusted certificates.		 int32 no 1 [0, 2147483647]

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.trustedCA.certificates[]

Field Description Type Required Default Allowed Values
secretRef defines the reference to a secret containing one or more CA certificates under the key ‘ca.crt’. object yes

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification.custom.trustedCA.certificates[].secretRef

Field Description Type Required Default Allowed Values
name of the resource string yes

TokenExchange.spec.tokenEndpoint.endpoint.tls.protocol

Field Description Type Required Default Allowed Values
maximum supported TLS version. enum no TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3
minimum supported TLS version. enum no TLSv1_0, TLSv1_1, TLSv1_2, TLSv1_3

TokenExchange.spec.tokenEndpoint.endpoint.timeouts

Field Description Type Required Default Allowed Values
connect specifies the timeout for establishing a connection. string (duration) no 5s See link
maxDuration specifies the response timeout. string (duration) no 15s See link