TokenExchange

microgateway.airlock.com/v1alpha1

TokenExchange configures 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
apiVersion: microgateway.airlock.com/v1alpha1
kind: TokenExchange
metadata:
  name: default

TokenExchange

Field Type Description Required Default Allowed Values
metadata ObjectMeta Refer to Kubernetes API documentation for fields of metadata yes
spec object Specification of the Token Exchange configuration. yes

TokenExchange.spec

Field Type Description Required Default Allowed Values
audiences string[] Audiences specifies target audiences for which the token is requested. no
requestedTokenType string 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.		 no
resources string[] Resources specifies target resources for which the token is requested. no
scopes string[] Scopes specifies the scopes to request for the exchanged token. no
tokenEndpoint object TokenEndpoint specifies how to connect to the token endpoint of the OAuth2 authorization server handling the token exchanges. yes

TokenExchange.spec.tokenEndpoint

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

TokenExchange.spec.tokenEndpoint.credentials

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

TokenExchange.spec.tokenEndpoint.credentials.clientPassword

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

TokenExchange.spec.tokenEndpoint.credentials.clientPassword.clientSecret

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

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

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

TokenExchange.spec.tokenEndpoint.endpoint

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

TokenExchange.spec.tokenEndpoint.endpoint.tls

Field Type Description Required Default Allowed Values
certificateVerification object CertificateVerification specifies how the certificate presented by the server is verified. no publicCAs{...} custom{}, disabled{}, publicCAs{}
ciphers string[] 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. no
protocol object Protocol defines the supported TLS protocol versions. no

TokenExchange.spec.tokenEndpoint.endpoint.tls.certificateVerification

Field Type Description Required Default Allowed Values
custom object 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.		 no
disabled object Disabled specifies to trust any certificate without verification.
THIS IS INSECURE AND SHOULD ONLY BE USED FOR TESTING.		 no
publicCAs object 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. no

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

Field Type Description Required Default Allowed Values
allowedSANs object[] 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.		 no
certificatePinning object 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.		 no
crl object CRL defines the Certificate Revocation List (CRL) settings. no
trustedCA object TrustedCA defines which CA certificates are trusted. no

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

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

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

Field Type Description Required Default Allowed Values
contains string 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.		 no
exact string Exact defines an explicit match on the string specified here.
Only one of exact, prefix, suffix, regex or contains can be set.		 no
ignoreCase bool IgnoreCase indicates whether the matching should be case-insensitive. In case of a regex match, the regex gets wrapped with a group (?i:...). no false true, false
prefix string 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.		 no
regex string 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.		 no
suffix string 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.		 no

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

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

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

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

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

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

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

Field Type Description Required Default Allowed Values
allowedHashes string[] 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.		 no
allowedSPKIs string[] 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.		 no

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

Field Type Description Required Default Allowed Values
certificates object[] Certificates defines the list of secretRefs containing trusted CA certificates. yes
verificationDepth uint32 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.		 no 1 [0, 4294967295]

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

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

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

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

TokenExchange.spec.tokenEndpoint.endpoint.tls.protocol

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

TokenExchange.spec.tokenEndpoint.endpoint.timeouts

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