Answerbase Developer Single Sign-On Documentation

Single Sign-On Documentation

Use single sign-on authentication to integrate your current registration and login with your Answerbase site, allowing you to utilize your own login and registration seamlessly with your Answerbase platform. You can also choose to manage user public profiles, their account dashboards, as well as all Q&A settings. This documentation is available to assist you and managing a Single Sign-On implementation and profile management with your site.

Introduction

This document details how to achieve a Single Sign-On (SSO) implementation with the Answerbase application.

Enabling the Single Sign-On feature within your Answerbase site will mean that your users will only have to sign in once via the current login utilized on your site to establish their credentials.

Additionally, your users will not have to explicitly register on the Answerbase platform. All user management will be handled via your own application and registration. This will facilitate access for your users and remove the inconvenience of having users re-enter their credentials as they move from your website to your Q&A site.

The Answerbase SSO implementation is based on the OAuth2 standard and the integration provided will allow you to specify various “integration points”, in the form of URLs, which will be called when a user attempts to take an action on the site that requires login or view a user profile. This flexibility will mean that user data is specifically controlled by you and your current website. A user will not be able to accomplish actions that require registration or login on the Q&A site without first being registered and logged into your application. Together with the API that is available, a truly flexible and bespoke experience will be available for your users.

Please note that your current registration and login process must support unique usernames and unique user id's for each of your users. Those usernames will act as the user’s display names through the Answerbase site and will be used as part of the user's profile URL. The user id's will be used by the system to identify each user.

Terms

The following terms are used within the document:

SSO

Abbreviation for the term Single Sign-On.

Answerbase / Answerbase site

This is the Q&A community site that has been created by you within the Answerbase system.

Authorization Server

This is your application or server that will handle the authorization for user accounts.

SSO Cookie

This refers to the cookie that is shared between the authenticating site and the Answerbase site, for the purposes of communicating the login state of the user between sites.

Process Flow

An overview of the full process can be seen in the following diagram:

Every time a user requests a private page or takes an action that requires authentication, the user is redirected to the authenticating site login page (the Authorization Endpoint). Once the user is successfully authenticated, the user is redirected back to the Answerbase site and an access token is returned. The Answerbase site will use this access token to request user data via the RESTful service and the response sent in JSON format. If the user id does not exist in the Answerbase site a new record is created. The user gains access to the Answerbase site without having to re-enter their credentials. If the user id is represented, it will recognize the user on the Answerbase site.

IMPORTANT NOTE: Since the user id is the identifier of the user, if any information is different than the information that we already have saved for a particular user id, that user’s information will simply be updated to represent the new values provided by your site including username, user’s email address, and any other profile information associated with that user.

Implementation Requirements

The following sections detail the specific implementation requirements in order to use the Single Sign-On service. Please note that the URLs included here are examples and will be different for the actual implementation.

User IDs

In order to implement the SSO solution, your site must provide a User ID for each user that will be used to match the users on the Answerbase site. This ID must be unique for each user.

Usernames

Your site must provide a username for each user that will be used as their display name on the Answerbase site and will be used within the user's profile URL in the case if Answerbase is managing the user’s public profiles. This username must be unique for each user.

Emails

In order to implement the SSO solution, your site must collect an email address for each user and that email address cannot match any other unique user’s email address on the system. If there is more than one user with the same email address, this will cause issues on the Answerbase site.

Request Monitoring

It is recommended that the authenticating site is protected to only accept requests from authorized sites. This is to prevent the unapproved access of user data.

SSO Cookie

In order for your Q&A platform to successfully recognize when one of your users has logged in or out of your main site, your website should drop a newly created cookie. Your website should create this cookie when a user logs in and delete it when he logs out. If the cookie does not exist, Answerbase will know the user has logged out from your website and if the cookie does exist then Answerbase will authenticate that user upon their arrival the Q&A platform and recognize them as being logged in.

It is important to explicitly set the domain of the cookie so that it is available across subdomains. Please note the leading “.”.

Name	The name of the cookie as defined in the SSO Settings page within the Administration section of the site.
Value	The Session ID of the user.
Domain	.yoursite.com

