# mod\_auth\_openidc

*Article Topics:* [*Members*](/getting-started/common-topics/members.md)

To use mod\_auth\_openidc, you need to set up NATS as an [OpenID Connect Server (OP)](/nats-admin/members/further-reading/openid-connect.md) first.\
Apache module [mod\_auth\_openidc](https://github.com/OpenIDC/mod_auth_openidc/tree/v2.4.11.2) allows you to authenticate members using NATS as the [OpenID Connect Server (OP)](/nats-admin/members/further-reading/openid-connect.md)

## Installing mod\_auth\_openidc

Please ask your host / server admin to install the [mod\_auth\_openidc apache module](https://github.com/OpenIDC/mod_auth_openidc/releases/tag/v2.4.11.2) on your member area server(s) (if not already installed). It would be best if your host / server admin can use one of the install packages. If not, your host / server admin can compile it from source. NATS OpenID Connect Server (OP) implementation supports mod\_auth\_openidc versions >= 2.4.11.2.

## Member Area Configuration

* You will need to create a vanity script inside your members area. This should be a completely blank script that servers no content. It is only needed for the inner workings of the mod\_auth\_openidc apache module. The only requirement is that this script must be protected by the mod\_auth\_openidc apache module using either the \<Directory> or the \<Files> directives.
* You can optionally create an error template and an unauthorized page so that you have better control of what your members see in case of errors. This will allow you to control the look and feel of those pages as well as provide members with help (like links back to the login page).
* You might need to update the link to your members area. It will need to be a link to any script protected by the \<Directory> or the \<Files> directives other than the vanity script.

## Apache Configuration

Documentation for all available apache settings is [here](https://github.com/OpenIDC/mod_auth_openidc/blob/v2.4.11.2/auth_openidc.conf). You can protect directories or individual files using the \<Directory> or the \<Files> directives. Here is an example:

```
<Directory /path/to/the/members/section>
  AuthType openid-connect
  Require valid-user
</Directory>
```

If you choose to sign the reply from the userinfo endpoint (recommended), you will need to add this to your apache virtual host configuration:

```
OIDCUserInfoSignedResponseAlg RS256
```

If you do not have an ssl cert for the login page and/or your members area (not recommended), you will need to add this to your apache virtual host configuration:

```
OIDCSSLValidateServer Off
```

If you choose to set up an error template, you will need to add this to your apache virtual host configuration:

```
OIDCHTMLErrorTemplate <path/to/your/apache/error/template>
```

If you choose to set up an unauthorized page, you will need to add this to your apache virtual host configuration:

```
ErrorDocument 401 <full or relative url to your unauthorized page>
```

To renew your access token, your members area can call this url:

{% code overflow="wrap" %}

```
<full or relative  url of your vanity script>?refresh=<url of the page in the members area to redirect to on success>&access_token=<?=$_SERVER['OIDC_access_token']?>
```

{% endcode %}

If your members area needs access to the refresh token (not recommended), you will need to add this to your apache virtual host configuration:

```
OIDCPassRefreshToken On
```

If your NATS install is behind a load balancer, you will need the following setting

```
OIDCXForwardedHeaders <header> <another header (if needed)> <another header (if needed)> 
```

## Claims

The mod\_auth\_openidc apache module will add all claims received from the token and the userinfo endpoints to the $\_SERVER superglobal. For example, if you enable the MEMBER\_OPENID\_BASE\_INFO configuration option in your NATS install, you will get the trial flag value as part of the userinfo response. You can then use it in your code by using the $\_SERVER\['OIDC\_CLAIM\_trial'] variable. Please reference the [OpenID Connect](/nats-admin/members/further-reading/openid-connect.md) setup article for more info on available claims.

Please note that the member's username will be available in the following variables:

```
$_SERVER['OIDC_CLAIM_username']
$_SERVER['REMOTE_USER']
```

When protecting your members area, you can use the value of one of the claims. Here is an example:

```
<Directory /path/to/the/full/members/section>
  AuthType openid-connect
   Require claim trial:0
</Directory>
```

## Example Virtual Host Settings

Here is an example extract from an apache virtual host for a members area:

{% code overflow="wrap" %}

```
<Directory /path/to/the/members/section>
  AuthType openid-connect
  Require valid-user
</Directory>

OIDCProviderMetadataURL <your NATS domain and protocol (preferably https)>/.well-known/member-openid-configuration
OIDCClientID <NATS Site ID or a comma separated list of NATS Site IDs>
OIDCClientSecret <value of the NATS MEMBER_OPENID_CLIENT_SECRET configuration option>
OIDCScope openid
OIDCRedirectURI <url of your vanity script>
OIDCCryptoPassphrase <encryption password (make one up) that is used for cookie and cache data>
OIDCSessionInactivityTimeout <period of inactivity (in seconds) before the member is logged out>
OIDCSessionMaxDuration <the length of time (in seconds) before the member is logged out regardless of activity, access and refresh tokens>
OIDCRemoteUserClaim username
OIDCUserInfoRefreshInterval <length of time (in seconds) between calls to the userinfo endpoint>
OIDCTokenBindingPolicy disabled
OIDCRefreshAccessTokenBeforeExpiry <length of time (in seconds) before the current access token expires to use the refresh token to obtain a new access token> logout_on_error
OIDCInfoHook access_token id_token userinfo session remote_user timeout exp
```

{% endcode %}

## Sample Scripts

vanity page (not a typo, it should be blank)

```
```

unauthorized page

```
You are not allowed to view this page, please try logging in<br><br>
<a href="<url of your members area>">Log In</a>
```

error template

```
there was an error<br>
message: %s<br>
description: %s<br><br>
<a href="<url of your members area>">Try Again</a>
```

logout button for the members area

{% code overflow="wrap" %}

```
<full or relative  url of your vanity script>?logout=<url of the page to redirect the logged out member to>
```

{% endcode %}

## Additional Resources

* [mod\_auth\_openidc releases](https://github.com/zmartzone/mod_auth_openidc/releases)
* [mod\_auth\_openidc wiki](https://github.com/zmartzone/mod_auth_openidc/wiki)
* [mod\_auth\_openidc source code](https://github.com/OpenIDC/mod_auth_openidc/tree/v2.4.11.2)

## Related Articles

{% content-ref url="/pages/GHyiHOP65KLUI0GVcYft" %}
[OpenID Connect](/nats-admin/members/further-reading/openid-connect.md)
{% endcontent-ref %}

{% content-ref url="/pages/MLwujsZcWCjGB2W72IsY" %}
[Members](/nats-admin/members.md)
{% endcontent-ref %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.toomuchmedia.com/nats-admin/members/further-reading/mod_auth_openidc.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.