Difference between revisions of "OpenID Connect"

From TMM Wiki
Jump to navigationJump to search
m (minor changes)
m (minor changes)
Line 3: Line 3:
 
}}
 
}}
  
−
As of version 4.1.21.1 NATS can be used as an OpenID Connect server.  This is another option for member authentication.  In order to utilize this feature, you will need to use an OpenID Connect client.  When developing this feature, we used the [https://github.com/zmartzone/mod_auth_openidc mod_auth_openidc] apache module. Here is an [[Mod_auth_openidc|example]] implementation.  Unlike the standard OpenID Connect server implemantaion, consent for the surfer to provide protected details (like username and email) to the client (members area) is implied.
+
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]]
  
−
== Setup ==
+
== Installing mod_auth_openidc ==
−
* Go to the NATS config admin -> surfers and scroll down to the 'Member OpenID Connect Server' section
+
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.
−
* Enable the ENABLE_MEMBER_OPENID config option
 
−
* Provide a list of all ips defined on your member area server(s) by entering it into the MEMBER_OPENID_SECURE_IPS field
 
−
* Enter the password that your member area(s) will use for the token endpoint authentication into the MEMBER_OPENID_CLIENT_SECRET field
 
−
* Decide what [[OpenID_Connect#Authorization_Domain|domain]] (and protocol) you will use for the authorization (login) page as well as the token and the userinfo endpoints
 
−
* Determine what [[OpenID_Connect#Claims|claims]] you want returned
 
−
* Set up an OpenID Connect client in your members area(s)
 
  
−
== Additional Configuration Options ==
+
== Member Area Configuration ==
−
* MEMBER_OPENID_EXPIRED_LOGIN - Enabling this option will allow expired members to login. You will be able to differentiate active members from expired members by using the [[OpenID_Connect#Claims|status claim]].  It will have value 1 for active members and 2 for expired members.
+
* 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.
  
−
* MEMBER_OPENID_SETUP_ERROR_SHOW_TEMPLATE - Enabling this option will display a NATS site template when a configuration error occurs instead of redirecting back to the members area.  An example of a configuration error would be leaving the ENABLE_MEMBER_OPENID option disabled.
+
== 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>
  
−
* MEMBER_OPENID_AUTH_CODE_DURATION - This option determines the length of time (in seconds) that the auth code (from the authorization endpoint aka the login page) is good for.
+
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>
 +
OIDCUserInfoSignedResponseAlg RS256
 +
</pre>
  
−
* MEMBER_OPENID_ACCESS_TOKEN_DURATION - This option determines the length of time (in seconds) that the access token (from the token endpoint) is good for.
+
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>
  
−
* MEMBER_OPENID_SIGN_USERINFO_REPLY - Enabling this option will cause NATS OpenID Connect server to sign the userinfo endpoint reply (in the same way that id_token is signed in the token endpoint reply) and return a JSON Web Token instead of a JSON encoded array.
+
If you choose to set up an error template, you will need to add this to your apache virtual host configuration:
 +
<pre>
 +
OIDCHTMLErrorTemplate <path/to/your/apache/error/template>
 +
</pre>
  
−
* THROTTLE_LOGIN, THROTTLE_LOGIN_MAX_COUNT, THROTTLE_LOGIN_TIME_LIMIT - These work like the other [[Throttling|throttling]] settings and apply to the authorization endpoint
+
If you choose to set up 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>
  
−
<br />'''The following options are useful for debugging, but for security reasons we recommend leaving them disabled in production environments:'''
+
== 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.
−
* MEMBER_OPENID_DESCRIPTIVE_LOGIN_ERROR - Enabling this option will display a descriptive error message on the login page when the authentication fails.  Some of the example error messages include 'Incorrect username!' and 'Incorrect password!'.  If this option is disabled, regardless of the reason for failed authentication, members will receive the 'Login Failed!' error message.
 
−
 
 
−
* MEMBER_OPENID_REDIECT_ERROR_DETAIL - Enabling this option will provide a detailed error description when a configuration error occurs at the authorization endpoint.
 
−
 
 
−
* MEMBER_OPENID_POST_ERROR_DETAIL - Enabling this option will provide a detailed error description on token and userinfo endpoint errors.
 
  
−
== Authorization Domain ==
+
Please note that the member's username will be available in the following variables:
−
You have a couple options when deciding what domain (and protocol) will be used for the authorization (login) page, as well as the token and the userinfo endpoints.
+
<pre>
−
# You can use the main NATS url.  In this case, the value of the PROJECT_HOSTNAME config setting will be used for the domain, and the protocol will be determined by the PROJECT_HOSTNAME_DISPLAY_HTTPS config setting.
+
$_SERVER['OIDC_CLAIM_username']
−
# You can provide a single domain (and protocol) to use via the MEMBER_OPENID_DOMAIN config setting.  This is very similar to the option above, except that it will be different than the main NATS domain.
+
$_SERVER['REMOTE_USER']
−
# You can use each site's link domain.  To do this, you will need to enable the MEMBER_OPENID_DYNAMIC_DOMAIN config option.
+
$_SERVER['PHP_AUTH_USER']
−
# You can make a custom authorization domain for each site.  This is very similar to the option above, except that it will be different than the domain of the join page (login.yoursite.com instead of join.yoursite.com).  You will need to set up each of these domains in a similar way that you set up your [[Link_Domain|link domains]].
+
</pre>
−
 
 
−
== Claims ==
 
−
The id_token that is generated by the token endpoint contains only the sub claim.  The value is the NATS member id for the successfully authenticated member.  The userinfo endpoint contains a variety of other claims.  NATS OpenID Connect server will return all claims that you enabled.  Here is the breakdown of claims that the NATS OpenID Connect server can return:
 
  
−
* Default:
+
When protecting your members area, you can use the value of one of the claims.  Here is an example:
−
** sub (NATS memberid)
+
<pre>
−
** username
+
<Directory /path/to/the/full/members/section>
 +
  AuthType openid-connect
 +
  Require claim trial:0
 +
</Directory>
 +
</pre>
  
−
* Enabling MEMBER_OPENID_BASE_INFO will return:
+
== Example Virtual Host Settings ==
−
** email
+
Here is an example extract from an apache virtual host for a members area:
−
** firstname
 
−
** lastname
 
−
** trial (1 if in trial, 0 otherwise)
 
−
** status (1 if active, 2 if expired)
 
−
** siteid
 
  
−
* Enabling MEMBER_OPENID_JOIN_EXPIRE_INFO will return a JSON encoded array named join_expire containing the following fields (all UNIX timestamps):
+
<pre>
−
** joined
+
<Directory /path/to/the/members/section>
−
** expired
+
  AuthType openid-connect
−
** expires
+
  Require valid-user
−
** nats_expires
+
</Directory>
−
** biller_expires
 
  
−
* Enabling MEMBER_OPENID_IDENTIFIER_INFO will return a JSON encoded array named identifier containing the following fields:
+
OIDCProviderMetadataURL <your OpenID Connect domain and protocol>/.well-known/member-openid-configuration
−
** identid (internal NATS identifier id)
+
OIDCClientID <NATS Site ID or a comma separated list of NATS Site IDs>
−
** loginid (id of the affiliate)
+
OIDCClientSecret <value of the NATS MEMBER_OPENID_CLIENT_SECRET configuration option>
−
** campaignid
+
OIDCScope openid
−
** programid
+
OIDCRedirectURI <url of your vanity script>
−
** optoinid
+
OIDCCryptoPassphrase <encryption password that is used for cookie and cache data>
−
** siteid
+
OIDCSessionInactivityTimeout <period of inactivity (in seconds) before the member is logged out>
−
** tourid
+
OIDCSessionMaxDuration <value of the MEMBER_OPENID_ACCESS_TOKEN_DURATION configuration option>
−
** countryid
+
OIDCRemoteUserClaim username
−
** adtoolid
+
OIDCUserInfoRefreshInterval 0
−
** billerid
+
OIDCTokenBindingPolicy disabled
−
** subid1
+
</pre>
−
** subid2
 
−
** promotionalid
 
  
−
* Enabling MEMBER_OPENID_ADDRESS_INFO will return a JSON encoded array named address containing the following fields:
+
== Sample Scripts ==
−
** address1
+
vanity page (not a typo, it should be blank)
−
** address2
+
<pre>
−
** city
+
</pre>
−
** state
 
−
** zip
 
−
** country
 
  
−
* Enabling MEMBER_OPENID_CUSTOM_INFO will return a JSON encoded array named customs containing the custom1..10 fields
+
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>
  
−
* Enabling MEMBER_OPENID_PASSTHROUGH_INFO will return a JSON encoded array named passthroughs containing the passthroughs1..5 fields (affiliate passthroughs)
+
error template
 +
<pre>
 +
there was an error<br>
 +
message: %s<br>
 +
description: %s<br><br>
 +
<a href="<url of your members area>">Try Again</a>
 +
</pre>
  
 
== Additional Resources ==
 
== Additional Resources ==
−
[[Mod_auth_openidc|TMM wiki on mod_auth_openidc]]
+
* [https://github.com/zmartzone/mod_auth_openidc/releases mod_auth_openidc releases]
−
[http://openid.net/specs/openid-connect-core-1_0.html OpenID Connect Specs]
+
* [https://github.com/zmartzone/mod_auth_openidc/wiki mod_auth_openidc wiki]
 +
* [https://github.com/zmartzone/mod_auth_openidc mod_auth_openidc source code]

Revision as of 15:32, 3 August 2018

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

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>



Additional Resources






Retrieved from "https://tmmwiki.com/index.php?title=OpenID_Connect&oldid=23962"