Expiry

The value for expiry will be determined by the authenticating site. The Answerbase application has no specific requirement as to the length of time that the cookie is available for.

Resource Server URL

In order for the Answerbase application to retrieve information relating to the user and thereby allow the user access to the site, it is expected that you provide a “RESTful” service. Only one method (GET) is required which will return the details of the user in JSON format. The URL for this service should be entered in the “Resource Server URL” field.

JSON Response

The REST service is required to return the response in JSON format. The following data is required:

Id
Email
Username

An example JSON message is as follows:

{

"Id":"265495",

"Email":"john.smith@test.com",

"Username":"jsmith"

}

As the name of each property may be different for each authorization server, the JSON property names must be informed as part of the SSO settings (described in the next section).

User Groups

If you have the groups feature enabled in Answerbase and you want to identify the groups that the user is associated to in the SSO process, you can do that by specifying another parameter in the JSON Response from the resource server. This parameter value has a special format as you need to supply several pieces of information about the groups.

In order to provide the group(s) that the user is part of, you need to pass that information in the following way:

{
...

"group":"{groupid=x1;groupname=x2};{groupid=y1;groupname=y2};"

...
}

You can specify as many groups as you'd like. The "groupid" is a unique identifier that you define and it determines if it is a new or existing group in Answerbase. If the group doesn't exist, it will be created in the process. If no groups are specified, the user will be disassociated from any group and if the group association changes in any way, the user will be updated accordingly (i.e. removed from one group and added to another). The group names for existing groups will be updated if they're different from the current information stored in Answerbase.

SSO Administration Settings

In order to accomplish SSO, you must go into the administration site under “Integration” in the main navigation. You will then be presented with a subnavigation that will have the option for “Single Sign-On”. Click on that page to change the settings so you can accomplish SSO for your site.

After you’ve accomplished all of the implementation requirements and have them available to test against, adjust the first Single Sign-On setting to enable Single Sign-On which lets the system know that you’ll be using your own login and registration.

Settings Page Screenshot

End Settings Page Screenshot

As described on the SSO settings page, it’s important to note that by choosing to enable SSO, the option for users to manage their username, email and password on the Answerbase side will be hidden as these items will need to be managed on your site.

After you’ve adjusted the setting to use your own login and registration, you must some additional settings. More detailed descriptions and requirements for these settings are below.

Field	Required	Length	Description
Client ID	Y	20	String that uniquely identifies the Answerbase application to the authorization server.
Client Secret	Y	200	A string that, along with the Client ID, is used to authenticate the Answerbase application.
Authorization Endpoint	Y	255	URL of the login page of the authorization server
Token Endpoint	Y	255	URL to obtain the access token
Resource Server URL	Y	255	URL of the GET method to access user’s data (JSON)
Scope	N	255	Comma-separated list of scope values as required by the authorization server
Method of Sending Tokens	Y		Method of sending bearer access tokens in resource requests as required by the resource server. Possible values are: “Authorization Header” and “Query String Parameter”.
Cookie Name	N	20	The shared cookie that helps seamlessly integrate your main site and the Answerbase site by communicating the login state of each user.
User Id Property	Y	50	JSON property name for User's Identity
Username Property	Y	50	JSON property name for Username
User Email Property	Y	50	JSON property name for User's Email
User Display Name Property	Y	50	JSON property name for User's Display Name
User Avatar URL Property	N	50	JSON property name for the User’s Avatar URL
User First Name Property	N	50	JSON property name for User's First Name
User Last Name Property	N	50	JSON property name for User's Last Name
User Organization Property	N	50	JSON property name for the User’s Organization Name

Authorization Endpoint

The user will be redirected to this URL when the user is not currently logged in and tries to complete an action on the Q&A environment that requires the user to be logged in or registered within the Answerbase Q&A site. These actions will include asking a question, answering a question, voting on answers, watching questions, etc. This page typically includes the ability for current users to login, along with an option or link to register for new users.

