View source for Mod auth openidc

{{NATS4 Manual
| show_members_admin_section = true
}}

Apache module [https://github.com/zmartzone/mod_auth_openidc mod_auth_openidc] allows you to authenticate [[Ct#Member|members]] using NATS as the [[Openid_connect|OpenID Connect server]]

== Installing mod_auth_openidc ==
Please ask your host to install the mod_auth_openidc apache module on your member area server(s) if not already installed.  Here is a [https://github.com/zmartzone/mod_auth_openidc/releases link] to their releases.  It would be best if they can use one of the install packages.  If not, they can compile it from source.  NATS OpenID Connect server supports mod_auth_openidc version >= 2.2.0.

== Member Area Configuration ==
* You will need to make 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 works 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 make 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 change 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 [https://github.com/zmartzone/mod_auth_openidc/blob/master/auth_openidc.conf here].  You can protect directories or individual files using the <Directory> or the <Files> directives.  Here is an example.
<pre>
<Directory /path/to/the/members/section>
  AuthType openid-connect
  Require valid-user
</Directory>
</pre>

If you decide to sign the reply from the userinfo endpoint (recommended), you will need to add this to your apache virtual host configuration.
<pre>
OIDCUserInfoSignedResponseAlg RS256
</pre>

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.
<pre>
OIDCSSLValidateServer Off
</pre>

If you setup an error template, you will need to add this to your apache virtual host configuration.
<pre>
OIDCHTMLErrorTemplate <path/to/your/apache/error/template>
</pre>

If you decide to setup an unauthorized page, you will need to add this to your apache virtual host configuration.
<pre>
ErrorDocument 401 <full or relative url to your unauthorized page>
</pre>

== 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 turn on 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|OpenID Connect setup article]] for more info on available claims.

Please note that the member's username will be available in the following variables.
<pre>
$_SERVER['OIDC_CLAIM_username']
$_SERVER['REMOTE_USER']
$_SERVER['PHP_AUTH_USER']
</pre>

When protecting your members area, you can use the value of one of the claims.  Here is an example.
<pre>
<Directory /path/to/the/full/members/section>
  AuthType openid-connect
   Require claim trial:0
</Directory>
</pre>

== Example Virtual Host Settings ==
Here is an example extract from an apache virtual host for a members area.

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

OIDCProviderMetadataURL <your OpenID Connect domain and protocol>/.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 that is used for cookie and cache data>
OIDCSessionInactivityTimeout <period of inactivity (in seconds) before the member is logged out>
OIDCSessionMaxDuration <value of the MEMBER_OPENID_ACCESS_TOKEN_DURATION configuration option>
OIDCRemoteUserClaim username
OIDCUserInfoRefreshInterval 0
OIDCTokenBindingPolicy disabled
</pre>

== Sample Scripts ==
vanity page (not a typo, it should be blank)
<pre>
</pre>

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

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