AuthConfig

Proto: auth_config.proto

Package: enterprise.gloo.solo.io

Types:

AccessTokenValidation

Field Description
introspectionUrl (string)

The URL for the OAuth2.0 Token Introspection endpoint. If provided, the (opaque) access token provided or received from the oauth authorization endpoint will be validated against this endpoint, or locally cached responses for this access token. This field is deprecated as it does not support authenticated introspection requests
jwt (JwtValidation)

Validate access tokens that conform to the JSON Web Token (JWT) specification.
introspection (IntrospectionValidation)

Defines how (opaque) access tokens, received from the oauth authorization endpoint, are validated OAuth2.0 Token Introspection specification.
userinfoUrl (string)

The URL for the OIDC userinfo endpoint. If provided, the (opaque) access token provided or received from the oauth endpoint will be queried and the userinfo response (or cached response) will be added to the AuthorizationRequest state under the “introspection” key. This can be useful to leverage the userinfo response in, for example, an external auth server plugin.
cacheTimeout (google.protobuf.Duration)

How long the token introspection and userinfo endpoint response for a specific access token should be kept in the in-memory cache. The result will be invalidated at this timeout, or at “exp” time from the introspection result, whichever comes sooner. If omitted, defaults to 10 minutes. If zero, then no caching will be done.
requiredScopes (AccessTokenValidation.ScopeList)

