OpenID Connect

From TMM Wiki
Jump to navigationJump to search
NATS 5
Members Section
Members Management
Adding a Member
View Member Details
Restricted Values
OpenID Connect
Mod Auth OpenIDC
    Adtool
GET /adtool/admin
GET /adtool/adtools
GET /adtool/adtool
GET /adtool/adtool-rules
GET /adtool/adtool-rule
GET /adtool/categories
GET /adtool/field-options
GET /adtool/field-types
GET /adtool/groups
GET /adtool/search
GET /adtool/templates
GET /adtool/types
GET /adtool/type
POST /adtool/adtool
POST /adtool/adtool-rule
POST /adtool/category
POST /adtool/field
POST /adtool/field-option
POST /adtool/group
POST /adtool/import
POST /adtool/type
PATCH /adtool/adtool
PATCH /adtool/adtool-group
PATCH /adtool/adtool-rule
PATCH /adtool/category
PATCH /adtool/field
PATCH /adtool/field-option
PATCH /adtool/group
PATCH /adtool/move
PATCH /adtool/restore-adtool
PATCH /adtool/restore-category
PATCH /adtool/restore-field
PATCH /adtool/restore-field-option
PATCH /adtool/restore-type
PATCH /adtool/type
DELETE /adtool/adtool
DELETE /adtool/adtool-rule
DELETE /adtool/category
DELETE /adtool/field
DELETE /adtool/field-option
DELETE /adtool/group
DELETE /adtool/type
    Affiliate
DELETE /affiliate/account-rep
DELETE /affiliate/account-type
DELETE /affiliate/affiliate
DELETE /affiliate/doc
DELETE /affiliate/group
DELETE /affiliate/permissions
GET /affiliate/account-changes
GET /affiliate/account-types
GET /affiliate/admin-settings
GET /affiliate/campaigns
GET /affiliate/current
GET /affiliate/current-permissions
GET /affiliate/docs
GET /affiliate/doc
GET /affiliate/groups
GET /affiliate/group
GET /affiliate/hits
GET /affiliate/link-styles
GET /affiliate/loginids
GET /affiliate/loginlog
GET /affiliate/manual-payout
GET /affiliate/news-sections
GET /affiliate/notes
GET /affiliate/notices
GET /affiliate/override
GET /affiliate/payout
GET /affiliate/payment-periods
GET /affiliate/payvia-types
GET /affiliate/payvia-type
GET /affiliate/permissions
GET /affiliate/programcampaigns
GET /affiliate/referrer
GET /affiliate/referring-urls
GET /affiliate/reps
GET /affiliate/rest-methods
GET /affiliate/search
GET /affiliate/search-limited
GET /affiliate/settings
GET /affiliate/skins
GET /affiliate/soap-functions
GET /affiliate/status
PATCH /affiliate/adminsettings
PATCH /affiliate/account-change
PATCH /affiliate/account-type
PATCH /affiliate/account-type-permissions
PATCH /affiliate/admin-setting
PATCH /affiliate/affiliate-account-type
PATCH /affiliate/affiliate-group
PATCH /affiliate/allsettings
PATCH /affiliate/account-rep
PATCH /affiliate/avatar
PATCH /affiliate/customs
PATCH /affiliate/defaults
PATCH /affiliate/details
PATCH /affiliate/override
PATCH /affiliate/password
PATCH /affiliate/payment-period
PATCH /affiliate/payvia
PATCH /affiliate/payvia-info
PATCH /affiliate/permissions
PATCH /affiliate/referrer
PATCH /affiliate/reset-api
PATCH /affiliate/reset-rss
PATCH /affiliate/reset-tos
PATCH /affiliate/rest-permissions
PATCH /affiliate/restore
PATCH /affiliate/restore-account-type
PATCH /affiliate/settings
PATCH /affiliate/soap-permissions
PATCH /affiliate/status
POST /affiliate/account-type
POST /affiliate/add
POST /affiliate/doc
POST /affiliate/group
POST /affiliate/invoice
POST /affiliate/manual-sale
POST /affiliate/note
    Biller
