=encoding utf-8

=head1 NAME

ngx_http_oidc_module - Module ngx_http_oidc_module




=head1



The C<ngx_http_oidc_module> module (1.27.4)
implements authentication as a Relying Party in OpenID Connect using the
L<Authorization Code Flow|https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth>.





The module expects the OpenID Provider's configuration to be available via
L<metadata|https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig> and requires dynamic
L<resolver|ngx_http_core_module>.





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






B<NOTE>

This module is available as part of our
commercial subscription.





=head1 Example Configuration




    
    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
“C<https:E<sol>E<sol>E<lt>nginx-hostE<gt>E<sol>oidc_callback>”
Redirection URI is configured on the OpenID Provider's side.
The path can be customized with the L</redirect_uri> directive.




=head1 Directives

=head2 oidc_provider


B<syntax:> oidc_provider I<I<C<name>> { B<...> } >



B<context:> I<http>





Defines an OpenID Provider for use with the L</auth_oidc> directive.







=head2 auth_oidc


B<syntax:> auth_oidc I<I<C<name>> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<http>


B<context:> I<server>


B<context:> I<location>





Enables end user authentication with the
specified OpenID Provider.





Parameter value can contain variables (1.29.0).





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







=head2 issuer


B<syntax:> issuer I<I<C<URL>>>



B<context:> I<oidc_provider>





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







=head2 client_id


B<syntax:> client_id I<I<C<string>>>



B<context:> I<oidc_provider>





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







=head2 client_secret


B<syntax:> client_secret I<I<C<string>>>



B<context:> I<oidc_provider>





Specifies a secret value
used to authenticate the Relying Party with the OpenID Provider.
The supported
L<authentication
methods|https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication> are
C<client_secret_basic> and
C<client_secret_post> (1.29.3).
The method is selected based on the OpenID Provider metadata
with a preference to C<client_secret_basic>.







=head2 config_url


B<syntax:> config_url I<I<C<URL>>>


B<default:> I<E<lt>issuerE<gt>E<sol>.well-knownE<sol>openid-configuration>


B<context:> I<oidc_provider>





Sets a custom URL to retrieve the OpenID Provider metadata.







=head2 cookie_name


B<syntax:> cookie_name I<I<C<name>>>


B<default:> I<NGX_OIDC_SESSION>


B<context:> I<oidc_provider>





Sets the name of a session cookie.







=head2 extra_auth_args


B<syntax:> extra_auth_args I<I<C<string>>>



B<context:> I<oidc_provider>





Sets additional query arguments for the
L<authentication
request|https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest> URL.

    
    extra_auth_args "display=page&prompt=login";









=head2 frontchannel_logout_uri


B<syntax:> frontchannel_logout_uri I<I<C<uri>>>



B<context:> I<oidc_provider>



This directive appeared in version 1.29.3.





Defines the URI path for triggering
L<front-channel
logout|https://openid.net/specs/openid-connect-frontchannel-1_0.html>.
For the logout request to be associated with a user session,
it must either include the module session cookie or provide
both the “C<iss>” and “C<sid>” arguments.
It is recommended to configure the OpenID Provider to set the
“C<iss>” and “C<sid>” arguments
when invoking this endpoint.







=head2 pkce


B<syntax:> pkce I<C<on> E<verbar> C<off>>



B<context:> I<oidc_provider>



This directive appeared in version 1.29.3.





Explicitly enables or disables PKCE.
By default, PKCE is automatically enabled
based on OpenID Provider metadata.







=head2 redirect_uri


B<syntax:> redirect_uri I<I<C<uri>>>


B<default:> I<E<sol>oidc_callback>


B<context:> I<oidc_provider>





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





Absolute “C<https>” URIs are supported since 1.29.0.







=head2 logout_uri


B<syntax:> logout_uri I<I<C<uri>>>



B<context:> I<oidc_provider>



This directive appeared in version 1.29.0.





Defines the URI path for initiating session logout.
Upon session termination, the user is redirected to
L<Provider's
Logout Endpoint|https://openid.net/specs/openid-connect-rpinitiated-1_0.html#OPMetadata>
or to the post logout page.
If neither is configured, the built-in post logout page is displayed.







=head2 post_logout_uri


B<syntax:> post_logout_uri I<I<C<uri>>>



B<context:> I<oidc_provider>



This directive appeared in version 1.29.0.





Defines the path or absolute URI
to redirect the user to after the logout.
The I<C<uri>> must match the configuration on the Provider's side.
If the post logout page is served by NGINX,
the OIDC module shouldn't be enabled for this location:

    
    http {
        oidc_provider my_idp {
            ...
    
            logout_uri      /logout;
            post_logout_uri /logged_out_page.html;
        }
    
        server {
            auth_oidc my_idp;
    
            location /logged_out_page.html {
                auth_oidc off;
            }
        }
    }








=head2 logout_token_hint


B<syntax:> logout_token_hint I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<oidc_provider>



This directive appeared in version 1.29.0.





Adds the
L<C<id_token_hint>|https://openid.net/specs/openid-connect-rpinitiated-1_0.html#RPLogout>
argument to the
L<Provider's
Logout Endpoint|https://openid.net/specs/openid-connect-rpinitiated-1_0.html#OPMetadata>
when redirecting user during logout.
This argument can be required by some OpenID Providers.







=head2 scope


B<syntax:> scope I<I<C<scope>> ...>


B<default:> I<openid>


B<context:> I<oidc_provider>





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







=head2 session_store


B<syntax:> session_store I<I<C<name>>>



B<context:> I<oidc_provider>





Specifies a custom
L<key-value database|ngx_http_keyval_module>
that stores session data.
By default, an 8-megabyte key-value database named 
C<oidc_default_store_E<lt>provider nameE<gt>>
is created automatically.

B<NOTE>

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








=head2 session_timeout


B<syntax:> session_timeout I<I<C<time>>>


B<default:> I<8h>


B<context:> I<oidc_provider>





Sets a timeout after which the session is deleted, unless it was
L<refreshed|https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokens>.







=head2 ssl_crl


B<syntax:> ssl_crl I<I<C<file>>>



B<context:> I<oidc_provider>





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







=head2 ssl_trusted_certificate


B<syntax:> ssl_trusted_certificate I<I<C<file>>>


B<default:> I<system CA bundle>


B<context:> I<oidc_provider>





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







=head2 userinfo


B<syntax:> userinfo I<C<on> E<verbar> C<off>>


B<default:> I<off>


B<context:> I<oidc_provider>



This directive appeared in version 1.29.0.





Enables downloading of the
L<UserInfo|https://openid.net/specs/openid-connect-core-1_0.html#UserInfo>
data and makes UserInfo claims available via the 
$oidc_claim_C<name> variables.







=head1 Embedded Variables



The C<ngx_http_oidc_module> module supports embedded variables:






=over



=item C<$oidc_id_token>




ID token



=item C<$oidc_access_token>




access token



=item C<$oidc_claim_>I<C<name>>




top-level ID token or UserInfo claim


Nested claims can be fetched with the
L<auth_jwt|ngx_http_auth_jwt_module> 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;
            }
        }
    }








=item C<$oidc_userinfo>




UserInfo data in the JSON format (1.29.0)




=back






