auth_config.proto

Package : enterprise.gloo.solo.io

Top

auth_config.proto

Table of Contents

AccessTokenValidation

Field Type Label 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 enterprise.gloo.solo.io.AccessTokenValidation.JwtValidation Validate access tokens that conform to the JSON Web Token (JWT) specification.
introspection enterprise.gloo.solo.io.AccessTokenValidation.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 enterprise.gloo.solo.io.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.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 Type Label 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.

AccessTokenValidation.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 Type Label Description
remoteJwks enterprise.gloo.solo.io.AccessTokenValidation.JwtValidation.RemoteJwks Fetches the JWKS from a remote location.
localJwks enterprise.gloo.solo.io.AccessTokenValidation.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.

AccessTokenValidation.JwtValidation.LocalJwks

Represents a locally available JWKS.

Field Type Label Description
inlineString string JWKS is embedded as a string.

AccessTokenValidation.JwtValidation.RemoteJwks

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

Field Type Label 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.

AccessTokenValidation.ScopeList

Field Type Label Description
scope []string repeated

ApiKeyAuth

Field Type Label Description
labelSelector []enterprise.gloo.solo.io.ApiKeyAuth.LabelSelectorEntry repeated 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 []core.solo.io.ResourceRef repeated 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 []enterprise.gloo.solo.io.ApiKeyAuth.HeadersFromMetadataEntry repeated API key secrets might contain additional data (e.g. the ID of the user that the API key belongs to) in the form of extra keys included in the secret's data field. 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 secret data that will be inspected to determine the value for the header.

ApiKeyAuth.HeadersFromMetadataEntry

Field Type Label Description
key string
value enterprise.gloo.solo.io.ApiKeyAuth.SecretKey

ApiKeyAuth.LabelSelectorEntry

Field Type Label Description
key string
value string

ApiKeyAuth.SecretKey

Field Type Label Description
name string (Required) The key of the secret data entry to inspect.
required bool If this field is set to true, Gloo will reject an API key secret that does not contain the given key. Defaults to false. In this case, if a secret does not contain the requested data, no header will be added to the request.

ApiKeySecret

Field Type Label Description
generateApiKey bool If true, generate an API key. This field is deprecated as it was used only internally by glooctl and is not actually part of the secret API.
apiKey string The value of the API key.
labels []string repeated A list of labels (key=value) for the apikey secret.
These labels are used when creating an ApiKeySecret via glooctl and then are copied to the metadata of the created secret. This field is deprecated as it was used only internally by glooctl and is not actually part of the secret API.
metadata []enterprise.gloo.solo.io.ApiKeySecret.MetadataEntry repeated If the secret data contains entries in addition to the API key one, they will be copied to this field.

ApiKeySecret.MetadataEntry

Field Type Label Description
key string
value string

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 Type Label Description
configs []enterprise.gloo.solo.io.AuthConfigSpec.Config repeated 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.

AuthConfigSpec.Config

Field Type Label 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 enterprise.gloo.solo.io.BasicAuth
oauth enterprise.gloo.solo.io.OAuth
oauth2 enterprise.gloo.solo.io.OAuth2
apiKeyAuth enterprise.gloo.solo.io.ApiKeyAuth
pluginAuth enterprise.gloo.solo.io.AuthPlugin
opaAuth enterprise.gloo.solo.io.OpaAuth
ldap enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.PassThroughAuth

AuthConfigStatus

Field Type Label Description
state enterprise.gloo.solo.io.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 []enterprise.gloo.solo.io.AuthConfigStatus.SubresourceStatusesEntry repeated 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 Type Label Description
key string
value enterprise.gloo.solo.io.AuthConfigStatus

AuthPlugin

Field Type Label 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

BasicAuth

Field Type Label Description
realm string
apr enterprise.gloo.solo.io.BasicAuth.Apr

BasicAuth.Apr

Field Type Label Description
users []enterprise.gloo.solo.io.BasicAuth.Apr.UsersEntry repeated

BasicAuth.Apr.SaltedHashedPassword

Field Type Label Description
salt string
hashedPassword string

BasicAuth.Apr.UsersEntry

Field Type Label Description
key string
value enterprise.gloo.solo.io.BasicAuth.Apr.SaltedHashedPassword

BufferSettings

Configuration for buffering the request data.

Field Type Label 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 Type Label Description
contextExtensions []enterprise.gloo.solo.io.CustomAuth.ContextExtensionsEntry repeated 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 Type Label 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 Type Label 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 []string repeated list of scope values that the provider supports
responseTypes []string repeated list of response types that the provider supports
subjects []string repeated list of subject identifier types that the provider supports
idTokenAlgs []string repeated list of json web signature signing algorithms that the provider supports for encoding claims in a jwt
authMethods []string repeated list of client authentication methods supported by the provider token endpoint
claims []string repeated list of claim types that the provider supports

