OIDC Authentication

Authenticate with an OpenID Connect provider

GSLHTTPAvailable since: v1

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.

Configuration

The base GSL type is OIDCAuthenticationFilter

tls

struct

Embedded TLS configuration

tls: { useTLS: *true | bool certPath?: string keyPath?: string caPath?: string insecureSkipVerify: *false | bool }

additionalScopes

[...string]

Any additional scopes to request.

clientId

String

The public identifier registered with the OAuth authorization server.

clientSecret

String

The secret known only to the application and the authorization server.

callbackPath

String

The path of the callback API. The callback URL gets constructed with the combination of `serviceUrl` and `callbackPath`.

serviceUrl

String

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.

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.