As part of the OAuth2 specification, a “redirect_uri” parameter will be passed on the querystring which will contain the URL the user should be redirected to after they login successfully as well as important parameters that include information about the action the user was trying to take before being asked to login. This “redirect_uri” parameter will allow the authenticating site to redirect the user back to the process that the user was trying to accomplish, and lets the Answerbase site complete that desired action the user was trying to take.

Example of a “redirect_uri” is here:

http://answers.cubicminds.com/Account/ExternalLoginCallback?state= action%3Danswervote%26id%3D23431

The above example is the URL a user will go to when they’re voting on an answer which requires login. After the user goes to your site and logs in, you will send them back to this URL which will register their vote for that answer. It is critical that you send the user back to this URL after login or registration on your site so their desired action is completed. If the login is being performed through a popup, as in the case, for example, with the Full Featured Widget, the URL redirect path will be (...)/Account/ExternalLoginPopupCallback.

IMPORTANT: Please note that the Authorization Endpoint page on the authenticating site should include the option for current users to login but also a link to register for users who are not currently registered on your system (the page sometimes also contains both functionalities with a simple form for users to register as well as the option to login, this depends on your preferences). The “redirect_uri” parameter must be passed through the registration or login process and the user must be redirected back to that URL after filling out the authenticating site’s registration or login form. This will allow the user to become a newly registered member on the authenticating site or successfully login, and also allow them to successfully complete the action they were looking to take on the Answebase site that initiated the registration or login of the user.

Login, Registration and Logout Links

The Answerbase site displays login, registration and logout links within the main navigation areas of the site by default. With single sign-on authentication you have the ability to hide these links or continue displaying them and identify the relevant URLs on your site that these links should point to.

Hiding the Login, Registration, and Logout Links

If you would like to hide the login, registration, and logout links on the Answerbase site simply make sure the option to hide these links on the SSO settings page is set accordingly and the default links will no longer appear for users to click on. In this case, it is highly recommended that you add your own login, registration, and logout links within the header navigation of the Answerbase site or within one of the content areas so users are still able to achieve these objectives.

Settings Page Screenshot

End Settings Page Screenshot

If you choose to hide these links, the links that will be hidden on the public Q&A site are outlined in red in the below screenshot.

Q&A Page Screenshot

End Q&A Page Screenshot

Displaying the Login, Registration, and Logout Links

If you’d like to continue to display those links with Single Sign-On, you can do that by going to the Sign-On settings area, scroll down to the section entitled “Login, Registration, and Logout Links”, and then make sure the option to continue displaying those links is selected.

Settings Page Screenshot

End Settings Page Screenshot

Once you’ve selected the option to continue displaying the default Q&A login, provide the relevant URLs of the authenticating site for each of these options, and when users click on those links they will be brought to those pages.

Login URL

The Login URL will take the user to your login page, where existing users are able to login to your site using their existing credentials.

Register URL

The Register URL should represent your existing registration page, allowing users to create a new account on your system where they can identify their username and any other user data.

Logout URL

The logout URL should represent the page on your system that users will go to, which will officially log the user off. If an SSO cookie is defined, the page should also delete this cookie so the Answerbase site can recognize that the user is no longer logged in.

Profile Management

You can choose to have Answerbase manage the user’s public profile, their ability to manage Q&A settings, as well as their logged-in account dashboard if you’d like or you can also manage those on your end. In order to manage those elements on your side, you’ll need to select the option to manage your own profiles on the Single Sign-On settings page, provide us with the URL format for your public user profile pages, as well as integrate Q&A information and settings in your current public user profile and the account dashboard that you provide to users after they’re logged into your side.

We provide Advanced APIs which allow you to display and manage Q&A related content and settings on your pages. Please read the “Profile Management API Guide” at the end of this section which defines the specific methods used to manage the information and settings referenced in this section.

The Advanced API Documentation can be found at the following URL:

http://answerbase.com/API/Api-documentation.html

We’ve listed the common Q&A related elements typically included in each of these areas below, which will help promote healthy activity on the Q&A site.

Changing the Profile Management Setting