GET /biller/available
GET /biller/partner-available
GET /biller/billerdata
GET /biller/cascades
GET /biller/cascades-available
GET /biller/cascade-count
GET /biller/cascade-history
GET /biller/cascade-rules
GET /biller/cascade-rule
GET /biller/cascade-step-count
GET /biller/cascade-steps
GET /biller/cascade-detail
GET /biller/cascade-list
GET /biller/count
GET /biller/detail
GET /biller/fees
GET /biller/partner-fees
GET /biller/last_poll
GET /biller/partner-last-poll
GET /biller/list
GET /biller/partner-detail
GET /biller/partner-list
GET /biller/partner-shortnames
GET /biller/process_types
GET /biller/partner-process-types
GET /biller/shortnames
GET /biller/transaction_types
GET /biller/partner-transaction-types
GET /biller/taxes
POST /biller/add
POST /biller/cascade
POST /biller/cascade-rule
POST /biller/cascade-step
POST /biller/partner
PATCH /biller/cascade
PATCH /biller/cascade-rule
PATCH /biller/cascade-step
PATCH /biller/cascade-steps-reorder
PATCH /biller/fee
PATCH /biller/partner-fee
PATCH /biller/restore
PATCH /biller/restore-cascade
PATCH /biller/restore-partner
PATCH /biller/setting
PATCH /biller/partner-setting
PATCH /biller/tax
DELETE /biller/biller
DELETE /biller/cascade
DELETE /biller/cascade-rule
DELETE /biller/cascade-step
DELETE /biller/fee
DELETE /biller/partner-fee
DELETE /biller/partner
DELETE /biller/tax
    Codes
GET /codes/affiliate-codes
GET /codes/decode
GET /codes/linkcodes
GET /codes/strack
    Config
DELETE /config/setting
GET /config/section
GET /config/sections
PATCH /config/affiliate_default
PATCH /config/section
    Include
DELETE /include/include
DELETE /include/step
GET /include/include
GET /include/includes
GET /include/templates
PATCH /include/include
PATCH /include/restore
PATCH /include/step
POST /include/include
POST /include/step
    Mailing
DELETE /mailing/mailing
DELETE /mailing/mailing-rule
DELETE /mailing/queue
GET /mailing/mailing
GET /mailing/mailings
GET /mailing/mailing-rules
GET /mailing/mailing-rule
GET /mailing/queue
GET /mailing/removelist
PATCH /mailing/mailing
PATCH /mailing/mailing-rule
PATCH /mailing/removelist
PATCH /mailing/removelist-queue
PATCH /mailing/resend-queue
PATCH /mailing/restore-queue
PATCH /mailing/send-mailing
PATCH /mailing/send-test-mailing
POST /mailing/mailing
POST /mailing/mailing-rule
POST /mailing/removelist
    Maintenance
DELETE /maintenance/log
DELETE /maintenance/cache
GET /maintenance/admin-actions
GET /maintenance/log
GET /maintenance/logs
GET /maintenance/nats
GET /maintenance/report
GET /maintenance/report-progress
GET /maintenance/reports
GET /maintenance/server
GET /maintenance/table
GET /maintenance/tables
GET /maintenance/table-clean-count
GET /maintenance/table-clean-progress
PATCH /maintenance/log
PATCH /maintenance/report
PATCH /maintenance/table
    Member
GET /member/available_flags
GET /member/encryptusername
GET /member/authstring
GET /member/details
GET /member/flags
GET /member/loginlog
GET /member/matching
GET /member/notes
GET /member/notices
GET /member/restricted-values
GET /member/search
GET /member/suggestedcanceloffers
GET /member/surfer-actions
PATCH /member/details
PATCH /member/expiration
PATCH /member/expiremanual
PATCH /member/resend-transaction-email
PATCH /member/resend-transaction-postback
PATCH /member/restricted-value
PATCH /member/forget
PATCH /member/lock
PATCH /member/unlock
POST /member/flag
POST /member/login
POST /member/note
POST /member/restricted-value
DELETE /member/flag
DELETE /member/restricted-value
    Message