Require access token to have all of the scopes in the given list. This configuration applies to both opaque and JWT tokens. In the case of opaque tokens, this will check the scopes returned in the “scope” member of introspection response (as described in Section 2.2 of RFC7662. In case of JWTs the scopes to be validated are expected to be contained in the “scope” claim of the token in the form of a space-separated string. Omitting this field means that scope validation will be skipped.

AccessTokenValidation.ScopeList

Field Description
scope (repeated string)

AerospikeApiKeyStorage

Field Description
hostname (string)

The hostname or IP address of one of the cluster members The client will discover other members of the cluster once a connection has been established.
namespace (string)

The Aerospike namespace to use for storage. Defaults to “solo-namespace”
set (string)

The Aerospike set to use for storage of apikeys. Defaults to “apikeys”
port (int32)

The port on which to connect to the Aerospike server. Defaults to 3000
batchSize (int32)

commitAll (uint32)

commit_all indicates the server should wait until successfully committing master and all replicas.
commitMaster (uint32)

commit_master indicates the server should wait until successfully committing master only.
readModeSc (AerospikeApiKeyStorage.readModeSc)

Read settings for strong consistency (SC) Defaults to read_mode_sc_session
readModeAp (AerospikeApiKeyStorage.readModeAp)

Read settings for availability (AP) Defaults to read_mode_ap_one
nodeTlsName (string)

TLS Settings, mtls is enabled on the server side
certPath (string)

keyPath (string)

allowInsecure (bool)

skip the client verifying the server's certificate chain and host name
rootCaPath (string)

If the RootCA is not set, add the system certs bt default
tlsVersion (string)

TLS version, defaults to 1.3
tlsCurveGroups (repeated AerospikeApiKeyStorage.tlsCurveID)

TLS identifiers for the elliptic curves used

AerospikeApiKeyStorage.readModeAp

Field Description
readModeApOne (uint32)

one indicates that a single node should be involved in the read operation.
readModeApAll (uint32)

all indicates that all duplicates should be consulted in the read operation.

AerospikeApiKeyStorage.readModeSc

Field Description
readModeScSession (uint32)

session ensures this client will only see an increasing sequence of record versions. Server only reads from master. This is the default.
readModeScLinearize (uint32)

linearize ensures ALL clients will only see an increasing sequence of record versions. Server only reads from master.
readModeScReplica (uint32)

replica indicates that the server may read from master or any full (non-migrating) replica. Increasing sequence of record versions is not guaranteed.
readModeScAllowUnavailable (uint32)

allow_unavailable indicates that the server may read from master or any full (non-migrating) replica or from unavailable partitions. Increasing sequence of record versions is not guaranteed.

AerospikeApiKeyStorage.tlsCurveID

Field Description
curveP256 (uint32)

curveP384 (uint32)

curveP521 (uint32)

x25519 (uint32)

ApiKey

Field Description
apiKey (string)

The string value of the API key.
labels (repeated string)

A list of labels (key=value) for the apikey secret. These labels are used by the storage driver to facilitate lookups by label
metadata (repeated ApiKey.MetadataEntry)

additional data the client needs associated with this API key

ApiKey.MetadataEntry

Field Description
key (string)

value (string)

ApiKeyAuth

Field Description
labelSelector (repeated ApiKeyAuth.LabelSelectorEntry)

DEPRECATED: use K8sSecretApiKeyStorage to configure secrets storage backend. Values here will be overwritten if values are specified in the storage backend. Identify all valid API key secrets that match the provided label selector. API key secrets must be in one of the watch namespaces for gloo to locate them.
apiKeySecretRefs (repeated core.solo.io.ResourceRef)

DEPRECATED: use K8sSecretApiKeyStorage to configure secrets storage backend. Values here will be overwritten if values are specified in the storage backend. A way to directly reference API key secrets. This configuration can be useful for testing, but in general the more flexible label selector should be preferred.
headerName (string)

When receiving a request, the Gloo Edge Enterprise external auth server will look for an API key in a header with this name. This field is optional; if not provided it defaults to api-key.
headersFromMetadata (repeated ApiKeyAuth.HeadersFromMetadataEntry)

DEPRECATED: use headers_from_metadata_entry
headersFromMetadataEntry (repeated ApiKeyAuth.HeadersFromMetadataEntryEntry)

API key structures might contain additional data (e.g. the ID of the user that the API key belongs to) in the form of extra fields included in the API key metadata structure. This configuration can be used to add this data to the headers of successfully authenticated requests. Each key in the map represents the name of header to be added; the corresponding value determines the key in the API key metadata structure that will be inspected to determine the value for the header.
k8sSecretApikeyStorage (K8sSecretApiKeyStorage)

aerospikeApikeyStorage (AerospikeApiKeyStorage)

ApiKeyAuth.HeadersFromMetadataEntry

Field Description
key (string)

value (ApiKeyAuth.SecretKey)

ApiKeyAuth.HeadersFromMetadataEntryEntry

Field Description
key (string)

value (ApiKeyAuth.MetadataEntry)

ApiKeyAuth.LabelSelectorEntry

Field Description
key (string)

value (string)

ApiKeyAuth.MetadataEntry

For the K8s secret backend, this data is stored as key-value data in the secret itself. For the Aerospike backend, this data is stored as bins on the key's record

Field Description
name (string)

(Required) The key of the API key metadata entry to inspect.
required (bool)

If this field is set to true, Gloo will reject an API key structure that does not contain data for the given key. Defaults to false. In this case, if an API key structure does not contain the requested data, no header will be added to the request.

ApiKeyAuth.SecretKey

DEPRECATED: use generalized MetadataEntry

Field Description
name (string)

DEPRECATED (Required) The key of the API key metadata entry to inspect.
required (bool)

DEPRECATED If this field is set to true, Gloo will reject an API key structure that does not contain data for the given key. Defaults to false. In this case, if an API key structure does not contain the requested data, no header will be added to the request.

ApiKeyCreateRequest

Field Description
apiKeys (repeated ApiKey)

rawApiKeys (repeated string)

ApiKeyCreateResponse

Field Description
apiKeys (repeated ApiKey)

ApiKeyDeleteRequest

Field Description
rawApiKeys (repeated string)

labels (repeated string)

ApiKeyDeleteResponse

ApiKeyReadRequest

Field Description
rawApiKeys (repeated string)

labels (repeated string)

ApiKeyReadResponse

Field Description
apiKeys (repeated ApiKey)

ApiKeySecret

DEPRECATED: use ApiKey

Field Description
apiKey (string)

The string value of the API key.
labels (repeated string)

A list of labels (key=value) for the apikey secret. These labels are used by the storage driver to facilitate lookups by label
metadata (repeated ApiKeySecret.MetadataEntry)

additional data the client needs associated with this API key

ApiKeySecret.MetadataEntry

Field Description
key (string)

value (string)

ApiKeyUpdateRequest

Field Description
upsert (bool)

apiKeys (repeated ApiKey)

rawApiKeys (repeated string)

ApiKeyUpdateResponse

Field Description
apiKeys (repeated ApiKey)

AuthConfigNamespacedStatuses

Field Description
statuses (repeated AuthConfigNamespacedStatuses.StatusesEntry)

AuthConfigNamespacedStatuses.StatusesEntry

Field Description
key (string)

value (AuthConfigStatus)

AuthConfigSpec

This is the user-facing auth configuration. When processed by Gloo, certain configuration types (i.a. oauth, opa) will be translated, e.g. to resolve resource references. See the ExtAuthConfig.AuthConfig for the final config format that will be included in the extauth snapshot.

Field Description
configs (repeated AuthConfigSpec.Config)

List of auth configs to be checked for requests on a route referencing this auth config, By default, every config must be authorized for the entire request to be authorized. This behavior can be changed by defining names for each config and defining boolean_expr below.
State is shared between successful requests on the chain, i.e., the headers returned from each successful auth service get appended into the final auth response.
booleanExpr (google.protobuf.StringValue)

How to handle processing of named configs within an auth config chain. An example config might be: ( basic1 || basic2 || (oidc1 && !oidc2) ) The boolean expression is evaluated left to right but honors parenthesis and short-circuiting.
failOnRedirect (bool)

How the service should handle a redirect response from an OIDC issuer. In the default false mode, the redirect will be considered a successful response, and the client will receive a 302 with a location header. If this is set to true, the client will instead receive a 401 unauthorized response. This is useful in cases where API calls are being made or other such occurrences where the client cannot handle the redirect.

AuthConfigSpec.Config

Field Description
name (google.protobuf.StringValue)

optional: used when defining complex boolean logic, if boolean_expr is defined below. Also used in logging. If omitted, an automatically generated name will be used (e.g. config_0, of the pattern ‘config_$INDEX_IN_CHAIN’). In the case of plugin auth, this field is ignored in favor of the name assigned on the plugin config itself.
basicAuth (BasicAuth)

oauth (OAuth)

oauth2 (OAuth2)

apiKeyAuth (ApiKeyAuth)

pluginAuth (AuthPlugin)

opaAuth (OpaAuth)

ldap (Ldap)

jwt (google.protobuf.Empty)

This is a “dummy” extauth service which can be used to support multiple auth mechanisms with JWT authentication. If Jwt authentication is to be used in the boolean expression in an AuthConfig, you can use this auth config type to include Jwt as an Auth config. In addition, allow_missing_or_failed_jwt must be set on the Virtual Host or Route that uses JWT auth or else the JWT filter will short circuit this behaviour.
passThroughAuth (PassThroughAuth)

AuthConfigStatus

Field Description
state (AuthConfigStatus.State)

State is the enum indicating the state of the resource
reason (string)

Reason is a description of the error for Rejected resources. If the resource is pending or accepted, this field will be empty
reportedBy (string)

Reference to the reporter who wrote this status
subresourceStatuses (repeated AuthConfigStatus.SubresourceStatusesEntry)

Reference to statuses (by resource-ref string: “Kind.Namespace.Name”) of subresources of the parent resource
details (google.protobuf.Struct)

Opaque details about status results

AuthConfigStatus.SubresourceStatusesEntry

Field Description
key (string)

value (AuthConfigStatus)

AuthPlugin

Field Description
name (string)

Name of the plugin
pluginFileName (string)

Name of the compiled plugin file. If not specified, Gloo Edge will look for an “.so” file with same name as the plugin.
exportedSymbolName (string)

Name of the exported symbol that implements the plugin interface in the plugin. If not specified, defaults to the name of the plugin
config (google.protobuf.Struct)

AutoMapFromMetadata

Field Description
namespace (string)

The namespace from which to map metadata

BasicAuth

Field Description
realm (string)

apr (BasicAuth.Apr)

BasicAuth.Apr

Field Description
users (repeated BasicAuth.Apr.UsersEntry)

BasicAuth.Apr.SaltedHashedPassword

Field Description
salt (string)

hashedPassword (string)

BasicAuth.Apr.UsersEntry

Field Description
key (string)

value (BasicAuth.Apr.SaltedHashedPassword)

BufferSettings

Configuration for buffering the request data.

Field Description
maxRequestBytes (uint32)

Sets the maximum size of a message body that the filter will hold in memory. Envoy will return HTTP 413 and will not initiate the authorization process when buffer reaches the number set in this field. Note that this setting will have precedence over failure_mode_allow. Defaults to 4KB.
allowPartialMessage (bool)

When this field is true, Envoy will buffer the message until max_request_bytes is reached. The authorization request will be dispatched and no 413 HTTP error will be returned by the filter.
packAsBytes (bool)

When this field is true, Envoy will send the body sent to the external authorization service with raw bytes.

CustomAuth

Gloo is not expected to configure the ext auth server in this case. This is used with custom auth servers.

Field Description
contextExtensions (repeated CustomAuth.ContextExtensionsEntry)

When a request matches the virtual host, route, or weighted destination on which this configuration is defined, Gloo will add the given context_extensions to the request that is sent to the external authorization server. This allows the server to base the auth decision on metadata that you define on the source of the request.
This attribute is analogous to Envoy's config.filter.http.ext_authz.v2.CheckSettings. See the official Envoy documentation for more details.
name (string)

[Enterprise-only] Only required in the case where multiple auth servers are configured in Settings This name must match a key in the named_extauth Settings.

CustomAuth.ContextExtensionsEntry

Field Description
key (string)

value (string)

DiscoveryOverride

OIDC configuration is discovered at /.well-known/openid-configuration The discovery override defines any properties that should override this discovery configuration https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderMetadata

Field Description
authEndpoint (string)

url of the provider authorization endpoint
tokenEndpoint (string)

url of the provider token endpoint
jwksUri (string)

url of the provider json web key set
scopes (repeated string)

list of scope values that the provider supports
responseTypes (repeated string)

list of response types that the provider supports
subjects (repeated string)

list of subject identifier types that the provider supports
idTokenAlgs (repeated string)

list of json web signature signing algorithms that the provider supports for encoding claims in a jwt
authMethods (repeated string)

list of client authentication methods supported by the provider token endpoint
claims (repeated string)

list of claim types that the provider supports
revocationEndpoint (string)

url of the provider token revocation endpoint
endSessionEndpoint (string)

url of the provider end session endpoint

EndSessionProperties

Field Description
methodType (EndSessionProperties.MethodType)

The method type used by the end session endpoint, defaults to GET.

ExtAuthConfig

@solo-kit:xds-service=ExtAuthDiscoveryService @solo-kit:resource.no_references

This is an internal API used to share configuration between gloo-ee and extauth. Although this API is only used in gloo-ee, rules about breaking changes still apply to ensure we do not get errors during upgrade and downgrade.

Field Description
authConfigRefName (string)

@solo-kit:resource.name This is the identifier of the AuthConfig resource that this configuration is associated with. Any request to the external auth server includes an identifier that is matched against this field to determine which AuthConfig should be applied to it.
configs (repeated ExtAuthConfig.Config)

List of auth configs to be checked for requests on a route referencing this auth config, By default, every config must be authorized for the entire request to be authorized. This behavior can be changed by defining names for each config and defining boolean_expr below.
State is shared between successful requests on the chain, i.e., the headers returned from each successful auth service get appended into the final auth response.
booleanExpr (google.protobuf.StringValue)

How to handle processing of named configs within an auth config chain. An example config might be: ( basic1 || basic2 || (oidc1 && !oidc2) ) The boolean expression is evaluated left to right but honors parenthesis and short-circuiting. Defaults to an empty string, which is interpreted as and-ing the configs.
failOnRedirect (bool)

How the service should handle a redirect response from an OIDC issuer. In the default false mode, the redirect will be considered a successful response, and the client will receive a 302 with a location header. If this is set to true, the client will instead receive a 401 unauthorized response. This is useful in cases where API calls are being made or other such occurrences where the client cannot handle the redirect.

ExtAuthConfig.AccessTokenValidationConfig

Field Description
introspectionUrl (string)

The URL for the OAuth2.0 Token Introspection endpoint. If provided, the (opaque) access token provided or received from the oauth authorization endpoint will be validated against this endpoint, or locally cached responses for this access token. This field is deprecated as it does not support authenticated introspection requests
jwt (ExtAuthConfig.AccessTokenValidationConfig.JwtValidation)

Validate access tokens that conform to the JSON Web Token (JWT) specification.
introspection (ExtAuthConfig.AccessTokenValidationConfig.IntrospectionValidation)

Defines how (opaque) access tokens, received from the oauth authorization endpoint, are validated OAuth2.0 Token Introspection specification.
userinfoUrl (string)

The URL for the OIDC userinfo endpoint. If provided, the (opaque) access token provided or received from the oauth endpoint will be queried and the userinfo response (or cached response) will be added to the AuthorizationRequest state under the “introspection” key. This can be useful to leverage the userinfo response in, for example, an external auth server plugin.
cacheTimeout (google.protobuf.Duration)

How long the token introspection and userinfo endpoint response for a specific access token should be kept in the in-memory cache. The result will be invalidated at this timeout, or at “exp” time from the introspection result, whichever comes sooner. If omitted, defaults to 10 minutes. If zero, then no caching will be done.
requiredScopes (ExtAuthConfig.AccessTokenValidationConfig.ScopeList)

Require access token to have all of the scopes in the given list. This configuration applies to both opaque and JWT tokens. In the case of opaque tokens, this will check the scopes returned in the “scope” member of introspection response (as described in Section 2.2 of RFC7662. In case of JWTs the scopes to be validated are expected to be contained in the “scope” claim of the token in the form of a space-separated string. Omitting this field means that scope validation will be skipped.

ExtAuthConfig.AccessTokenValidationConfig.IntrospectionValidation

Defines how (opaque) access tokens, received from the oauth authorization endpoint, are validated OAuth2.0 Token Introspection

If the token introspection url requires client authentication, both the client_id and client_secret are required. If only one is provided, the config will be rejected. These values will be encoded in a basic auth header in order to authenticate the client.

Field Description
introspectionUrl (string)

The URL for the OAuth2.0 Token Introspection endpoint. If provided, the (opaque) access token provided or received from the oauth authorization endpoint will be validated against this endpoint, or locally cached responses for this access token.
clientId (string)

Your client id as registered with the issuer. Optional: Use if the token introspection url requires client authentication.
clientSecret (string)

Your client secret as registered with the issuer. Optional: Use if the token introspection url requires client authentication.
userIdAttributeName (string)

The name of the introspection response attribute that contains the ID of the resource owner (e.g. sub, username). If specified, the external auth server will use the value of the attribute as the identifier of the authenticated user and add it to the request headers and/or dynamic metadata (depending on how the server is configured); if the field is set and the attribute cannot be found, the request will be denied. This field is optional and by default the server will not try to derive the user ID.

ExtAuthConfig.AccessTokenValidationConfig.JwtValidation

Defines how JSON Web Token (JWT) access tokens are validated.

Tokens are validated using a JSON Web Key Set (as defined in Section 5 of RFC7517), which can be either inlined in the configuration or fetched from a remote location via HTTP. Any keys in the JWKS that are not intended for signature verification (i.e. whose “use” parameter is not “sig”) will be ignored by the system, as will keys that do not specify a “kid” (Key ID) parameter.

The JWT to be validated must define non-empty “kid” and “alg” headers. The “kid” header determines which key in the JWKS will be used to verify the signature of the token; if no matching key is found, the token will be rejected.

If present, the server will verify the “exp”, “iat”, and “nbf” standard JWT claims. Validation of the “iss” claim and of token scopes can be configured as well. If the JWT has been successfully validated, its set of claims will be added to the AuthorizationRequest state under the “jwtAccessToken” key.

Field Description
remoteJwks (ExtAuthConfig.AccessTokenValidationConfig.JwtValidation.RemoteJwks)

Fetches the JWKS from a remote location.
localJwks (ExtAuthConfig.AccessTokenValidationConfig.JwtValidation.LocalJwks)

Loads the JWKS from a local data source.
issuer (string)

Allow only tokens that have been issued by this principal (i.e. whose “iss” claim matches this value). If empty, issuer validation will be skipped.

ExtAuthConfig.AccessTokenValidationConfig.JwtValidation.LocalJwks

Represents a locally available JWKS.

Field Description
inlineString (string)

JWKS is embedded as a string.

ExtAuthConfig.AccessTokenValidationConfig.JwtValidation.RemoteJwks

Specifies how to fetch JWKS from remote and how to cache it.

Field Description
url (string)

The HTTP URI to fetch the JWKS.
refreshInterval (google.protobuf.Duration)

The frequency at which the JWKS should be refreshed. If not specified, the default value is 5 minutes.

ExtAuthConfig.AccessTokenValidationConfig.ScopeList

Field Description
scope (repeated string)

ExtAuthConfig.ApiKeyAuthConfig

NOTE: This configuration is not user-facing and will be auto generated**

Field Description
validApiKeys (repeated ExtAuthConfig.ApiKeyAuthConfig.ValidApiKeysEntry)

A mapping of valid API keys to their associated metadata. This map is automatically populated with the information from the relevant ApiKeys.
headerName (string)

(Optional) When receiving a request, the Gloo Edge Enterprise external auth server will look for an API key in a header with this name. This field is optional; if not provided it defaults to api-key.
headersFromKeyMetadata (repeated ExtAuthConfig.ApiKeyAuthConfig.HeadersFromKeyMetadataEntry)

Determines the key metadata that will be included as headers on the upstream request. Each entry represents a header to add: the key is the name of the header, and the value is the key that will be used to look up the data entry in the key metadata.
k8sSecretApikeyStorage (K8sSecretApiKeyStorage)

aerospikeApikeyStorage (AerospikeApiKeyStorage)

ExtAuthConfig.ApiKeyAuthConfig.HeadersFromKeyMetadataEntry

Field Description
key (string)

value (string)

ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata

Field Description
username (string)

The user is mapped as the name of Secret which contains the ApiKey
metadata (repeated ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata.MetadataEntry)

The metadata present on the ApiKey.

ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata.MetadataEntry

Field Description
key (string)

value (string)

ExtAuthConfig.ApiKeyAuthConfig.ValidApiKeysEntry

Field Description
key (string)

value (ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata)

ExtAuthConfig.Config

Field Description
name (google.protobuf.StringValue)

optional: used when defining complex boolean logic, if boolean_expr is defined below. Also used in logging. If omitted, an automatically generated name will be used (e.g. config_0, of the pattern ‘config_$INDEX_IN_CHAIN’). In the case of plugin auth, this field is ignored in favor of the name assigned on the plugin config itself.
oauth (ExtAuthConfig.OAuthConfig)

oauth2 (ExtAuthConfig.OAuth2Config)

basicAuth (BasicAuth)

apiKeyAuth (ExtAuthConfig.ApiKeyAuthConfig)

pluginAuth (AuthPlugin)

opaAuth (ExtAuthConfig.OpaAuthConfig)

ldap (Ldap)

ldapInternal (ExtAuthConfig.LdapConfig)

Used for LDAP configurations that need service account credentials saved in a secret.
jwt (google.protobuf.Empty)

This is a “dummy” extauth service which can be used to support multiple auth mechanisms with JWT authentication. If Jwt authentication is to be used in the boolean expression in an AuthConfig, you can use this auth config type to include Jwt as an Auth config. In addition, allow_missing_or_failed_jwt must be set on the Virtual Host or Route that uses JWT auth or else the JWT filter will short circuit this behaviour.
passThroughAuth (PassThroughAuth)

ExtAuthConfig.LdapConfig

Field Description
address (string)

Address of the LDAP server to query. Should be in the form ADDRESS:PORT, e.g. ldap.default.svc.cluster.local:389.
userDnTemplate (string)

Template to build user entry distinguished names (DN). This must contains a single occurrence of the “%s” placeholder. When processing a request, Gloo will substitute the name of the user (extracted from the auth header) for the placeholder and issue a search request with the resulting DN as baseDN (and ‘base’ search scope). E.g. “uid=%s,ou=people,dc=solo,dc=io”
membershipAttributeName (string)

Case-insensitive name of the attribute that contains the names of the groups an entry is member of. Gloo will look for attributes with the given name to determine which groups the user entry belongs to. Defaults to ‘memberOf’ if not provided.
allowedGroups (repeated string)

In order for the request to be authenticated, the membership attribute (e.g. memberOf) on the user entry must contain at least of one of the group DNs specified via this option. E.g. []string{ “cn=managers,ou=groups,dc=solo,dc=io”, “cn=developers,ou=groups,dc=solo,dc=io” }
pool (Ldap.ConnectionPool)

Use this property to tune the pool of connections to the LDAP server that Gloo maintains.
searchFilter (string)

Use to set a custom filter when searching a member. Defaults to “(uid=*)".
disableGroupChecking (bool)

Disables group checking, regardless of the value for allowedGroups, and disables validation for the membership attribute of the user entry. Group checking is enabled by default.
groupLookupSettings (ExtAuthConfig.LdapServiceAccountConfig)

Settings for using a separate service account for looking up group membership To use this, you also need to configure credentials

ExtAuthConfig.LdapServiceAccountConfig

Field Description
username (string)

username and password are taken from the secret during gloo-ee translation
password (string)

checkGroupsWithServiceAccount (bool)

If true, Gloo will use the service account to check group membership

ExtAuthConfig.OAuth2Config

Field Description
oidcAuthorizationCode (ExtAuthConfig.OidcAuthorizationCodeConfig)

provide issuer location and let gloo handle OIDC flow for you. requests authorized by validating the contents of ID token. can also authorize the access token if configured.
accessTokenValidationConfig (ExtAuthConfig.AccessTokenValidationConfig)

provide the access token on the request and let gloo handle authorization.
according to https://tools.ietf.org/html/rfc6750 you can pass tokens through: - form-encoded body parameter. recommended, more likely to appear. e.g.: Authorization: Bearer mytoken123 - URI query parameter e.g. access_token=mytoken123 - and (preferably) secure cookies
oauth2Config (ExtAuthConfig.PlainOAuth2Config)

Enterprise-Only: THIS FEATURE IS IN TECH PREVIEW. APIs are versioned as alpha and subject to change. provide issuer location and let Gloo handle Oauth2 flow for you. requests authorized by validating the contents of access token. Prefer to use OIDC for better security.

ExtAuthConfig.OAuthConfig

Deprecated, prefer OAuth2Config

Field Description
clientId (string)

your client id as registered with the issuer
clientSecret (string)

your client secret as registered with the issuer
issuerUrl (string)

The url of the issuer. We will look for OIDC information in issuerUrl+ “.well-known/openid-configuration”
authEndpointQueryParams (repeated ExtAuthConfig.OAuthConfig.AuthEndpointQueryParamsEntry)

extra query parameters to apply to the Ext-Auth service's authorization request to the identity provider.
appUrl (string)

we to redirect after successful auth, if we can't determine the original url this should be your publicly available app url.
callbackPath (string)

a callback path relative to app url that will be used for OIDC callbacks. needs to not be used by the application
scopes (repeated string)

scopes to request in addition to the openid scope.

ExtAuthConfig.OAuthConfig.AuthEndpointQueryParamsEntry

Field Description
key (string)

value (string)

ExtAuthConfig.OidcAuthorizationCodeConfig

Field Description
clientId (string)

your client id as registered with the issuer
clientSecret (string)

your client secret as registered with the issuer
issuerUrl (string)

The url of the issuer. We will look for OIDC information in issuerUrl+ “.well-known/openid-configuration”
authEndpointQueryParams (repeated ExtAuthConfig.OidcAuthorizationCodeConfig.AuthEndpointQueryParamsEntry)

extra query parameters to apply to the Ext-Auth service's authorization request to the identity provider. this can be useful for flows such as PKCE (https://www.oauth.com/oauth2-servers/pkce/authorization-request/) to set the code_challenge and code_challenge_method.
tokenEndpointQueryParams (repeated ExtAuthConfig.OidcAuthorizationCodeConfig.TokenEndpointQueryParamsEntry)

extra query parameters to apply to the Ext-Auth service's token request to the identity provider. this can be useful for flows such as PKCE (https://www.oauth.com/oauth2-servers/pkce/authorization-request/) to set the code_verifier.
appUrl (string)

we to redirect after successful auth, if we can't determine the original url this should be your publicly available app url.
callbackPath (string)

a callback path relative to app url that will be used for OIDC callbacks. needs to not be used by the application
logoutPath (string)

a path relative to app url that will be used for logging out from an OIDC session. should not be used by the application. If not provided, logout functionality will be disabled.
afterLogoutUrl (string)

url to redirect to after logout. This should be a publicly available URL. If not provided, will default to the app_url.
scopes (repeated string)

scopes to request in addition to the openid scope.
session (UserSession)

headers (HeaderConfiguration)

Configures headers added to requests.
discoveryOverride (DiscoveryOverride)

OIDC configuration is discovered at /.well-known/openid-configuration The configuration override defines any properties that should override this discovery configuration For example, the following AuthConfig CRD could be defined as: yaml apiVersion: enterprise.gloo.solo.io/v1 kind: AuthConfig metadata: name: google-oidc namespace: gloo-system spec: configs: - oauth: app_url: http://localhost:8080 callback_path: /callback client_id: $CLIENT_ID client_secret_ref: name: google namespace: gloo-system issuer_url: https://accounts.google.com discovery_override: token_endpoint: "https://token.url/gettoken"
And this will ensure that regardless of what value is discovered at /.well-known/openid-configuration, “https://token.url/gettoken" will be used as the token endpoint
discoveryPollInterval (google.protobuf.Duration)

The interval at which OIDC configuration is discovered at /.well-known/openid-configuration If not specified, the default value is 30 minutes.
jwksCacheRefreshPolicy (JwksOnDemandCacheRefreshPolicy)

If a user executes a request with a key that is not found in the JWKS, it could be that the keys have rotated on the remote source, and not yet in the local cache. This policy lets you define the behavior for how to refresh the local cache during a request where an invalid key is provided
sessionIdHeaderName (string)

If set, the randomly generated session id will be sent to the token endpoint as part of the code exchange The session id is used as the key for sessions in Redis
parseCallbackPathAsRegex (bool)

If set, CallbackPath will be evaluated as a regular expression
autoMapFromMetadata (AutoMapFromMetadata)

If specified, authEndpointQueryParams and tokenEndpointQueryParams will be populated using dynamic metadata values. By default parameters will be extracted from the solo_authconfig_oidc namespace this behavior can be overridden by explicitly specifying a namespace
endSessionProperties (EndSessionProperties)

If specified, these are properties defined for the end session endpoint specifications. Noted here in the OIDC documentation.

ExtAuthConfig.OidcAuthorizationCodeConfig.AuthEndpointQueryParamsEntry

Field Description
key (string)

value (string)

ExtAuthConfig.OidcAuthorizationCodeConfig.TokenEndpointQueryParamsEntry

Field Description
key (string)

value (string)

ExtAuthConfig.OpaAuthConfig

Field Description
modules (repeated ExtAuthConfig.OpaAuthConfig.ModulesEntry)

An optional modules (filename, module content) maps containing modules assist in the resolution of query.
query (string)

The query that determines the auth decision. The result of this query must be either a boolean or an array with boolean as the first element. A boolean true value means that the request will be authorized. Any other value, or error, means that the request will be denied.
options (OpaAuthOptions)

Additional Options for Opa Auth configuration.

ExtAuthConfig.OpaAuthConfig.ModulesEntry

Field Description
key (string)

value (string)

ExtAuthConfig.PlainOAuth2Config

Field Description
clientId (string)

Your client ID as registered with the issuer
clientSecret (string)

Your client secret as registered with the issuer
authEndpointQueryParams (repeated ExtAuthConfig.PlainOAuth2Config.AuthEndpointQueryParamsEntry)

Extra query parameters to apply to the Ext-Auth service's authorization request to the identity provider. These parameters can be useful for flows such as PKCE to set the code_challenge and code_challenge_method.
appUrl (string)

Where to redirect after successful auth, if Gloo can't determine the original URL. Set this field to your publicly available app URL.
callbackPath (string)

A callback path relative to the app URL to be used for OAuth2 callbacks. Do not use this path in the application itself.
scopes (repeated string)

Scopes to request for.
session (UserSession)

Configuration related to the user session.
logoutPath (string)

A path relative to the app URL to use for logging out from an OAuth2 session. Do not use this path in the application itself. If not provided, logout functionality is disabled.
tokenEndpointQueryParams (repeated ExtAuthConfig.PlainOAuth2Config.TokenEndpointQueryParamsEntry)

Extra query parameters to apply to the Ext-Auth service's token request to the identity provider. These parameters can be useful for flows such as PKCE to set the code_verifier.
afterLogoutUrl (string)

URL to redirect to after logout. Set this field to a publicly available URL. If not provided, this value defaults to the app_url value.
authEndpoint (string)

The URL of the provider authorization endpoint.
tokenEndpoint (string)

The URL of the provider token endpoint.
revocationEndpoint (string)

The URL of the provider token revocation endpoint. For more information, refer to https://www.rfc-editor.org/rfc/rfc7009.

ExtAuthConfig.PlainOAuth2Config.AuthEndpointQueryParamsEntry

Field Description
key (string)

value (string)

ExtAuthConfig.PlainOAuth2Config.TokenEndpointQueryParamsEntry

Field Description
key (string)

value (string)

ExtAuthExtension

Auth configurations defined on virtual hosts, routes, and weighted destinations will be unmarshalled to this message.

Field Description
disable (bool)

Set to true to disable auth on the virtual host/route.
configRef (core.solo.io.ResourceRef)

A reference to an AuthConfig. This is used to configure the Gloo Edge Enterprise extauth server.
customAuth (CustomAuth)

Use this field if you are running your own custom extauth server.

GrpcService

Field Description
authority (string)

Set the authority header when calling the GRPC service.

HeaderConfiguration

Field Description
idTokenHeader (string)

If set, the id token will be forward upstream using this header name.
accessTokenHeader (string)

If set, the access token will be forward upstream using this header name.
useBearerSchemaForAuthorization (google.protobuf.BoolValue)

If true, adds the “Bearer” prefix to the upstream access token header value.

HttpService

Field Description
pathPrefix (string)

Sets a prefix to the value of authorization request header Path.
request (HttpService.Request)

response (HttpService.Response)

HttpService.Request

Field Description
allowedHeaders (repeated string)

These headers will be copied from the incoming request to the request going to the auth server. Note that in addition to the user's supplied matchers:
1. Host, Method, Path and Content-Length are automatically included to the list.
2. Content-Length will be set to 0 and the request to the authorization service will not have a message body.
headersToAdd (repeated HttpService.Request.HeadersToAddEntry)

These headers that will be included to the request to authorization service. Note that client request of the same key will be overridden.
allowedHeadersRegex (repeated string)

Headers that match these regex patterns will be copied from the incoming request to the request going to the auth server.

HttpService.Request.HeadersToAddEntry

Field Description
key (string)

value (string)

HttpService.Response

Field Description
allowedUpstreamHeaders (repeated string)

When this is set, authorization response headers that have a header in this list will be added to the original client request and sent to the upstream. Note that coexistent headers will be overridden.
allowedClientHeaders (repeated string)

When this is set, authorization response headers in this list will be added to the client's response when the auth request is denied. Note that when this list is not set, all the authorization response headers, except Authority (Host) will be in the response to the client. When a header is included in this list, Path, Status, Content-Length, WWW-Authenticate and Location are automatically added.
allowedUpstreamHeadersToAppend (repeated string)

When this is set, authorization response headers that have a correspondent match will be added to the client's response. Note that coexistent headers will be appended.

IntrospectionValidation

Defines how (opaque) access tokens, received from the oauth authorization endpoint, are validated OAuth2.0 Token Introspection

If the token introspection url requires client authentication, both the client_id and client_secret are required. If only one is provided, the config will be rejected. These values will be encoded in a basic auth header in order to authenticate the client.

Field Description
introspectionUrl (string)

The URL for the OAuth2.0 Token Introspection endpoint. If provided, the (opaque) access token provided or received from the oauth authorization endpoint will be validated against this endpoint, or locally cached responses for this access token.
clientId (string)

Your client id as registered with the issuer. Optional: Use if the token introspection url requires client authentication.
clientSecretRef (core.solo.io.ResourceRef)

Your client secret as registered with the issuer. Optional: Use if the token introspection url requires client authentication.
userIdAttributeName (string)

The name of the introspection response attribute that contains the ID of the resource owner (e.g. sub, username). If specified, the external auth server will use the value of the attribute as the identifier of the authenticated user and add it to the request headers and/or dynamic metadata (depending on how the server is configured); if the field is set and the attribute cannot be found, the request will be denied. This field is optional and by default the server will not try to derive the user ID.

JwksOnDemandCacheRefreshPolicy

The json web key set (JWKS) (https://tools.ietf.org/html/rfc7517) is discovered at an interval from a remote source. When keys rotate in the remote source, there may be a delay in the local source picking up those new keys. Therefore, a user could execute a request with a token that has been signed by a key in the remote JWKS, but the local cache doesn't have the key yet. The request would fail because the key isn't contained in the local set. Since most IdPs publish key keys in their remote JWKS before they are used, this is not an issue most of the time. This policy lets you define the behavior for when a user has a token with a key not yet in the local cache.

Field Description
never (google.protobuf.Empty)

Never refresh the local JWKS cache on demand. If a key is not in the cache, it is assumed to be malicious. This is the default policy since we assume that IdPs publish keys before they rotate them, and frequent polling finds the newest keys.
always (google.protobuf.Empty)

If a key is not in the cache, fetch the most recent keys from the IdP and update the cache. NOTE: This should only be done in trusted environments, since missing keys will each trigger a request to the IdP. Using this in an environment exposed to the internet will allow malicious agents to execute a DDoS attack by spamming protected endpoints with tokens signed by invalid keys.
maxIdpReqPerPollingInterval (uint32)

If a key is not in the cache, fetch the most recent keys from the IdP and update the cache. This value sets the number of requests to the IdP per polling interval. If that limit is exceeded, we will stop fetching from the IdP for the remainder of the polling interval.

JwtValidation

Defines how JSON Web Token (JWT) access tokens are validated.

Tokens are validated using a JSON Web Key Set (as defined in Section 5 of RFC7517), which can be either inlined in the configuration or fetched from a remote location via HTTP. Any keys in the JWKS that are not intended for signature verification (i.e. whose “use” parameter is not “sig”) will be ignored by the system, as will keys that do not specify a “kid” (Key ID) parameter.

The JWT to be validated must define non-empty “kid” and “alg” headers. The “kid” header determines which key in the JWKS will be used to verify the signature of the token; if no matching key is found, the token will be rejected.

If present, the server will verify the “exp”, “iat”, and “nbf” standard JWT claims. Validation of the “iss” claim and of token scopes can be configured as well. If the JWT has been successfully validated, its set of claims will be added to the AuthorizationRequest state under the “jwtAccessToken” key.

Field Description
remoteJwks (JwtValidation.RemoteJwks)

Fetches the JWKS from a remote location.
localJwks (JwtValidation.LocalJwks)

Loads the JWKS from a local data source.
issuer (string)

Allow only tokens that have been issued by this principal (i.e. whose “iss” claim matches this value). If empty, issuer validation will be skipped.

JwtValidation.LocalJwks

Represents a locally available JWKS.

Field Description
inlineString (string)

JWKS is embedded as a string.

JwtValidation.RemoteJwks

Specifies how to fetch JWKS from remote and how to cache it.

Field Description
url (string)

The HTTP URI to fetch the JWKS.
refreshInterval (google.protobuf.Duration)

The frequency at which the JWKS should be refreshed. If not specified, the default value is 5 minutes.

K8sSecretApiKeyStorage

Field Description
labelSelector (repeated K8sSecretApiKeyStorage.LabelSelectorEntry)

Identify all valid API key secrets that match the provided label selector.
API key secrets must be in one of the watch namespaces for gloo to locate them.
apiKeySecretRefs (repeated core.solo.io.ResourceRef)

A way to directly reference API key secrets. This configuration can be useful for testing, but in general the more flexible label selector should be preferred.

K8sSecretApiKeyStorage.LabelSelectorEntry

Field Description
key (string)

value (string)

Ldap

Authenticates and authorizes requests by querying an LDAP server. Gloo makes the following assumptions:

Field Description
address (string)

Address of the LDAP server to query. Should be in the form ADDRESS:PORT, e.g. ldap.default.svc.cluster.local:389.
userDnTemplate (string)

Template to build user entry distinguished names (DN). This must contains a single occurrence of the “%s” placeholder. When processing a request, Gloo will substitute the name of the user (extracted from the auth header) for the placeholder and issue a search request with the resulting DN as baseDN (and ‘base’ search scope). E.g. “uid=%s,ou=people,dc=solo,dc=io”
membershipAttributeName (string)

Case-insensitive name of the attribute that contains the names of the groups an entry is member of. Gloo will look for attributes with the given name to determine which groups the user entry belongs to. Defaults to ‘memberOf’ if not provided.
allowedGroups (repeated string)

In order for the request to be authenticated, the membership attribute (e.g. memberOf) on the user entry must contain at least of one of the group DNs specified via this option. E.g. []string{ “cn=managers,ou=groups,dc=solo,dc=io”, “cn=developers,ou=groups,dc=solo,dc=io” }
pool (Ldap.ConnectionPool)

Use this property to tune the pool of connections to the LDAP server that Gloo maintains.
searchFilter (string)

Use to set a custom filter when searching a member. Defaults to “(uid=*)".
disableGroupChecking (bool)

Disables group checking, regardless of the value for allowedGroups, and disables validation for the membership attribute of the user entry. Group checking is enabled by default.
groupLookupSettings (LdapServiceAccount)

Settings for using a separate service account for looking up group membership To use this, you also need to configure credentials in a secret

Ldap.ConnectionPool

Configuration properties for pooling connections to the LDAP server. If the pool is exhausted when a connection is requested (meaning that all the pooled connections are in use), the connection will be created on the fly.

Field Description
maxSize (google.protobuf.UInt32Value)

Maximum number connections that are pooled at any give time. The default value is 5.
initialSize (google.protobuf.UInt32Value)

Number of connections that the pool will be pre-populated with upon initialization. The default value is 2.

LdapServiceAccount

Field Description
credentialsSecretRef (core.solo.io.ResourceRef)

Reference to an AccountCredentialsSecret to use to authenticate as the service account
checkGroupsWithServiceAccount (bool)

If true, Gloo will use the service account to check group membership

OAuth

Deprecated: Prefer OAuth2

Field Description
clientId (string)

your client id as registered with the issuer
clientSecretRef (core.solo.io.ResourceRef)

your client secret as registered with the issuer
issuerUrl (string)

The url of the issuer. We will look for OIDC information in issuerUrl+ “.well-known/openid-configuration”
authEndpointQueryParams (repeated OAuth.AuthEndpointQueryParamsEntry)

extra query parameters to apply to the Ext-Auth service's authorization request to the identity provider.
appUrl (string)

we to redirect after successful auth, if we can't determine the original url this should be your publicly available app url.
callbackPath (string)

a callback path relative to app url that will be used for OIDC callbacks. needs to not be used by the application
scopes (repeated string)

Scopes to request in addition to openid scope.

OAuth.AuthEndpointQueryParamsEntry

Field Description
key (string)

value (string)

OAuth2

Field Description
oidcAuthorizationCode (OidcAuthorizationCode)

provide issuer location and let gloo handle OIDC flow for you. requests authorized by validating the contents of ID token. can also authorize the access token if configured.
accessTokenValidation (AccessTokenValidation)

provide the access token on the request and let gloo handle authorization.
according to https://tools.ietf.org/html/rfc6750 you can pass tokens through: - form-encoded body parameter. recommended, more likely to appear. e.g.: Authorization: Bearer mytoken123 - URI query parameter e.g. access_token=mytoken123 - and (preferably) secure cookies
oauth2 (PlainOAuth2)

Enterprise-Only: THIS FEATURE IS IN TECH PREVIEW. APIs are versioned as alpha and subject to change. provide issuer location and let Gloo handle Oauth2 flow for you. requests authorized by validating the contents of access token. Prefer to use OIDC for better security.

OauthSecret

Field Description
clientSecret (string)

OidcAuthorizationCode

Field Description
clientId (string)

your client id as registered with the issuer
clientSecretRef (core.solo.io.ResourceRef)

your client secret as registered with the issuer
issuerUrl (string)

The url of the issuer. We will look for OIDC information in issuerUrl+ “.well-known/openid-configuration”
authEndpointQueryParams (repeated OidcAuthorizationCode.AuthEndpointQueryParamsEntry)

extra query parameters to apply to the Ext-Auth service's authorization request to the identity provider. this can be useful for flows such as PKCE (https://www.oauth.com/oauth2-servers/pkce/authorization-request/) to set the code_challenge and code_challenge_method.
tokenEndpointQueryParams (repeated OidcAuthorizationCode.TokenEndpointQueryParamsEntry)

extra query parameters to apply to the Ext-Auth service's token request to the identity provider. this can be useful for flows such as PKCE (https://www.oauth.com/oauth2-servers/pkce/authorization-request/) to set the code_verifier.
appUrl (string)

where to redirect after successful auth, if we can't determine the original url. this should be your publicly available app url.
callbackPath (string)

a callback path relative to app url that will be used for OIDC callbacks. should not be used by the application.
logoutPath (string)

a path relative to app url that will be used for logging out from an OIDC session. should not be used by the application. If not provided, logout functionality will be disabled.
afterLogoutUrl (string)

url to redirect to after logout. This should be a publicly available URL. If not provided, will default to the app_url.
scopes (repeated string)

Scopes to request in addition to openid scope.
session (UserSession)

Configuration related to the user session.
headers (HeaderConfiguration)

Configures headers added to requests.
discoveryOverride (DiscoveryOverride)

OIDC configuration is discovered at /.well-known/openid-configuration The discovery override defines any properties that should override this discovery configuration For example, the following AuthConfig CRD could be defined as: yaml apiVersion: enterprise.gloo.solo.io/v1 kind: AuthConfig metadata: name: google-oidc namespace: gloo-system spec: configs: - oauth: app_url: http://localhost:8080 callback_path: /callback client_id: $CLIENT_ID client_secret_ref: name: google namespace: gloo-system issuer_url: https://accounts.google.com discovery_override: token_endpoint: "https://token.url/gettoken"
And this will ensure that regardless of what value is discovered at /.well-known/openid-configuration, “https://token.url/gettoken" will be used as the token endpoint
discoveryPollInterval (google.protobuf.Duration)

The interval at which OIDC configuration is discovered at /.well-known/openid-configuration If not specified, the default value is 30 minutes.
jwksCacheRefreshPolicy (JwksOnDemandCacheRefreshPolicy)

If a user executes a request with a key that is not found in the JWKS, it could be that the keys have rotated on the remote source, and not yet in the local cache. This policy lets you define the behavior for how to refresh the local cache during a request where an invalid key is provided
sessionIdHeaderName (string)

DEPRECATED: Prefer the RedisSession.HeaderName field If set, the randomly generated session id will be sent to the token endpoint as part of the code exchange The session id is used as the key for sessions in Redis
parseCallbackPathAsRegex (bool)

If set, CallbackPath will be evaluated as a regular expression
autoMapFromMetadata (AutoMapFromMetadata)

If specified, authEndpointQueryParams and tokenEndpointQueryParams will be populated using dynamic metadata values. By default parameters will be extracted from the solo_authconfig_oidc namespace this behavior can be overridden by explicitly specifying a namespace
endSessionProperties (EndSessionProperties)

If specified, these are properties defined for the end session endpoint specifications. Noted here in the OIDC documentation.

OidcAuthorizationCode.AuthEndpointQueryParamsEntry

Field Description
key (string)

value (string)

OidcAuthorizationCode.TokenEndpointQueryParamsEntry

Field Description
key (string)

value (string)

OpaAuth

Field Description
modules (repeated core.solo.io.ResourceRef)

An optional resource reference to config maps containing modules to assist in the resolution of query.
query (string)

The query that determines the auth decision. The result of this query must be either a boolean or an array with boolean as the first element. A boolean true value means that the request will be authorized. Any other value, or error, means that the request will be denied.
options (OpaAuthOptions)

Additional Options for Opa Auth configuration.

OpaAuthOptions

Field Description
fastInputConversion (bool)

Decreases OPA latency by speeding up conversion of input to the OPA engine. If this is set to true, only http_request and state fields which are a scalar, map, or string array are included in the request input. All other fields are dropped. Dropped fields will not be evaluated by the OPA engine. By default, this is set to false and all fields are evaluated by OPA.

PassThroughAuth

Authorizes requests by querying a custom extauth server.

Field Description
grpc (PassThroughGrpc)

http (PassThroughHttp)

config (google.protobuf.Struct)

Custom config to be passed per request to the passthrough auth service.
failureModeAllow (bool)

If set to true, the service will accept client request even if the communication with the authorization service has failed, or if the authorization service has returned a server error. Defaults to false.

PassThroughGrpc

Authorizes requests by querying a custom extauth grpc server Assumes that the server implements the envoy external authorization spec: https://github.com/envoyproxy/envoy/blob/ae1ed1fa74f096dabe8dd5b19fc70333621b0309/api/envoy/service/auth/v3/external_auth.proto#L29

Field Description
address (string)

Address of the auth server to query. Should be in the form ADDRESS:PORT, e.g. default.svc.cluster.local:389.
connectionTimeout (google.protobuf.Duration)

Timeout for the auth server to respond. Defaults to 5s

PassThroughHttp

Authorizes requests by making a POST HTTP/1 request to a custom HTTP auth server Assumes the request is authorized if the server returns a OK (200) status code, else the request is unauthorized.

Field Description
url (string)

Required: URL of the passthrough http service, is a fully qualified domain name. Example: http://ext-auth-service.svc.local:9001. Path provided in the URL will be respected. To use https, provide the cert in the HTTPS_PASSTHROUGH_CA_CERT environment variable to the ext-auth-service pod as a base64-encoded string
request (PassThroughHttp.Request)

response (PassThroughHttp.Response)

connectionTimeout (google.protobuf.Duration)

Timeout for the auth server to respond. Defaults to 5s

PassThroughHttp.Request

The passthrough http request can be configured to pass through the incoming request body, the ext-auth state (which is shared between different auth methods within one ext-auth instance), and the filterMetadata The body of the passthrough auth request will be a JSON as follows: { “body” : string, “state”: object (map[string]interface{}), “filterMetadata”: object (map[string]protobuf.Struct), “config”: object (protobuf.Struct), } config is the struct block specified under the passthrough auth configuration. If passthrough_body, passthrough_state, passthrough_filter_metadata, and config are all false/nil, the body of the auth request will remain empty. Setting any of these will increase latency slightly due to JSON marshalling.

Field Description
allowedHeaders (repeated string)

These headers will be copied from the incoming request to the request going to the auth server. By default, no headers are copied from the incoming request. Pseudo-headers such as :Path, and :Method can not be specified here.
headersToAdd (repeated PassThroughHttp.Request.HeadersToAddEntry)

These headers that will be included to the request to authorization service. Note that client request of the same key will be overridden. Pseudo-headers such as :Path, and :Method can not be specified here.
passThroughState (bool)

Whether or not to include the ext-auth state object in the passthrough request body. If this is set to true, it is expected that the state is returned in the HTTP response from the passthrough service. The state received from the response will be the state that is shared with other ext-auth service methods. If pass_through_body, pass_through_filter_metadata and pass_through_state are false, the authorization request body will be empty. A non-empty body will increase latency times slightly, so this is set to false by default, and should only be set to to true if the extauth state is needed in the auth request.
passThroughFilterMetadata (bool)

Whether or not to include the filter metadata in the passthrough request body. If pass_through_body, pass_through_filter_metadata and pass_through_state are false, the authorization request body will be empty. A non-empty body will increase latency times slightly, so this is set to false by default, and should only be set to to true if the filter metadata is needed in the auth request.
passThroughBody (bool)

Whether or not to include the body in the passthrough request body. In order for this to work, the settings.extauth.requestBody must be set in the Gloo Edge Settings CRD so that the request body is buffered and sent to the ext-auth service. If pass_through_body, pass_through_filter_metadata and pass_through_state are false, the authorization request body will be empty. A non-empty body will increase latency times slightly, so this is set to false by default, and should only be set to to true if the request body is needed in the auth request.

PassThroughHttp.Request.HeadersToAddEntry

Field Description
key (string)

value (string)

PassThroughHttp.Response

Field Description
allowedUpstreamHeaders (repeated string)

When this is set, authorization response headers that have a header in this list will be added to the original client request and sent to the upstream when the auth request is successful. These will be appended to any request headers that already exist. If this is empty, by default, no authorization response headers will be added to the upstream request.
allowedClientHeadersOnDenied (repeated string)

When this is set, authorization response headers in this list will be added to the client's response when the auth request is denied. If the response header already exists, it will replace the response header. If this is empty, by default, no authorization response headers will be added to the client response.
readStateFromResponse (bool)

If this is set to true, the body of the response from the http passthrough auth server is expected to have shape { “state”: object (map[string]interface{}) } The state will be marshalled from the response body and this is the state that will be passed on to other auth configs. Because of the marshalling from JSON to Go map, this will add some latency to the request. If the marshalling fails, the authorization check will fail and the request will be unauthorized after the ext-auth-service pod logs the marshal error.

PlainOAuth2

Field Description
clientId (string)

Your client ID as registered with the issuer
clientSecretRef (core.solo.io.ResourceRef)

Your client secret as registered with the issuer
authEndpointQueryParams (repeated PlainOAuth2.AuthEndpointQueryParamsEntry)

Extra query parameters to apply to the Ext-Auth service's authorization request to the identity provider. These parameters can be useful for flows such as PKCE to set the code_challenge and code_challenge_method.
appUrl (string)

Where to redirect after successful auth, if Gloo can't determine the original URL. Set this field to your publicly available app URL.
callbackPath (string)

A callback path relative to the app URL to be used for OAuth2 callbacks. Do not use this path in the application itself.
scopes (repeated string)

Scopes to request for.
session (UserSession)

Configuration related to the user session.
logoutPath (string)

A path relative to the app URL to use for logging out from an OAuth2 session. Do not use this path in the application itself. If not provided, logout functionality is disabled.
tokenEndpointQueryParams (repeated PlainOAuth2.TokenEndpointQueryParamsEntry)

Extra query parameters to apply to the Ext-Auth service's token request to the identity provider. These parameters can be useful for flows such as PKCE to set the code_verifier.
afterLogoutUrl (string)

URL to redirect to after logout. Set this field to a publicly available URL. If not provided, this value defaults to the app_url value.
authEndpoint (string)

The URL of the provider authorization endpoint.
tokenEndpoint (string)

The URL of the provider token endpoint.
revocationEndpoint (string)

The URL of the provider token revocation endpoint. For more information, refer to https://www.rfc-editor.org/rfc/rfc7009.

PlainOAuth2.AuthEndpointQueryParamsEntry

Field Description
key (string)

value (string)

PlainOAuth2.TokenEndpointQueryParamsEntry

Field Description
key (string)

value (string)

RedisOptions

Field Description
host (string)

address of the redis. can be address:port or unix://path/to/unix.sock
db (int32)

db to use. can leave unset for db 0.
poolSize (int32)

size of the connection pool. can leave unset for default. defaults to 10 connections per every CPU
tlsCertMountPath (string)

enabled with a socket type of TLS. this is the tls cert mount path for this particular host. the generic secret can include the keys ‘ca.crt’, ‘tls.crt’, and ‘tls.key’. the secret can contain the root-ca ,‘ca.crt’, at minimum. If a certificate is needed, both the ‘tls.crt’ and ‘tls.key’ need to be included. reference this to equal the ‘mountPath’ on the ‘redis.certs[x].mountPath’ in the helm chart values. an example of a mount path is ‘/certs’.
socketType (RedisOptions.SocketType)

the socket type, default is TCP.

Settings

Global external auth settings

Field Description
extauthzServerRef (core.solo.io.ResourceRef)

The upstream to ask about auth decisions
httpService (HttpService)

If this is set, communication to the upstream will be via HTTP and not GRPC (default).
grpcService (GrpcService)

Optional, if set the communication to the upstream will be via GRPC.
userIdHeader (string)

If the auth server trusted id of the user, it will be set in this header. Specifically this means that this header will be sanitized form the incoming request.
requestTimeout (google.protobuf.Duration)

Timeout for the ext auth service to respond. Defaults to 200ms
failureModeAllow (bool)

In case of a failure or timeout querying the auth server, normally a request is denied. if this is set to true, the request will be allowed.
requestBody (BufferSettings)

Set this if you also want to send the body of the request, and not just the headers.
clearRouteCache (bool)

Clears route cache in order to allow the external authorization service to correctly affect routing decisions. Filter clears all cached routes when:
1. The field is set to true.
2. The status returned from the authorization service is a HTTP 200 or gRPC 0.
3. At least one authorization response header is added to the client request, or is used for altering another client request header.
statusOnError (uint32)

Sets the HTTP status that is returned to the client when there is a network error between the filter and the authorization server. The default status is HTTP 403 Forbidden. If set, this must be one of the following: - 100 - 200 201 202 203 204 205 206 207 208 226 - 300 301 302 303 304 305 307 308 - 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 421 422 423 424 426 428 429 431 - 500 501 502 503 504 505 506 507 508 510 511
transportApiVersion (Settings.ApiVersion)

Determines the API version for the ext_authz transport protocol that will be used by Envoy to communicate with the auth server. Defaults to V2. For more info, see the transport_api_version field here.
statPrefix (string)

Optional additional prefix to use when emitting statistics. This allows to distinguish emitted statistics between configured ext_authz filters in an HTTP filter chain.

UserSession

Field Description
failOnFetchFailure (bool)

should we fail auth flow when failing to get a session from redis, or allow it to continue, potentially starting a new auth flow and setting a new session.
cookieOptions (UserSession.CookieOptions)

Set-Cookie options
cookie (UserSession.InternalSession)

Set the tokens in the cookie itself. No need for server side state.
redis (UserSession.RedisSession)

Use redis to store the tokens and just store a random id in the cookie.

UserSession.CookieOptions

Field Description
maxAge (google.protobuf.UInt32Value)

Max age for the cookie. Leave unset for a default of 30 days (2592000 seconds). To disable cookie expiry, set explicitly to 0.
notSecure (bool)

Use a non-secure cookie. Note - this should only be used for testing and in trusted environments.
httpOnly (google.protobuf.BoolValue)

Set the cookie to be HttpOnly. defaults to true. Set explicity to false to disable.
path (google.protobuf.StringValue)

Path of the cookie. If unset, defaults to “/". Set it explicitly to "” to avoid setting a path.
sameSite (UserSession.CookieOptions.SameSite)

Whether the cookie should be restricted to a first-party or same-site context. The default mode is LaxMode.
domain (string)

Cookie domain

UserSession.InternalSession

Field Description
allowRefreshing (google.protobuf.BoolValue)

When set, refresh expired id-tokens using the refresh-token. Defaults to false. Explicitly set to true to enable refreshing.
keyPrefix (string)

Prefix to append to cookie keys, such as for separate domain and subdomain prefixes. Cookie keys are stored in the form <key_prefix>_<cookie_name>. For more information, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#attributes
targetDomain (string)

Domain used to validate against requests in order to ensure that request host name matches target domain. If the target domain is provided will prevent requests that do not match the target domain according to the domain matching specifications in RFC 6265. For more information, see https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3

UserSession.RedisSession

Field Description
options (RedisOptions)

Options to connect to redis
keyPrefix (string)

Key prefix inside redis
cookieName (string)

Cookie name to set and store the session id. If empty the default “__session” is used.
allowRefreshing (google.protobuf.BoolValue)

When set, refresh expired id-tokens using the refresh-token. Defaults to true. Explicitly set to false to disable refreshing.
preExpiryBuffer (google.protobuf.Duration)

Specifies a time buffer in which an id-token will be refreshed prior to its actual expiration. Defaults to 2 seconds. A duration of 0 will only refresh tokens after they have already expired. To refresh tokens, you must also set ‘allowRefreshing’ to ‘true’; otherwise, this field is ignored.
targetDomain (string)

Domain used to validate against requests in order to ensure that request host name matches target domain. If the target domain is provided will prevent requests that do not match the target domain according to the domain matching specifications in RFC 6265. For more information, see https://datatracker.ietf.org/doc/html/rfc6265#section-5.1.3
headerName (string)

If set, the name of the header that will include the randomly generated session id This would be used as part of the code exchange with the Oauth2 token endpoint

AuthConfigStatus.State

Name Number Description
Pending 0 Pending status indicates the resource has not yet been validated
Accepted 1 Accepted indicates the resource has been validated
Rejected 2 Rejected indicates an invalid configuration by the user Rejected resources may be propagated to the xDS server depending on their severity
Warning 3 Warning indicates a partially invalid configuration by the user Resources with Warnings may be partially accepted by a controller, depending on the implementation

EndSessionProperties.MethodType

The Method used to make the request.

Name Number Description
GetMethod 0 Uses GET method when making the request
PostMethod 1 Uses POST method when making the request

RedisOptions.SocketType

redis socket types

Name Number Description
TCP 0 TCP connection socket, this is the default.
TLS 1 TLS connection socket.

Settings.ApiVersion

Describes the transport protocol version to use when connecting to the ext auth server.

Name Number Description
V3 0 Use v3 API.

UserSession.CookieOptions.SameSite

The SameSite options. The default value is LaxMode.

Name Number Description
DefaultMode 0 Default Mode is the same as LaxMode but will not show up in the Cookie Header. This value is ignored.
LaxMode 1 Cookies are not sent on normal cross-site subrequests, but are sent when navigating to the origin site.
StrictMode 2 Only be sent in a first-party context and not be sent along with requests initiated by third party websites.
NoneMode 3 Cookies are sent in all contexts. Cookie NotSecure must be unset.

ApiKeyService

Method Name Request Type Response Type Description
Create ApiKeyCreateRequest ApiKeyCreateResponse
Read ApiKeyReadRequest ApiKeyReadResponse
Update ApiKeyUpdateRequest ApiKeyUpdateResponse
Delete ApiKeyDeleteRequest ApiKeyDeleteResponse

ExtAuthDiscoveryService

@solo-kit:resource.xds-enabled

Method Name Request Type Response Type Description
StreamExtAuthConfig .envoy.api.v2.DiscoveryRequest stream .envoy.api.v2.DiscoveryResponse stream
DeltaExtAuthConfig .envoy.api.v2.DeltaDiscoveryRequest stream .envoy.api.v2.DeltaDiscoveryResponse stream
FetchExtAuthConfig .envoy.api.v2.DiscoveryRequest .envoy.api.v2.DiscoveryResponse