When you are viewing the Single Sign-On settings page within the administration area, you can scroll down and see the option to manage the user profiles on your end. In order to change this setting, you must select the option to manage profiles on your site. IMPORTANT NOTE: By choosing to manage these items on your end, all links on the Q&A site to navigate to and manage these items will be hidden on the site and you must provide your own navigation to manage those items.

Settings Page Screenshot

End Settings Page Screenshot

As mentioned above, if you choose to manage this on your end, the links highlighted in the below screenshot will be hidden on the public Q&A site and you’ll have to manage those pages and settings through your own navigation/options.

Q&A Page Screenshot

End Q&A Page Screenshot

Public Profile Page

You’ll need to be currently providing a public profile page for each of your users, where others within the community are able to view the basic information about each registered user. When looking to manage the Q&A related content and functionality on your side, you’ll need to pull each user’s Q&A activity to their public profile via API so other users can recognize this activity user and also give the ability for members to ask a user a direct question on the Q&A platform. Details on how to accomplish this are listed below.

Public User Profile URL Format

When you select to manage the user’s profiles on your end, you’ll be required to give us the format for the URLs of your public profile pages for users on the Single Sign-On settings page within your administration area. The URLs of your user’s profile pages must contain the username of the user, and will be reference on the Q&A site so users can click to see other member’s profile pages.

Settings Page Screenshot

End Settings Page Screenshot

When you provide your URL format in the administration area, the URL should contain the token [USERNAME] so we know where to insert the user’s username. When creating the link for each user on the site, that token will be replaced with the user’s real username which needs to represent the functioning link on your site to view each user’s profile page. A couple samples of what this URL format may look like is as follows:

SAMPLE 1
http://authentication.clientsite.com/UserProfile.aspx?username=[USERNAME]

SAMPLE 2
http://www.yoursite.com/users/[USERNAME]

The field in the administration site will accept any URL format, as long as the [USERNAME] token is present.

User Q&A Information and Lists

There is Q&A specific information and lists for each user that should be pulled via API to display on each user’s public profile page (See API Guide at the end of this section). You can use our Advanced API to pull this user information from the Answerbase database to your site for display on a user’s profile.

Q&A information we recommend displaying on the public profile is as follows:

Total Points Earned
Overall Ranking
Number of Questions Answered
Number of Questions Asked
User’s Areas of Expertise
List of Best Answers Submitted by User
List of All Answers Submitted by User
List of Questions Asked by User

Take a look at the screenshot below which shows you what the current public user profile page looks like by default on an Answerbase Q&A site, so you can have an idea of what information can be managed and displayed.

User’s Public Profile Page Screenshot

End User’s Public Profile Page Screenshot

Q&A “Direct Question” Functionality

Along with Q&A related information as listed above, you also have the ability to let users ask other members of the community a direct question. These questions will send an email specifically to that member notifying them that their expertise was being requested, and it will also be posted for the general community to contribute to as well just like any other question posted.

The “Ask a Question” button will simply be a button or link that you make available on each user’s profile page which links to a URL to the Q&A site’s “Ask a Question” page. Within the link, you’ll add the user’s id as a parameter so we know who to direct the question to. The format of the link is listed below, and where it has [USERID] is where you should insert the user’s unique id.

http://YourAnswerbaseSite.com/Question/Ask?directQuestionExternalUserId=[USERID]

This option should only display if the user has turned this feature on in their user settings area. You can see how this option to ask a user a direct question is currently displayed on a user’s public profile on the below screenshot, when Answerbase is managing that profile. The button to ask the direct question is highlighted with a red border.

-------------------------------------------------------------------------------------------------------
- User’s Public Profile Page Screenshot

End User’s Public Profile Page Screenshot
--------------------------------------------------------------------------------------------------------

Account Dashboard and Settings

When users log into your current site, sites typically have a dashboard where the logged-in users go to view any user-focused information, edit their profile image and information, as well as have the ability to navigate to edit their account settings. In this area, you’ll want to add Q&A related information and settings so a user can keep track of their specific Q&A activity and also adjust their Q&A related settings. The Q&A related items usually displayed on a user’s logged-in account dashboard, as well as the settings they are able to manipulate are listed below. You’re able to add these to your own dashboard by using our Advanced API.

