Module ngx_http_oidc_module

The ngx_http_oidc_module module (1.27.4) implements authentication as a Relying Party in OpenID Connect using the Authorization Code Flow.

The module expects the OpenID Provider's configuration to be available via metadata and requires dynamic resolver.

The module can be combined with other access modules via the satisfy directive. Note that the module may still block requests even with satisfy any; as an OpenID Provider might not redirect the user back to nginx.

This module is available as part of our commercial subscription.

http {
    resolver 10.0.0.1;

    oidc_provider my_idp {
        issuer        "https://provider.domain";
        client_id     "unique_id";
        client_secret "unique_secret";
    }

    server {
        location / {
            auth_oidc my_idp;

            proxy_set_header username $oidc_claim_sub;
            proxy_pass       http://backend;
        }
    }
}

The example assumes that the “https://<nginx-host>/oidc_callback” Redirection URI is configured on the OpenID Provider's side. The path can be customized with the redirect_uri directive.

Defines an OpenID Provider for use with the auth_oidc directive.

auth_oidc off;

Enables end user authentication with the specified OpenID Provider.

The special value off cancels the effect of the auth_oidc directive inherited from the previous configuration level.

Sets the Issuer Identifier URL of the OpenID Provider; required directive. The URL must exactly match the value of “issuer” in the OpenID Provider metadata and requires the “https” scheme.

Specifies the client ID of the Relying Party; required directive.

Specifies a secret value used to authenticate the Relying Party with the OpenID Provider.

config_url <issuer>/.well-known/openid-configuration;

Sets a custom URL to retrieve the OpenID Provider metadata.

cookie_name NGX_OIDC_SESSION;

Sets the name of a session cookie.

Sets additional query arguments for the authentication request URL.

extra_auth_args "display=page&prompt=login";

redirect_uri /oidc_callback;

Defines the Redirection URI path for post-authentication redirects expected by the module from the OpenID Provider. The uri must match the configuration on the Provider's side.

scope openid;

Sets requested scopes. The openid scope is always required by OIDC.

Specifies a custom key-value database that stores session data. By default, an 8-megabyte key-value database named oidc_default_store_<provider name> is created automatically.

A separate key-value database should be configured for each Provider to prevent session reuse across providers.

session_timeout 8h;

Sets a timeout after which the session is deleted, unless it was refreshed.

Specifies a file with revoked certificates (CRL) in the PEM format used to verify the certificates of the OpenID Provider endpoints.

ssl_trusted_certificate system CA bundle;

Specifies a file with trusted CA certificates in the PEM format used to verify the certificates of the OpenID Provider endpoints.

The ngx_http_oidc_module module supports embedded variables:

$oidc_id_token

ID token

$oidc_access_token

access token

$oidc_claim_name

top-level ID token claim

Nested claims can be fetched with the auth_jwt module:

http {
    auth_jwt_claim_set $postal_code address postal_code;

    server {
        location / {
            auth_oidc my_idp;
            auth_jwt  off token=$oidc_id_token;

            proxy_set_header x-postal_code $postal_code;
            proxy_pass       http://backend;
        }
    }
}