Mod auth openidc

From TMM Wiki
Jump to: navigation, search
NATS 4
Members Admin
The Members Admin
View Member Details
Add Member
MySQL Auth
Mod Authn DB
Multisite Access
Member Logging
Member Password Retrieval
OpenID Connect
Mod Auth OpenIDC
ID Numbers





To use this, you need to setup NATS as an OpenID Connect Server first.
Apache module mod_auth_openidc allows you to authenticate members using NATS as the 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 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 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. 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>

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 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']
$_SERVER['PHP_AUTH_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:

<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

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 member's area

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

Additional Resources