ExtAuthConfig

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

Field Type Label 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 []enterprise.gloo.solo.io.ExtAuthConfig.Config repeated 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.

ExtAuthConfig.AccessTokenValidationConfig

Field Type Label 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 enterprise.gloo.solo.io.ExtAuthConfig.AccessTokenValidationConfig.JwtValidation Validate access tokens that conform to the JSON Web Token (JWT) specification.
introspection enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.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 Type Label 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 Type Label Description
remoteJwks enterprise.gloo.solo.io.ExtAuthConfig.AccessTokenValidationConfig.JwtValidation.RemoteJwks Fetches the JWKS from a remote location.
localJwks enterprise.gloo.solo.io.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 Type Label 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 Type Label 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 Type Label Description
scope []string repeated

ExtAuthConfig.ApiKeyAuthConfig

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

Field Type Label Description
validApiKeys []enterprise.gloo.solo.io.ExtAuthConfig.ApiKeyAuthConfig.ValidApiKeysEntry repeated A mapping of valid API keys to their associated metadata. This map is automatically populated with the information from the relevant ApiKeySecrets.
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 []enterprise.gloo.solo.io.ExtAuthConfig.ApiKeyAuthConfig.HeadersFromKeyMetadataEntry repeated 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.

ExtAuthConfig.ApiKeyAuthConfig.HeadersFromKeyMetadataEntry

Field Type Label Description
key string
value string

ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata

Field Type Label Description
username string The user is mapped as the name of Secret which contains the ApiKeySecret
metadata []enterprise.gloo.solo.io.ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata.MetadataEntry repeated The metadata present on the ApiKeySecret.

ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata.MetadataEntry

Field Type Label Description
key string
value string

ExtAuthConfig.ApiKeyAuthConfig.ValidApiKeysEntry

Field Type Label Description
key string
value enterprise.gloo.solo.io.ExtAuthConfig.ApiKeyAuthConfig.KeyMetadata

ExtAuthConfig.Config

Field Type Label 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 enterprise.gloo.solo.io.ExtAuthConfig.OAuthConfig
oauth2 enterprise.gloo.solo.io.ExtAuthConfig.OAuth2Config
basicAuth enterprise.gloo.solo.io.BasicAuth
apiKeyAuth enterprise.gloo.solo.io.ExtAuthConfig.ApiKeyAuthConfig
pluginAuth enterprise.gloo.solo.io.AuthPlugin
opaAuth enterprise.gloo.solo.io.ExtAuthConfig.OpaAuthConfig
ldap enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.PassThroughAuth

ExtAuthConfig.OAuth2Config

Field Type Label Description
oidcAuthorizationCode enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.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

ExtAuthConfig.OAuthConfig

Deprecated, prefer OAuth2Config

Field Type Label 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 []enterprise.gloo.solo.io.ExtAuthConfig.OAuthConfig.AuthEndpointQueryParamsEntry repeated 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 []string repeated scopes to request in addition to the openid scope.

ExtAuthConfig.OAuthConfig.AuthEndpointQueryParamsEntry

Field Type Label Description
key string
value string

ExtAuthConfig.OidcAuthorizationCodeConfig

Field Type Label 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 []enterprise.gloo.solo.io.ExtAuthConfig.OidcAuthorizationCodeConfig.AuthEndpointQueryParamsEntry repeated 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 []enterprise.gloo.solo.io.ExtAuthConfig.OidcAuthorizationCodeConfig.TokenEndpointQueryParamsEntry repeated 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 []string repeated scopes to request in addition to the openid scope.
session enterprise.gloo.solo.io.UserSession
headers enterprise.gloo.solo.io.HeaderConfiguration Configures headers added to requests.
discoveryOverride enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.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

ExtAuthConfig.OidcAuthorizationCodeConfig.AuthEndpointQueryParamsEntry

Field Type Label Description
key string
value string

ExtAuthConfig.OidcAuthorizationCodeConfig.TokenEndpointQueryParamsEntry

Field Type Label Description
key string
value string

ExtAuthConfig.OpaAuthConfig

Field Type Label Description
modules []enterprise.gloo.solo.io.ExtAuthConfig.OpaAuthConfig.ModulesEntry repeated 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 enterprise.gloo.solo.io.OpaAuthOptions Additional Options for Opa Auth configuration.

ExtAuthConfig.OpaAuthConfig.ModulesEntry

