Skip to content

Observability

Jump to bottom Edit New page
Hans Zandbelt edited this page Dec 17, 2023 · 23 revisions

Since version 2.4.15 mod_auth_openidc allows for collection and retrieval of a number of metrics that are designed to be used in systems monitoring and alerting tools such as Prometheus.

Measurements

The OIDCMetricsData primitive configures the top level classes of metrics that will be collected. Supported metric classes are:

  • authtype
    the authentication handler type split out per AuthType: openid-connect, oauth20 and auth-openidc
  • authn
    authentication request generation and response processing
  • authz
    authorization errors per OIDCUnAuthzAction (per Require statement, not overall)
  • require.claim
    matches/errors count of Require claim directives (per Require statement, not overall)
  • requests
    requests to the provider endpoints (metadata retrieval, token request, refresh requests and userinfo requests)
  • session
    existing session handling
  • cache
    cache read/write/errors
  • redirect_uri
    requests to the Redirect URI
  • content
    requests to the content handler, split out per types of request (info, metrics, jwks, etc.)

Types

Two types of metrics exists, counters, recorded as a simple number and timings, recorded as a histogram.

Metrics

Supported metrics recorded and published per defined VirtualHost:

Timer:    <vhost>.authtype.handler     A histogram of the overall authz+authz processing time.
Timer:    <vhost>.authn.request        A histogram of authentication requests.
Timer:    <vhost>.authn.response       A histogram of authentication responses.
Timer:    <vhost>.session.valid        A histogram of successfully validated existing sessions.
Timer:    <vhost>.requests.metadata    A histogram of provider discovery document requests.
Timer:    <vhost>.requests.token       A histogram of provider token requests.
Timer:    <vhost>.requests.refresh     A histogram of provider refresh token requests.
Timer:    <vhost>.requests.userinfo    A histogram of provider userinfo requests.
Timer:    <vhost>.cache.read           A histogram of cache read requests.
Timer:    <vhost>.cache.write          A histogram of cache write requests.
Counter:    <vhost>.authtype.handler.mod_auth_openidc      The number of requests handled by mod_auth_openidc.
Counter:    <vhost>.authtype.handler.openid-connect        The number of requests protected by AuthType openid-connect.
Counter:    <vhost>.authtype.handler.oauth20               The number of requests protected by AuthType oauth20.
Counter:    <vhost>.authtype.handler.auth-openidc          The number of requests protected by AuthType auth-openidc.
Counter:    <vhost>.authtype.handler.declined              The number of requests protected by handled by mod_auth_openidc.
Counter:    <vhost>.authn.request.error.url                The number of errors matching the incoming request URL against the configuration.
Counter:    <vhost>.authn.response.error.state-mismatch    The number of state mismatch errors in authentication responses.
Counter:    <vhost>.authn.response.error.state-expired     The number of state expired errors in authentication responses.
Counter:    <vhost>.authn.response.error.provider          The number of errors returned by the provider in authentication responses.
Counter:    <vhost>.authn.response.error.protocol          The number of errors handling authentication responses.
Counter:    <vhost>.authn.response.error.remote-user       The number of errors identifying the remote user based on provided claims.
Counter:    <vhost>.authz.action.auth                      The number of step-up authentication requests.
Counter:    <vhost>.authz.action.401                       The number of 401 authorization errors.
Counter:    <vhost>.authz.action.403                       The number of 403 authorization errors.
Counter:    <vhost>.authz.action.302                       The number of 302 authorization errors.
Counter:    <vhost>.authz.error.oauth20                    The number of AuthType oauth20 authorization errors 401.
Counter:    <vhost>.require.claim.match.require.<value>    The number of per-require claim authorization matches.
Counter:    <vhost>.require.claim.error.require.<value>    The number of per-require claim authorization errors.
Counter:    <vhost>.requests.provider.metadata.error       The number of errors retrieving provider discovery document.
Counter:    <vhost>.requests.provider.token.error          The number of errors making a token request to the provider.
Counter:    <vhost>.requests.provider.refresh.error        The number of errors refreshing the access token.
Counter:    <vhost>.requests.provider.userinfo.error       The number of errors calling the provider userinfo endpoint.
Counter:    <vhost>.session.error.cookie-domain            The number of cookie domain validation errors for existing sessions.
Counter:    <vhost>.session.error.expired                  The number of sessions that exceeded the maximum duration.
Counter:    <vhost>.session.error.refresh-access-token     The number of errors refreshing the access token before expiry in existing sessions.
Counter:    <vhost>.session.error.refresh-user-info        The number of errors refreshing claims from the userinfo endpoint in existing sessions.
Counter:    <vhost>.session.error.general                  The number of existing sessions that failed validation.
Counter:    <vhost>.cache.cache.error                      The number of cache read/write errors.
Counter:    <vhost>.redirect_uri.authn.response.redirect   The number of authentication responses received in a redirect.
Counter:    <vhost>.redirect_uri.authn.response.post       The number of authentication responses received in a HTTP POST.
Counter:    <vhost>.redirect_uri.authn.response.implicit   The number of (presumed) implicit authentication responses to the redirect URI.
Counter:    <vhost>.redirect_uri.discovery.response        The number of discovery responses to the redirect URI.
Counter:    <vhost>.redirect_uri.request.logout            The number of logout requests to the redirect URI.
Counter:    <vhost>.redirect_uri.request.jwks              The number of JWKs retrieval requests to the redirect URI.
Counter:    <vhost>.redirect_uri.request.session           The number of session management requests to the redirect URI.
Counter:    <vhost>.redirect_uri.request.refresh           The number of refresh access token requests to the redirect URI.
Counter:    <vhost>.redirect_uri.request.request_uri       The number of Request URI calls to the redirect URI.
Counter:    <vhost>.redirect_uri.request.remove_at_cache   The number of access token cache removal requests to the redirect URI.
Counter:    <vhost>.redirect_uri.request.session           The number of revoke session requests to the redirect URI.
Counter:    <vhost>.redirect_uri.request.info              The number of info hook requests to the redirect URI.
Counter:    <vhost>.redirect_uri.error.provider            The number of provider authentication response errors received at the redirect URI.
Counter:    <vhost>.redirect_uri.error.invalid             The number of invalid requests to the redirect URI.
Counter:    <vhost>.content.request.declined               The number of requests declined by the content handler.
Counter:    <vhost>.content.request.info                   The number of info hook requests to the content handler.
Counter:    <vhost>.content.request.jwks                   The number of JWKs requests to the content handler.
Counter:    <vhost>.content.request.discovery              The number of discovery requests to the content handler.
Counter:    <vhost>.content.request.post-preserve          The number of HTTP POST preservation requests to the content handler.
Counter:    <vhost>.content.request.unknown                The number of unknown requests to the content handler.

