Light Dark Auto

OIDC Authentication

The OIDC Authentication filter has all the information needed to initiate an authentication handshake with an OpenID Connect provider. It begins by checking whether a request contains an access token in a specified location (header, query string, or cookie). If it exists, it assumes that the token was verified at least once by previous filters in the chain and passes the request onto the next filter. If an access token was not found, it will check for the query token to see if there is an access code. This happens when a request is coming back from the identity provider (specified by callback URL). If the code is found, it will exchange it for a bearer token and an id token - both of them will then be stored in specified locations. If no access code was found, the authentication process gets kicked off by forwarding the user to the identity provider.

Filter Configuration Options

  • accessToken.metadataFilter(String, default: "") - The name of the filter to read dynamic metadata from. Required if accessToken.location=met.
  • accessToken.cookieOptions.httpOnly(Boolean, default: false) - Whether the cookie being created should be httpOnly.
  • accessToken.cookieOptions.secure(Boolean, default: false) - Whether the cookie being created should only be sent to the server over HTTPS..
  • accessToken.cookieOptions.maxAge(String, default: "") - The Max-Age of the new cookie. The value is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "s", "m", "h" ("ns", "us"/"µs", and "ms" are also valid but the value gets rounded to the nearest second as Max-Age is defined as "number of seconds until the cookie expires"). If maxAge is not set, the cookie will have Expires/Max-Age of Session.true. If the access token expires before the specified max age, the actual token expiration is used instead.
  • accessToken.cookieOptions.path(String, default: "") - Path indicates a URL path that must exist in the requested URL in order to send the Cookie header.
  • accessToken.cookieOptions.domain(String, default: "") - Domain specifies allowed hosts to receive the cookie. If unspecified, it defaults to the host of the current document location, excluding subdomains. If Domain is specified, then subdomains are always included.
  • idToken - idToken block is optional. If there is no need to keep idToken, remove this block entirely.
  • idToken.location(enum[header, cookie, queryString, metadata], default: header) - The location where the filter expects an ID token to be.
  • idToken.key(String, default: "") - The key of the ID token in the above location.
  • idToken.cookieOptions.httpOnly(Boolean, default: false) - Whether the cookie being created should be httpOnly.
  • idToken.cookieOptions.secure(Boolean, default: false) - Whether the cookie being created should only be sent to the server over HTTPS.
  • idToken.cookieOptions.maxAge(String, default: "") - The Max-Age of the new cookie. The value is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "s", "m", "h" ("ns", "us"/"µs", and "ms" are also valid but the value gets rounded to the nearest second as Max-Age is defined as "number of seconds until the cookie expires"). If maxAge is not set, the cookie will have Expires/Max-Age of Session. If the ID token expires before the specified max age, the actual token expiration is used instead.
  • idToken.cookieOptions.path(String, default: "") - Path indicates a URL path that must exist in the requested URL in order to send the Cookie header.
  • idToken.cookieOptions.domain(String, default: "") - Domain specifies allowed hosts to receive the cookie. If unspecified, it defaults to the host of the current document location, excluding subdomains. If Domain is specified, then subdomains are always included.
  • serviceUrl(String, default: "") - The host name of the application. When a user signs in through the OAuth provider, they will need to be redirected back to your application; this host name will be used during the redirect.
  • callbackPath(String, default: "") - The path of the callback API. The callback URL gets constructed with the combination of serviceUrl and callbackPath.
  • provider(String, default: "") - The url for the OpenID connect provider to use. This is used to determine the particular OAuth endpoints.
  • clientId(String, default: "") - The public identifier registered with the OAuth authorization server.
  • clientSecret(String, default: "") - The secret known only to the application and the authorization server.
  • additionalScopes([]String, default: []) - Any additional scopes to openid.
  • tokenRefresh(default: {}) - An optional block specifying configuration for resetting token with Keycloak.
  • tokenRefresh.enabled(Boolean, default: false) - Toggles refresh token feature.
  • tokenRefresh.endpoint(String, default: "") - Keycloak endpoint.
  • tokenRefresh.realm(String, default: "") - Realm to refresh tokens in.
  • tokenRefresh.useTLS(Boolean, default: false) - Toggles whether or not to use TLS in connection to Keycloak for token refresh.
  • tokenRefresh.certPath(String, default: "") - Local path to cert for TLS connection to Keycloak.
  • tokenRefresh.keyPath(String, default: "") - Local path for key for TLS connection to Keycloak..
  • tokenRefresh.caPath(String, default: "") - Local path to CA cert for TLS connection to Keycloak.
  • tokenRefresh.insecureSkipVerify(Boolean, default: false) - Toggles whether calls to keycloak require hostname verification in certs.
  • tokenRefresh.timeoutMs(Integer, default: 0) - Millisecond timeout in for calls to keycloak. Note: this must be set or all calls will timeout after 0ms.

Design Decisions

Access token and ID token locations

All three location types work just as well for the filter to read from. For storing the newly acquired bearer token and ID token, however, it is important to keep in mind there will be redirects involved in the equation.

If you choose header for storing an access token, the service that sits behind this proxy may or may not see this header. Let's break this down to two scenarios:

  • If a user is already authenticated and have an access code in the request header, the service will see this token because this filter will just let the request pass through.
  • If a user is in the middle of authentication process and the filter just exchanged an access code with a bearer token, the filter will attach the newly acquired token to the response header and send back a 302 Found response to the user. The user's browser will then see that this response has Location header set, and make a new request to the location specified. So the only audience of the token headers (if you so choose) is the user while the service behind this proxy will not see the token. In most cases, this is not what you want to configure to.

If you choose queryString, the filter will append the token(s) to the URL that the user was originally trying to get to (before being redirected to authenticate). So the service behind this proxy will be able to read them.

cookie is the most straight forward of the three. When the 302 response goes back to the user, it will set the cookie on their browser (which will be visible from the service when a new request gets created).

State Parameter

Although the main purpose of using the state parameter is to mitigate CSRF attacks, we are currently using this parameter to store the original URL that a user was trying reach before he/she was redirected to Identity Provider for authentication. This was taken from the existing implementation of the OpenID Connect authentication filter (gm.oauth), and something to be aware of moving forward.

Refresh Tokens

The gm-oidc-authentication filter has the ability to refresh incoming tokens if they are expired. At this writing, only Keycloak is supported for token refresh.