Field Type Label Description
key string
value string

ExtAuthExtension

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

Field Type Label 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 enterprise.gloo.solo.io.CustomAuth Use this field if you are running your own custom extauth server.

HeaderConfiguration

Field Type Label 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.

HttpService

Field Type Label Description
pathPrefix string Sets a prefix to the value of authorization request header Path.
request enterprise.gloo.solo.io.HttpService.Request
response enterprise.gloo.solo.io.HttpService.Response

HttpService.Request

Field Type Label Description
allowedHeaders []string repeated 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 []enterprise.gloo.solo.io.HttpService.Request.HeadersToAddEntry repeated These headers that will be included to the request to authorization service. Note that client request of the same key will be overridden.

HttpService.Request.HeadersToAddEntry

Field Type Label Description
key string
value string

HttpService.Response

Field Type Label Description
allowedUpstreamHeaders []string repeated When this is set, authorization response headers that have a will be added to the original client request and sent to the upstream. Note that coexistent headers will be overridden.
allowedClientHeaders []string repeated When this. is set, authorization response headers that will be added to the client's response when 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.

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 Type Label 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.

Ldap

Authenticates and authorizes requests by querying an LDAP server. Gloo makes the following assumptions: * Requests provide credentials via the basic HTTP authentication header. Gloo will BIND to the LDAP server using the credentials extracted from the header. * Your LDAP server is configured so that each entry you want to authorize has an attribute that indicates its group memberships. A common way of achieving this is by using the memberof overlay.

Field Type Label 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 []string repeated 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 enterprise.gloo.solo.io.Ldap.ConnectionPool Use this property to tune the pool of connections to the LDAP server that Gloo maintains.

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 polled connections are in use), the connection will be created on the fly.

Field Type Label 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.

OAuth

Deprecated: Prefer OAuth2

Field Type Label 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 []enterprise.gloo.solo.io.OAuth.AuthEndpointQueryParamsEntry repeated 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 []string repeated Scopes to request in addition to openid scope.

OAuth.AuthEndpointQueryParamsEntry

Field Type Label Description
key string
value string

OAuth2

Field Type Label Description
oidcAuthorizationCode enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.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

OauthSecret

Field Type Label Description
clientSecret string

OidcAuthorizationCode

Field Type Label 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 []enterprise.gloo.solo.io.OidcAuthorizationCode.AuthEndpointQueryParamsEntry repeated 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 []enterprise.gloo.solo.io.OidcAuthorizationCode.TokenEndpointQueryParamsEntry repeated 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 []string repeated Scopes to request in addition to openid scope.
session enterprise.gloo.solo.io.UserSession Configuration related to the user session.
headers enterprise.gloo.solo.io.HeaderConfiguration Configures headers added to requests.
discoveryOverride enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.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

OidcAuthorizationCode.AuthEndpointQueryParamsEntry

Field Type Label Description
key string
value string

OidcAuthorizationCode.TokenEndpointQueryParamsEntry

Field Type Label Description
key string
value string

OpaAuth

Field Type Label Description
modules []core.solo.io.ResourceRef repeated 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 enterprise.gloo.solo.io.OpaAuthOptions Additional Options for Opa Auth configuration.

OpaAuthOptions

Field Type Label 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 Type Label Description
grpc enterprise.gloo.solo.io.PassThroughGrpc
config google.protobuf.Struct Custom config to be passed per request to the passthrough auth service.

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 Type Label 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

RedisOptions

Field Type Label 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

Settings

Global external auth settings

Field Type Label Description
extauthzServerRef core.solo.io.ResourceRef The upstream to ask about auth decisions
httpService enterprise.gloo.solo.io.HttpService If this is set, communication to the upstream will be via HTTP and not 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 enterprise.gloo.solo.io.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 enterprise.gloo.solo.io.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 Type Label 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 enterprise.gloo.solo.io.UserSession.CookieOptions Set-Cookie options
cookie enterprise.gloo.solo.io.UserSession.InternalSession Set the tokens in the cookie itself. No need for server side state.
redis enterprise.gloo.solo.io.UserSession.RedisSession Use redis to store the tokens and just store a random id in the cookie.

UserSession.CookieOptions

Field Type Label 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.
path google.protobuf.StringValue Path of the cookie. If unset, defaults to “/". Set it explicitly to "” to avoid setting a path.
domain string Cookie domain

UserSession.InternalSession

UserSession.RedisSession

Field Type Label Description
options enterprise.gloo.solo.io.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.

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

Settings.ApiVersion

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

Name Number Description
V3 0 Use v3 API.

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