Skip to content

OAuth 2.0 Resource Server

Jump to bottom Edit New page
Hans Zandbelt edited this page Apr 14, 2015 · 26 revisions

In addition to its OpenID Connect RP capabilities, mod_auth_openidc can also function as an OAuth 2.0 Resource Server, validating bearer access tokens sent by OAuth 2.0 clients. This can be used to protect static content, hosted APIs or applications or protected content running behind the Apache server when Apache operates as a reverse proxy in front of origin servers, APIs or applications.

There are two modes for validation of access tokens, remote and local.

Remote Validation

Remote validation consists of calling out to an OAuth 2.0 Authorization Server in a so-called "introspection" or "validation" call. This works with arbitrary token types since the token is opaque to the Resource Server. The API between Resource Server and Authorization Server is not (yet) standardized, but mod_auth_openidc supports a number of implementations:

The validation call settings are flexible enough to cater for even different implementations as long as it conforms to the following template:

  • use HTTP POST with form-encoded parameters to the URL specified in OIDCOAuthIntrospectionEndpoint, or use HTTP GET with query parameters when OIDCOAuthIntrospectionEndpointMethod GET is defined
  • use HTTP Basic Authentication against the introspection endpoint with OIDCOAuthClientID and OIDCOAuthClientSecret, or pass those credentials in as POST (or GET) parameters client_id and client_secret respectively (or don't use client authentication)
  • configure the parameter name in which the token is passed with OIDCOAuthIntrospectionTokenParamName (default is token)
  • configure additional parameters sent in as part of the HTTP POST (or GET) to the introspection endpoint in OIDCOAuthIntrospectionEndpointParams
  • the response is a JSON object that contains an "token expiry" claim whose interpretation can be configured using the OIDCOAuthTokenExpiryClaim configuration setting wrt. claim name, timestamp semantics (absolute or relative) and whether the claim is optional or mandatory (the default is to expect a mandatoryexpires_in claim with a relative value as PingFederate's and Google's Authorization Servers provide)

Local Validation

(available since version 1.8.0rc0)
Local validation can be used with bearer access tokens that are JSON Web Tokens. It consists of validating the JWT token against a configured set of symmetric or public keys. Settings used in that case are:

# The symmetric shared key(s) that can be used for local JWT access token validation.
# NB: this is one or more plain secret(s), so NOT hex or base64 encoded.
# When not defined, no access token validation with shared keys will be performed.
OIDCOAuthVerifySharedKeys [<secret>+]

# The fully qualified names of the files that contain the X.509 certificates with the RSA public
# keys that can be used for local JWT access token verification.
# When not defined, no access token validation with statically configured certificates will be performed.
OIDCOAuthVerifyCertFiles [<filename>+]

Alternatively, if your Authorization Server supports the OpenID Connect style of publishing key material on a JWKs URL you can use a more dynamic way of obtaining the verification keys:

# The JWKs URL on which the Authorization publishes the keys used to sign its JWT access tokens.
# When not defined local validation of JWTs can still be done using statically configured keys,
# by setting OIDCOAuthVerifyCertFiles and/or OIDCOAuthVerifySharedKeys.
OIDCOAuthVerifyJwksUri <jwks_url>
Add a custom footer
Add a custom sidebar
Clone this wiki locally