Difference between revisions of "Mod auth openidc"
From TMM Wiki
Jump to navigationJump to search| (28 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | 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 | + | {{NATS5 Manual |
| + | | show_members_admin_section = true | ||
| + | }} | ||
| + | To use this, you need to setup NATS as an [[OpenID_Connect|OpenID Connect Server (OP)]] first.<br> | ||
| + | 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 (OP)]] | ||
== Installing mod_auth_openidc == | == 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 | + | Please ask your host / server admin to install the [https://github.com/zmartzone/mod_auth_openidc/releases mod_auth_openidc apache module] 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.2.0. |
== Member Area Configuration == | == Member Area Configuration == | ||
| − | * You will need to | + | * 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 | + | * 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 | + | * 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 == | == Apache Configuration == | ||
| − | Documentation for all available apache settings is [https://github.com/zmartzone/mod_auth_openidc/blob/master/auth_openidc.conf here] | + | 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 | + | If you choose to sign the reply from the userinfo endpoint (recommended), you will need to add this to your apache virtual host configuration: |
<pre> | <pre> | ||
OIDCUserInfoSignedResponseAlg RS256 | OIDCUserInfoSignedResponseAlg RS256 | ||
</pre> | </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 | + | 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> | <pre> | ||
OIDCSSLValidateServer Off | OIDCSSLValidateServer Off | ||
</pre> | </pre> | ||
| − | If you | + | If you choose to set up an error template, you will need to add this to your apache virtual host configuration: |
<pre> | <pre> | ||
OIDCHTMLErrorTemplate <path/to/your/apache/error/template> | OIDCHTMLErrorTemplate <path/to/your/apache/error/template> | ||
</pre> | </pre> | ||
| − | If you | + | If you choose to set up an unauthorized page, you will need to add this to your apache virtual host configuration: |
<pre> | <pre> | ||
ErrorDocument 401 <full or relative url to your unauthorized page> | ErrorDocument 401 <full or relative url to your unauthorized page> | ||
| + | </pre> | ||
| + | |||
| + | To renew your access token, your members area can call this url: | ||
| + | <pre> | ||
| + | <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']?> | ||
| + | </pre> | ||
| + | |||
| + | If your members area needs access to the refresh token (not recommended), you will need to add this to your apache virtual host configuration: | ||
| + | <pre> | ||
| + | OIDCPassRefreshToken On | ||
| + | </pre> | ||
| + | |||
| + | If your NATS install is behind a load balancer, you will need the following setting | ||
| + | <pre> | ||
| + | OIDCXForwardedHeaders <header> <another header (if needed)> <another header (if needed)> | ||
| + | </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 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|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'] | ||
| + | </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> | </pre> | ||
== Example Virtual Host Settings == | == Example Virtual Host Settings == | ||
| − | Here is an example extract from an apache virtual host for a members area | + | Here is an example extract from an apache virtual host for a members area: |
<pre> | <pre> | ||
| Line 41: | Line 83: | ||
</Directory> | </Directory> | ||
| − | OIDCProviderMetadataURL <your | + | 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> | OIDCClientID <NATS Site ID or a comma separated list of NATS Site IDs> | ||
OIDCClientSecret <value of the NATS MEMBER_OPENID_CLIENT_SECRET configuration option> | OIDCClientSecret <value of the NATS MEMBER_OPENID_CLIENT_SECRET configuration option> | ||
OIDCScope openid | OIDCScope openid | ||
OIDCRedirectURI <url of your vanity script> | OIDCRedirectURI <url of your vanity script> | ||
| − | OIDCCryptoPassphrase <encryption password that is used for cookie and cache data> | + | 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> | OIDCSessionInactivityTimeout <period of inactivity (in seconds) before the member is logged out> | ||
| − | OIDCSessionMaxDuration < | + | OIDCSessionMaxDuration <the length of time (in seconds) before the member is logged out regardless of activity, access and refresh tokens> |
OIDCRemoteUserClaim username | OIDCRemoteUserClaim username | ||
| − | OIDCUserInfoRefreshInterval | + | OIDCUserInfoRefreshInterval <length of time (in seconds) between calls to the userinfo endpoint> |
OIDCTokenBindingPolicy disabled | 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 | ||
</pre> | </pre> | ||
| Line 65: | Line 108: | ||
</pre> | </pre> | ||
| − | error | + | error template |
<pre> | <pre> | ||
there was an error<br> | there was an error<br> | ||
| Line 72: | Line 115: | ||
<a href="<url of your members area>">Try Again</a> | <a href="<url of your members area>">Try Again</a> | ||
</pre> | </pre> | ||
| + | |||
| + | logout button for the members area | ||
| + | <pre> | ||
| + | <full or relative url of your vanity script>?logout=<url of the page to redirect the logged out member to> | ||
| + | </pre> | ||
| + | |||
| + | == Additional Resources == | ||
| + | * [https://github.com/zmartzone/mod_auth_openidc/releases mod_auth_openidc releases] | ||
| + | * [https://github.com/zmartzone/mod_auth_openidc/wiki mod_auth_openidc wiki] | ||
| + | * [https://github.com/zmartzone/mod_auth_openidc mod_auth_openidc source code] | ||
| + | * [[OpenID_Connect|Setting up NATS as an OpenID Connect Server (OP)]] | ||
Latest revision as of 19:28, 17 August 2023
To use this, you need to setup NATS as an OpenID Connect Server (OP) first.
Apache module mod_auth_openidc allows you to authenticate members using NATS as the OpenID Connect Server (OP)
Installing mod_auth_openidc
Please ask your host / server admin to install the mod_auth_openidc apache module 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.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>
To renew your access token, your members area can call this url:
<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']?>
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 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:
<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
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
<full or relative url of your vanity script>?logout=<url of the page to redirect the logged out member to>
