Customize Your Expert Knowledge Sharing Platform with AnswerHub

Welcome to our documentation site! Here you can learn how to import/export your data and integrate with third party applications through our REST API.

Get Started

SAML Auth

Configuring the SAML Auth Plugin

To configure the SAML Auth plugin, do the following:

  1. Navigate to the Plugins > Manage Plugins in the admin panel.
  1. Select the Disabled Plugins tab.
  1. Select the SAML Auth plugin to display the dropdown.
  2. Click the ENABLE button.

📘

NOTE:

If you do not see the plugins section at the bottom of the left nav column in the administration section of the site, you will need to update the group membership for your user. Add your user to the Network Administrator group.

  1. Once you enable the SAML Auth plugin, navigate to Users and Groups > Settings > SAML Authentication.
  1. The SAML Authentication panel displays for configuration, with the IDP Config tab as the default.
  1. Enter the Login URL and Logout URL for your IDP.
  2. Select the Login signature type, Post or Redirect.
  3. Fill in or select/deselect the following fields as required:
  • IDP Login URL: Configure the login URL for the IDP server that AnswerHub will redirect the login request to. If the user is already logged in, then the IDP server will redirect back to the AnswerHub consumer URL wan an SAML assertion. If the user is not logged in, then the system will present them with a login form by the IDP server and then redirected back to AnswerHub. From a configuration XML, this would be the SingleSignOnService.
  • IDP Logout URL: The logout URL for the IDP server that AnswerHub needs to contact when the user logs out. If not specified, then the user gets redirected to the user logout page. From a configuration XML, this would be SingleLogoutService.
  • IDP Login Type: Controls whether AnswerHub makes a POST call or does a redirect to the IDP Login URL. This depends upon whether the IDP implements a POST or a redirect method. Some IDPs implement both. From a configuration XML, this would depend upon the bind-type for the SingleSignOnService.
  • IDP Name Identifier Format: The format for the NameID. Implementations could use an email address as the NameID. (This is frequently used.) If set to transient, then the NameID is random and will change from session to session. If set to unspecified, then the NameID is of an unspecified format the IDP and SP must agree upon.
  • Use NameID as Username: Configures AnswerHub to use the NameID as the username when creating new users. If you do not enable this setting, then AnswerHub will use the SAML attribute specified by the IDP Username Mapping as the username when creating the user. If you do not enalbe Allow Email As Username, then AnswerHub will use the portion of the NameID until the @ symbol. (assuming IDP, you set the name identifier to emailaddress). We do not recommended setting this if you set IDP Name Identifier Format to transient because the value changes from session to session. (This can also result in nonsensical user names that appear as random alphanumeric expressions).
  • Require NameID in Response: Configures whether AnswerHub will fail the login request if the IDP does not include NameID in the SAML assertion. This is a workaround for some IDPs that will fail if the auth request includes the nameIdPolicy.
  • Synch Profile Fields On Login: Controls whether AnswerHub will update the user's profile information if it detects any changes between Answerhub and information from the IDP when the user logs in.
  • Allow Email as Username: Controls whether AnswerHub will allow email addresses to be usernames. See Use NameID as Username.
  • Automatically Validate All Emails: Controls whether AnswerHub automatically marks imported email addresses as validated. If unchecked, after a creating a user in AnswerHub, the users will have to validate their email addresses, but this will not prevent users from signing in and participating.
  • Automatically Create New User Groups: Controls whether AnswerHub creates new groups corresponding to the attribute mapping for Groups in the SAML assertion.

📘

NOTE:

Be careful to check how many groups exist in the IDP before activating this to avoid an unwanted surge in group creation. New groups automatically inherit the permission settings of the standard “user” group. Once created, you can update permissions for new groups.

  • Enable Debug Mode: Controls whether AnswerHub will log and print debug information to the console for troubleshooting issues.

📘

NOTE:

This may be helpful to enable if you are experiencing trouble getting the site configured and need assistance from AnswerHub. Answerhub support team members can view the information in the server logs. However, you should uncheck this during normal operation to avoid log spam.

  • Use Certificate: Boolean setting (by default unchecked) for displaying under metadata endpoint (/saml/metadata.xml) <ds:X509Certificate> tag, the value from:
    • Cert (if checked)
    • Public key (if unchecked)
  • Sign Assertions and AuthN Requests: Boolean setting (by default unchecked) for displaying under metadata endpoint (/saml/metadata.xml) tag:
    • Flag values:
      • (if checked): WantAssertionsSigned="true" AuthnRequestsSigned="true"
      • (if unchecked): Don’t display the flag values
  1. Expand the SAML Attribute Mapping section and fill out the field names from the SAML response as required:
  • IDP Remote Id Attribute Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the remote identity. The value returned gets used as the authorization information if you enable Require NameID in Response.
  • IDP Username Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the username for the user.
  • IDP Email Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the email address for the user.
  • IDP First Name Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the first name for the user.
  • IDP Last Name Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the last name for the user.
  • IDP Location Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the location for the user.
  • IDP Company Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the company for the user.
  • IDP Profile Avatar Url Mapping: Controls which attribute in the SAML assertion AnswerHub uses to map to the URL for the profile avatar for the user.
  • IDP Real Name Mapping: Controls which attribute in the SAML assertion AnswerHub maps to the real name for the user.
  • IDP Groups: Comma-separated list of attributes AnswerHub uses to identify groups the user belongs to in the SAML assertion.
  • Store Groups in Separate Attribute Values: Indicates whether AnswerHub should look for groups in separate attributes in the SAML assertion
  • Extra Data Mappings: Used to map attributes in SAML assertions to custom properties for the user. Configured by settings SAML attribute then a comma then custom property. You can configure multiple properties on separate lines. For example:
    • [SAML Attribute],[User custom property]
    • [SAML Attribute],[User custom property]
  1. Select the Keys & Certificates tab.
  1. Fill out the field names as follows as required:
  • IDP Public Key: The public key for IDP server in x509 format
  • Sign SAML Login Requests: Controls whether AnswerHub signs SAML login requests
    • If you enable the sign SAML Login Requests, additional settings for public/private key pairs get exposed and you should complete them.
  • Public/Private Key Pair for Signing Requests: Upload PKCS12 file previously generated (for example using openssl command, here a hint: openssl req -x509 -sha256 -newkey rsa:2048 -keyout -out -days 365).
  • Key Pair Password: Key password value related to the PKCS12 file generation
  • Key Pair Alias: Key alias value related to the PKCS12 file generation
  1. Select the Advanced tab.
  1. Fill out the field names as follows as required:
  • AuthRequest: Issuer Value Override: By default AnswerHub uses the login URL as the Issuer (or EntityID) during the SAML login process. This option allows the customer to override this behavior and specify a custom value to use. A common use case would be for the customer to specify a URN.
  • AuthRequest: Relay State URL: AnswerHub (as SP) can send some value to the IDP together with the AuthnRequest and then get it back. It’s a URL parameter we use to tell the Identity Provider where it should send the response back. It’s an option which you can use to redirect the user to a different application after the authentication flow finishes.
  • AuthRequest: Consumer URL Override: Allows the customer to override the value used for the Consumer URL. This is the URL where the IDP returns the SAML assertion.
  • Bypass Signature Validation: Configure AnswerHub to not validate the signature of the SAML assertion. You can use this to temporarily allow logins to succeed if the IDP public key has changed.
  • Force Requested Authn Context: Configures AnswerHub to not include the Authn context as part of the request. (Not clear on why this would be useful. Perhaps another workaround for some IDPs).
  • Don't Send SPNameQualifier in NamedIdPolicy: Controls whether AnswerHub sets the SPNameQualifier to the issuer in the NamedIdPolicy attached to the SAML auth request. (Not clear why this would be useful. Perhaps another workaround).
  • Perform Role Attribute Check: When enabled AnswerHub will use Regex to Verify Role as a pattern to match against the value returned by Attribute to Match for Role to validate the user has the appropriate role to login to AnswerHub. This is useful for customers to control which users in the IDP have access to AnswerHub.
  • Allow Access If No Role Attribute is Found: When you enable Perform Role Attribute Check, this option controls whether AnswerHub allows the user to login if the SAML assertion does not have the attribute specified by Attribute to Match for Role.
  • Attribute to Match for Role: The attribute in the SAML assertion AnswerHub uses in conjunction with Regex to Verify Role.
  • Regex to Verify Role: A regular expression AnswerHub uses to validate the user has a specific role that the customer wants to allow access to AnswerHub.
  • Redirect To Remote Site To Grant Access: Configures AnswerHub to redirect requests to a remote URL specified by Access Grant URL if SAML validation fails.
  • Access Grant URL: The URL AnswerHub will redirect to if SAML validation fails and you enable Redirect To Remote Site To Grant Access.
  • Use email to match local users against IDP users: Configures AnswerHub to use the email to lookup the user if it cannot find the user before creating a new user.
  • Deflate the Request: Typically checked in most configs. Option to have SAML text message deflated (without header and checksum) and base64 encode before sending it as a request

Updated about a year ago



SAML Auth


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.