DELETE /message/message
DELETE /message/permanent
GET /message/count
GET /message/messages
GET /message/view
PATCH /message/read
PATCH /message/unread
PATCH /message/undelete
POST /message/message
    News
DELETE /news/entry
DELETE /news/section
GET /news/entry
GET /news/news
GET /news/sections
PATCH /news/entry
POST /news/entry
POST /news/section
    Notification
DELETE /notification/notification
DELETE /notification/permanent
GET /notification/count
GET /notification/notifications
GET /notification/view
PATCH /notification/read
PATCH /notification/unread
PATCH /notification/undelete
    Option
GET /option/options
GET /option/rule
PATCH /option/rule
PATCH /option/text
POST /option/rule
    Payment
DELETE /payment/invoice
DELETE /payment/payout-period
DELETE /payment/payvia-field
DELETE /payment/payvia-field-mc
DELETE /payment/payvia-rule
GET /payment/dump-format
GET /payment/dump-formats
GET /payment/invoices
GET /payment/payments
GET /payment/payment-dumps
GET /payment/payment-dump
GET /payment/payment-search
GET /payment/payvia
GET /payment/payvias
GET /payment/payvia-fields
GET /payment/payvia-field-mcs
GET /payment/payout-period
GET /payment/payout-periods
GET /payment/payvia-rules
GET /payment/payvia-rule
GET /payment/payviarule
PATCH /payment/copy-dump-format
PATCH /payment/default-payout-period
PATCH /payment/dump-format
PATCH /payment/duplicate-payvia
PATCH /payment/invoice
PATCH /payment/payment
PATCH /payment/payment-paid
PATCH /payment/payment-store
PATCH /payment/payment-unstore
PATCH /payment/payments
PATCH /payment/payments-unstore
PATCH /payment/payout-period
PATCH /payment/payout-period-affiliates
PATCH /payment/payvia
PATCH /payment/payvia-field
PATCH /payment/payvia-fields-reorder
PATCH /payment/payvia-field-mc
PATCH /payment/payvia-field-mcs-reorder
PATCH /payment/payvia-rule
PATCH /payment/payviarule
PATCH /payment/restore-payout-period
PATCH /payment/restore-payvia-field
PATCH /payment/restore-payvia-field-mc
POST /payment/check-dump
POST /payment/dump-format
POST /payment/import-dump
POST /payment/invoice
POST /payment/payout-period
POST /payment/payvia
POST /payment/payvia-field
POST /payment/payvia-field-mc
POST /payment/payvia-rule
    Program
DELETE /program/program
DELETE /program/payout-change
DELETE /program/payout-change-tier
GET /program/additional-payout-change-targets
GET /program/affiliate-available
GET /program/detail
GET /program/list
GET /program/options
GET /program/payout-changes
GET /program/redirect-available
GET /program/sites
GET /program/tours
GET /program/types
PATCH /program/default_payout
PATCH /program/details
PATCH /program/disable_affiliate
PATCH /program/disable_tour
PATCH /program/enable_affiliate
PATCH /program/enable_site
PATCH /program/enable_tour
PATCH /program/move-payout-change
PATCH /program/payout-change
PATCH /program/payout-change-tier
POST /program/new
POST /program/payout-change
POST /program/payout-change-tier
    Report
