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.
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.
How to handle processing of named configs within an auth config chain. An example config might be: `( basic1
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.
Azure
For apps in Microsoft Azure, configure Microsoft Entra ID as the OpenID Connect (OIDC) provider.
This way, you can enable distributed claims and caching for when users are members of more than 200 groups.
The client ID for the ExtAuthService app that is registered in MS Entra, to access the Microsoft Graph API to retrieve distributed claims. This app is NOT the app that you want to configure external auth for.
tenantId
string
The tenant ID represents the MS Entra organization ID where the ExtAuthService app is registered. This tenant ID may or may not be the same as in the top level OidcAuthorizationCodeConfig, depending on how your Azure account is provisioned.
clientSecret
string
The client secret of the ExtAuthService app that is registered with MS Entra to communicate with the MS Graph API.
Redis connection details to cache MS Entera claims. This way, you avoid performance issues of accessing the Microsoft Graph API too many times. Note that this setting does NOT turn on Redis caching for the user session. To turn on Redis user session caching, use the userSessionConfig field.
ClaimToHeader
Map a single claim from an OAuth2 or OIDC token to a header in the request to the upstream destination.
"claim": string"header": string"append": bool
Field
Type
Description
claim
string
The claim name from the token, such as sub.
header
string
The header to copy the claim to, such as x-sub.
append
bool
If the header exists, append the claim value to the header (true), or overwrite any existing value (false). The default behavior is to overwrite any existing value (false).
BasicAuthInternal
Message to store Basic Auth Configuration.
“Internal” refers to this format allowing for selection of the hashing algorithm and user source.
If only the legacy “apr” field is defined, the existing public BasicAuth configuration will continue be used.
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.
the cipher config enables the symmetric key encryption of the cookie values of the user session.
CipherConfig
"key": string
Field
Type
Description
key
string
to enable the cipher encryption, the key has to be present. Note that the key has to be found and 32 bytes in length for the authconfig to not be rejected.
your client secret as registered with the issuer. Only one of client_secret or pk_jwt_client_authentication_config should be set. pk_jwt_client_authentication_config takes precedence.
issuerUrl
string
The url of the issuer. We will look for OIDC information in issuerUrl+ “.well-known/openid-configuration”.
authEndpointQueryParams
map<string, string>
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.
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
scopes to request in addition to the openid scope.
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.
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.
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.
Configuration for private key JWT client authentication. Only one of client_secret or pk_jwt_client_authentication_config should be set. pk_jwt_client_authentication_config takes precedence.
Configuration for front channel logout. This is used to log out the user from multiple apps/clients associated with one OpenId Provider (OP). The path is registered with the OP and is called for each app/client that the user is logged into when the logout endpoint is called.
dynamicMetadataFromClaims
map<string, string>
Map of metadata key to claim. Ie: dynamic_metadata_from_claims: issuer: iss email: email When specified, the matching claims from the ID token will be emitted as dynamic metadata. Note that metadata keys must be unique, and the claim names must be alphanumeric and use - or _ as separators. The metadata will live in a namespace specified by the canonical name of the ext auth filter (in our case envoy.filters.http.ext_authz), and the structure of the claim value will be preserved in the metadata struct.
Amount of time for which the JWT is valid. No maximum is enforced, but different IDPs may impose limits on how far in the future the expiration time is allowed to be. Defaults in 5s in front end, but expected to be set explicitly here.
AccessToken
Optional: Map a single claim from an OAuth2 access token to a header in the request to the upstream destination.
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. Only one of introspectionUrl, jwt, or introspection can be set.
Defines how (opaque) access tokens, received from the oauth authorization endpoint, are validated OAuth2.0 Token Introspection specification. Only one of introspection, introspectionUrl, or jwt can be set.
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.
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.
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.
dynamicMetadataFromClaims
map<string, string>
Map of metadata key to claim. Ie: dynamic_metadata_from_claims: issuer: iss email: email When specified, the matching claims from the access token will be emitted as dynamic metadata. Note that metadata keys must be unique, and the claim names must be alphanumeric and use - or _ as separators. Works when the access token is a JWT or when the access token is opaque, in which case the claims will refer to field in the response from the token introspection endpoint. The metadata will live in a namespace specified by the canonical name of the ext auth filter (in our case envoy.filters.http.ext_authz), and the structure of the claim value will be preserved in the metadata struct.
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.
The frequency at which the JWKS should be refreshed. If not specified, the default value is 5 minutes.
LocalJwks
Represents a locally available JWKS.
"inlineString": string
Field
Type
Description
inlineString
string
JWKS is embedded as a string.
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.
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.
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.
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
map<string, string>
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.
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. Only one of oidcAuthorizationCode, accessTokenValidationConfig, or oauth2Config can be set.
provide the access token on the request and let gloo handle authorization. according to https://datatracker.ietf.org/doc/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. Only one of accessTokenValidationConfig, oidcAuthorizationCode, or oauth2Config can be set.
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. Only one of oauth2Config, oidcAuthorizationCode, or accessTokenValidationConfig can be set.
ApiKeyAuthConfig
NOTE: This configuration is not user-facing and will be auto generated
A mapping of valid API keys to their associated metadata. This map is automatically populated with the information from the relevant ApiKeys. Currently this is only configured when using the k8s Secret storage backend.
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
map<string, string>
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.
Only one of serverDefaultApikeyStorage, k8sSecretApikeyStorage, or aerospikeApikeyStorage can be set.
skipMetadataValidation
bool
API key metadata may contain data is is invalid for a header, such as a newline. By default, this data will be validated in the data plane and mitigated in a way that provides a consistent experience for the user and visibility for the operator. This validation comes with a performance cost, and can be disabled by setting this field to true.
KeyMetadata
"username": string"metadata": map<string, string>
Field
Type
Description
username
string
The user is mapped as the name of Secret which contains the ApiKey.
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.
Configure the Gloo external auth server to use your own Open Policy Agent (OPA) server.
This way, you can use extra capabilities such as bundling or caching.
The package from your Rego policy bundle used to query the OPA data API.
ruleName
string
The rule in your Rego policy bundle used to query the OPA data API. Supports querying subfields with a /. For more information, see the OPA docs for the Data API.
serverAddr
string
The address of the OPA server to query, in the format ADDRESS:PORT. For OPA servers within the cluster, the address is the pod’s service address, such as opa-svc.default.svc.cluster.local:8181. For OPA servers outside the cluster, the server must be accessible to the cluster, such as through an ExternalService. If you do not have your own OPA server instance, omit this field. When the external auth service has the OPA server sidecar enabled, the OPA server sidecar will be used instead, with an address such as http://localhost:8181.
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
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” }.
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.
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.
Only one of oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of oauth2, oauth, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of basicAuth, oauth, oauth2, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of basicAuthInternal, oauth, oauth2, basicAuth, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of apiKeyAuth, oauth, oauth2, basicAuth, basicAuthInternal, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of pluginAuth, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of opaAuth, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of ldap, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldapInternal, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Used for LDAP configurations that need service account credentials saved in a secret. Only one of ldapInternal, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, jwt, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
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. Only one of jwt, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, passThroughAuth, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of passThroughAuth, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, hmacAuth, opaServerAuth, or portalAuth can be set.
Only one of hmacAuth, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, opaServerAuth, or portalAuth can be set.
Only one of opaServerAuth, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, or portalAuth can be set.
Only one of portalAuth, oauth, oauth2, basicAuth, basicAuthInternal, apiKeyAuth, pluginAuth, opaAuth, ldap, ldapInternal, jwt, passThroughAuth, hmacAuth, or opaServerAuth can be set.