User’s Q&A Information and Lists

Total Points Earned by the User
Overall Ranking of the User
User’s Current Category Subscriptions (with ability to add/remove)
List of Questions the User is Watching (with ability to add/remove)
List of Questions Asked Directly to the User
List of Questions Asked by User
List of Questions Answered by User
Point Summary

Take a look at the screenshot below which shows you what the current logged-in user profile page looks like by default on an Answerbase Q&A site. This will give out an idea of what information can be managed and displayed. Also note the “Your Account” links that are available, which reference the different pages so users are able to manage their Q&A-related settings.

--------------------------------------------------------------------------------------------------------
User’s Manage Account Page Screenshot

End User’s Manage Account Page Screenshot
--------------------------------------------------------------------------------------------------------

User’s Q&A Settings

Direct Question Activation Setting
Email Notifications

Note that it’s common that these settings and lists are displayed on different pages, and sites will create navigation to easily access any pages and setting related to the Q&A content.

Profile Management API Guide

This section specifies the API methods, referenced within the Answerbase Advanced API Documentation, which are relevant for sites managing public user profiles and the ability for users to manage their account and settings.
The advanced API Documentation can be found at the following URL:

http://answerbase.com/API/Api-documentation.html

Please review the API methods that are used below, with detailed descriptions of what they’re used for when managing profiles and accounts on your site. Managing and displaying these elements on your current user profile pages and when a user is managing their account is recommended to effectively promote and reward Q&A activity.

Method Title	How Method Is Used
GET User	Pull all of the basic information for each user including total points earned through Q&A activity, overall rank, as well as points earned and rank for specific categories. This information is typically displayed on both the public profile for visitors to recognize a person’s expertise, as well as a user’s logged in “Manage Account” area so they can keep track of their rankings and point totals.
GET Questions Asked by User	This list can be pulled to display on both the public user profile so other users can see a user’s Q&A activity, as well as their logged in “Manage Account” area on your site so they have easy access to the questions they’ve asked.
GET Questions Answered By Users	This list can be pulled to display on both the public user profile so other users can see a user’s Q&A activity, as well as their logged in “Manage Account” area on your site so they have easy access to the questions they’ve answered.
GET Questions with Highest Rated Answers By User	This list can be pulled to display on the public user profile for each user, so other users can see the high quality answers submitted by that particular user which highlights their expertise.
GET Questions Followed by User	This list can be displayed within each user’s “Manage Account” dashboard on your site, so they can have easy access to the questions they’ve chosen to follow on the Q&A system.
GET Recently Viewed Questions by User	This can be displayed within each users “Manage Account” dashboard on your site, so they can have easy access to questions they’ve recently viewed and may be interested in.
Add User Category Subscriptions	This method is used when users are viewing the categories that they’ve chosen to subscribe to (subscriptions send an email to users when a question is asked in that specific category) and you can add a link to let them add a category to their subscription list.
Remove User Category Subscriptions	This method is used when users are viewing the categories that they’ve chosen to subscribe to (subscriptions send an email to users when a question is asked in that specific category) and you can add a link to let them remove a category from their subscription list.
Remove Followed Question	This method can be used when displaying the list of questions that the user is watching in their “Manage Account” dashboard on your site, you can also add a link that allows them to easily stop watching that question and remove that question from their list.
Update User Data	You use this to make sure when a user updates their data on your end, the same user data is available on the Q&A database. This information can be used in displays throughout the Q&A system and on Q&A related widgets.
Update Email Settings	This method allows you to publish a user’s Q&A related email settings in their “Manage Account” area on your site, as well as update those settings if a user chooses to update them.
Get User Category Subscriptions	This method allows you to pull a list of categories that a user is currently subscribed to
Get Questions Asked Directly to User	This method allows you to pull a list of questions that have been asked directly to a specific user, so you can display this list to them on their account dashboard.
Get User Point Summary	This method allows you to pull each user’s point summary, displaying what actions on the Q&A system each user has received points for.