GET /report/affiliate-ratios
GET /report/hits
GET /report/hit-totals
GET /report/profitloss
GET /report/profit-loss
GET /report/fields
GET /report/focus
GET /report/focuses
GET /report/groups
GET /report/perspective
GET /report/perspectives
GET /report/report
GET /report/subscription
GET /report/surfer
GET /report/surferaction
GET /report/transactionpayouts
GET /report/transactions
GET /report/transaction
GET /report/report-widget
GET /report/widgets
GET /report/widget
GET /report/widget-info
GET /report/views
POST /report/focus
POST /report/group
POST /report/perspective
PATCH /report/focus
PATCH /report/focus-enabled
PATCH /report/focus-default
PATCH /report/focuses-reorder
PATCH /report/perspective
PATCH /report/perspective-group
PATCH /report/report-widget
PATCH /report/widget
DELETE /report/focus
    Reward
DELETE /reward/category
DELETE /reward/purchase
DELETE /reward/point
DELETE /reward/reward
GET /reward/categories
GET /reward/points
GET /reward/purchases
GET /reward/rewards
PATCH /reward/move-point
PATCH /reward/point
PATCH /reward/reward
PATCH /reward/ship-purchase
PATCH /reward/unship-purchase
POST /reward/category
POST /reward/point
POST /reward/reward
    Service
GET /service/check-functions
GET /service/condition
GET /service/countries
GET /service/country
GET /service/datetime
GET /service/languages
GET /service/periods
GET /service/ping
GET /service/project
GET /service/rule-condition-data
GET /service/rule-info
GET /service/stats-breakdowns
GET /service/timezone
GET /service/timestamp
POST /service/sendemail
    Site
GET /site/base-templates
GET /site/billers
GET /site/cookies
GET /site/coupon
GET /site/coupons
GET /site/coupon-revisions
GET /site/email-settings
GET /site/groups
GET /site/option
GET /site/options
GET /site/options-available
GET /site/option-fields
GET /site/option-rules
GET /site/option-rule
GET /site/option-type
GET /site/option-types
GET /site/programs
GET /site/redirect
GET /site/redirects
GET /site/redirect-rules
GET /site/redirect-rule
GET /site/site-list
GET /site/site
GET /site/site-notices
GET /site/site-partner
GET /site/site-partners
GET /site/site-type
GET /site/sites
GET /site/template
GET /site/templates
GET /site/template-sections
GET /site/template-sites
GET /site/tour
GET /site/tours
GET /site/tour-emails
GET /site/tour-notices
POST /site/coupon
POST /site/group
POST /site/option
POST /site/option-rule
POST /site/redirect
POST /site/redirect-rule
POST /site/site-partner
POST /site/site-tour
POST /site/copy-template
POST /site/tour
PATCH /site/cookie
PATCH /site/coupon
PATCH /site/duplicate-option
PATCH /site/email-settings
PATCH /site/group
PATCH /site/move
PATCH /site/option
PATCH /site/option-rule
PATCH /site/redirect
PATCH /site/redirect-rule
PATCH /site/reset-coupon
PATCH /site/restore-group
PATCH /site/restore-option
PATCH /site/restore-redirect
PATCH /site/restore-site
PATCH /site/restore-site-partner
PATCH /site/restore-tour
PATCH /site/site
PATCH /site/site-partner
PATCH /site/template
PATCH /site/tour
DELETE /site/cookie
DELETE /site/group
DELETE /site/option
DELETE /site/option-rule
DELETE /site/site
DELETE /site/site-partner
DELETE /site/redirect
DELETE /site/redirect-rule
DELETE /site/template
DELETE /site/tour
DELETE /site/tour-field
    Skin
DELETE /skin/skin
DELETE /skin/template
GET /skin/colors
GET /skin/export
GET /skin/skins
GET /skin/sections
GET /skin/templates
GET /skin/template
PATCH /skin/colors
PATCH /skin/flush
PATCH /skin/skin
PATCH /skin/template
POST /skin/copy-template
POST /skin/import
POST /skin/skin
POST /skin/template

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.

  1. 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.
  2. 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.
  3. You can use each site's link domain. To do this, you will need to enable the MEMBER_OPENID_DYNAMIC_DOMAIN config option.
  4. 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:
    • 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

TMM wiki on mod_auth_openidc
OpenID Connect Specs