Process

The measurements are recorded per virtual host in a local in-memory hash table for performance reasons. The local data is flushed to shared memory in a dedicated thread that runs every 5 seconds per virtual host. Notice that any data consumed on OIDCMetricsPublish is therefore max 5 seconds behind. The shared memory is shared between all of the virtual hosts configured on the same Apache instance. Retrieval of the data on OIDCMetricsPublish returns and resets the counters/timings for all virtual hosts.

Retrieval

The OIDCMetricsPublish primitive configures where the data is published. This URL may contain sensitive data and can be protected by any available Apache mechanism (including e.g. AuthType oauth20). This can be done as part of the virtual host that runs mod_auth_openidc but one may also define a separate virtual host in the same Apache server to publish the data, e.g.:

<VirtualHost _default_:8443>
  SSLEngine on	
  OIDCMetricsPublish  /_mod_auth_openidc/metrics
  Require ip 192.168
</VirtualHost>

Data can be retrieved in a number of formats (see below), using the format query parameter. The format-specific default setting whether or not counters/timings are reset on retrieval can be overruled using the parameter reset with values true|false.

Formats

The URL configured in OIDCMetricsData returns the collected metrics data in a specified format, passed in the format=<value> query parameter. The folowing formats are supported, listed with their reset setting default:

  • format=prometheus&reset=true (default)
    the Prometheus text-based exposition format
  • format=json&reset=true
    JSON a custom extended JSON format with descriptions and labels
  • format=status&reset=false
    Status a short text response containing a single OK line, meant to be using in monitoring/uptime tools such as Nagios, optionally extended to "OK: <value" by retrieving a specific counter in the provided server=<vhost>&counter=<name> parameters.
  • format=internal&reset=false
    Internal a terse internal JSON-based representation of the data that is stored in shared memory, without textual labels or descriptions, only used for debugging

Advanced

Use RequireAny with Require claim <sub> for user specific access count.

Add a custom footer
Add a custom sidebar
Clone this wiki locally