Difference between revisions of "OpenID Connect"
From TMM Wiki
Jump to navigationJump to search| (46 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | {{ | + | {{NATS5 Manual |
| show_members_admin_section = true | | show_members_admin_section = true | ||
}} | }} | ||
| − | As of version 4.1.21.1 NATS can be used as an OpenID Connect | + | As of version 4.1.21.1 NATS can be used as an OpenID Connect Server (OP). 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_Virtual_Host_Settings|example]] implementation. Unlike the standard OpenID Connect Server (OP) implementation, consent for the surfer to provide protected details (like username and email) to the client (members area) is implied. |
| − | == | + | == Setup == |
| − | * Go to the NATS | + | * Go to the NATS configuration admin -> surfer and scroll down to the 'Member OpenID Connect Server' section. |
| − | * Enable the ENABLE_MEMBER_OPENID config option | + | * 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 | + | * 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) | + | * Enter the password (make one up) that your member area(s) will use for the token endpoint authentication into the MEMBER_OPENID_CLIENT_SECRET field. If you are using [[Mod_auth_openidc#Example_Virtual_Host_Settings|mod_auth_openidc]] as the client, this is the value you will need for the OIDCClientSecret field. |
| − | * Decide what domain (and protocol) you will use for the authorization (login) page as well as the token and the userinfo endpoints | + | * 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. | ||
| + | * '''NOTE''': Confirm there is a value set for MEMBER_OPENID_SIGNING_KEY_ID. If it is not set, contact TMM Support to generate the signing key for you. | ||
| + | * Set up an OpenID Connect client in your members area(s). | ||
| − | + | == Additional Configuration Options == | |
| − | + | * 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. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | == | + | * 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. |
| − | 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. | + | |
| − | # 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. | + | * 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. |
| + | |||
| + | * 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. | ||
| + | |||
| + | * MEMBER_OPENID_SIGN_USERINFO_REPLY - Enabling this option will cause NATS OpenID Connect Server (OP) 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 are using [[Mod_auth_openidc#Apache_Configuration|mod_auth_openidc]] as the client, you will need to set the OIDCUserInfoSignedResponseAlg field. | ||
| + | |||
| + | * MEMBER_OPENID_RETURN_REFRESH_TOKEN - Disabling this option will prevent NATS OpenID Connect Server (OP) from generating and returning refresh tokens when creating new access tokens. | ||
| + | |||
| + | * MEMBER_OPENID_INCLUDE_IDTOKEN_ON_REFRESH - Enabling this option will make NATS return the id_token when generating a new access token from a refresh token. | ||
| + | |||
| + | * MEMBER_OPENID_ACCESS_TOKEN_FORMAT - This option determines the format of the access token value return (string or signed JWT). | ||
| + | |||
| + | * MEMBER_OPENID_REFRESH_TOKEN_FORMAT - This option determines the format of the refresh token value return (string or signed JWT). | ||
| + | |||
| + | * MEMBER_OPENID_REFRESH_TOKEN_DURATION - This option determines the length of time (in seconds) that the refresh token (from the token endpoint) is good for. This value needs to be greater than the MEMBER_OPENID_ACCESS_TOKEN_DURATION value. | ||
| + | |||
| + | * THROTTLE_LOGIN, THROTTLE_LOGIN_MAX_COUNT, THROTTLE_LOGIN_TIME_LIMIT - These work like the other [[Throttling|throttling]] settings and apply to the authorization endpoint. | ||
| + | |||
| + | <br />'''The following options are useful for debugging, but for security reasons we recommend leaving them disabled in production environments:''' | ||
| + | |||
| + | * 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 == | ||
| + | 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. | ||
| + | # 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. | ||
# 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. | # 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. | ||
| − | # You can use each site's link domain. To do this, you will need to | + | # You can use each site's link domain. To do this, you will need to enable the MEMBER_OPENID_DYNAMIC_DOMAIN config option. |
| − | # You can make a custom | + | # 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]]. |
== Claims == | == 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 (OP) will return all claims that you enabled. Here is the breakdown of claims that the NATS OpenID Connect Server (OP) can return: | ||
| + | |||
| + | * Default: | ||
| + | ** sub (NATS memberid) | ||
| + | ** username | ||
| + | |||
| + | * Enabling MEMBER_OPENID_BASE_INFO will return: | ||
| + | ** email | ||
| + | ** 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): | ||
| + | ** joined | ||
| + | ** expired | ||
| + | ** expires | ||
| + | ** nats_expires | ||
| + | ** biller_expires | ||
| + | |||
| + | * Enabling MEMBER_OPENID_IDENTIFIER_INFO will return a JSON encoded array named identifier containing the following fields: | ||
| + | ** identid (internal NATS identifier id) | ||
| + | ** loginid (id of the affiliate) | ||
| + | ** campaignid | ||
| + | ** programid | ||
| + | ** optoinid | ||
| + | ** siteid | ||
| + | ** tourid | ||
| + | ** countryid | ||
| + | ** adtoolid | ||
| + | ** billerid | ||
| + | ** subid1 | ||
| + | ** subid2 | ||
| + | ** promotionalid | ||
| + | |||
| + | * Enabling MEMBER_OPENID_ADDRESS_INFO will return a JSON encoded array named address containing the following fields: | ||
| + | ** address1 | ||
| + | ** address2 | ||
| + | ** city | ||
| + | ** state | ||
| + | ** zip | ||
| + | ** country | ||
| + | |||
| + | * Enabling MEMBER_OPENID_CUSTOM_INFO will return a JSON encoded array named customs containing the custom1..10 fields | ||
| + | |||
| + | * Enabling MEMBER_OPENID_PASSTHROUGH_INFO will return a JSON encoded array named passthroughs containing the passthroughs1..5 fields (affiliate passthroughs) | ||
| + | |||
| + | == Additional Troubleshooting== | ||
| + | |||
| + | * If you are running FastCGI and receiving errors about missing the Authorization header, you may want to add the following line to your htaccess files: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1 | ||
| + | * You might have to restart your NATS web server after any changes since the output of the call to the NATS .well-known/member-openid-configuration file can be cached | ||
| + | |||
| + | == Additional Resources == | ||
| + | [[Mod_auth_openidc|TMM wiki on mod_auth_openidc]]<br /> | ||
| + | [http://openid.net/specs/openid-connect-core-1_0.html OpenID Connect Specs] | ||
Latest revision as of 15:31, 28 October 2021
As of version 4.1.21.1 NATS can be used as an OpenID Connect Server (OP). 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 mod_auth_openidc apache module. Here is an example implementation. Unlike the standard OpenID Connect Server (OP) implementation, consent for the surfer to provide protected details (like username and email) to the client (members area) is implied.
Setup
- Go to the NATS configuration admin -> surfer and scroll down to the 'Member OpenID Connect Server' section.
- 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 (make one up) that your member area(s) will use for the token endpoint authentication into the MEMBER_OPENID_CLIENT_SECRET field. If you are using mod_auth_openidc as the client, this is the value you will need for the OIDCClientSecret field.
- Decide what domain (and protocol) you will use for the authorization (login) page as well as the token and the userinfo endpoints.
- Determine what claims you want returned.
- NOTE: Confirm there is a value set for MEMBER_OPENID_SIGNING_KEY_ID. If it is not set, contact TMM Support to generate the signing key for you.
- Set up an OpenID Connect client in your members area(s).
Additional Configuration Options
- 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 status claim. It will have value 1 for active members and 2 for expired members.
- 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.
- 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.
- 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.
- MEMBER_OPENID_SIGN_USERINFO_REPLY - Enabling this option will cause NATS OpenID Connect Server (OP) 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 are using mod_auth_openidc as the client, you will need to set the OIDCUserInfoSignedResponseAlg field.
- MEMBER_OPENID_RETURN_REFRESH_TOKEN - Disabling this option will prevent NATS OpenID Connect Server (OP) from generating and returning refresh tokens when creating new access tokens.
- MEMBER_OPENID_INCLUDE_IDTOKEN_ON_REFRESH - Enabling this option will make NATS return the id_token when generating a new access token from a refresh token.
- MEMBER_OPENID_ACCESS_TOKEN_FORMAT - This option determines the format of the access token value return (string or signed JWT).
- MEMBER_OPENID_REFRESH_TOKEN_FORMAT - This option determines the format of the refresh token value return (string or signed JWT).
- MEMBER_OPENID_REFRESH_TOKEN_DURATION - This option determines the length of time (in seconds) that the refresh token (from the token endpoint) is good for. This value needs to be greater than the MEMBER_OPENID_ACCESS_TOKEN_DURATION value.
- THROTTLE_LOGIN, THROTTLE_LOGIN_MAX_COUNT, THROTTLE_LOGIN_TIME_LIMIT - These work like the other throttling settings and apply to the authorization endpoint.
The following options are useful for debugging, but for security reasons we recommend leaving them disabled in production environments:
- 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
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.
- 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.
- 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.
- You can use each site's link domain. To do this, you will need to enable the MEMBER_OPENID_DYNAMIC_DOMAIN config option.
- 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 domains.
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 (OP) will return all claims that you enabled. Here is the breakdown of claims that the NATS OpenID Connect Server (OP) can return:
- Default:
- sub (NATS memberid)
- username
- Enabling MEMBER_OPENID_BASE_INFO will return:
- 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):
- joined
- expired
- expires
- nats_expires
- biller_expires
- Enabling MEMBER_OPENID_IDENTIFIER_INFO will return a JSON encoded array named identifier containing the following fields:
- identid (internal NATS identifier id)
- loginid (id of the affiliate)
- campaignid
- programid
- optoinid
- siteid
- tourid
- countryid
- adtoolid
- billerid
- subid1
- subid2
- promotionalid
- Enabling MEMBER_OPENID_ADDRESS_INFO will return a JSON encoded array named address containing the following fields:
- address1
- address2
- city
- state
- zip
- country
- Enabling MEMBER_OPENID_CUSTOM_INFO will return a JSON encoded array named customs containing the custom1..10 fields
- Enabling MEMBER_OPENID_PASSTHROUGH_INFO will return a JSON encoded array named passthroughs containing the passthroughs1..5 fields (affiliate passthroughs)
Additional Troubleshooting
- If you are running FastCGI and receiving errors about missing the Authorization header, you may want to add the following line to your htaccess files: SetEnvIf Authorization "(.*)" HTTP_AUTHORIZATION=$1
- You might have to restart your NATS web server after any changes since the output of the call to the NATS .well-known/member-openid-configuration file can be cached
