Forumbee Single Sign- On

Transcription

1 Forumbee Single Sign- On What is Single Sign- On? In basic terms, Single Sign- On (SSO) allows users of your web site to log into your Forumbee community automatically, without needing to sign up and create another account. Implementation of SSO on your web site requires technical development skills. This article is intended to give the information needed for a developer to implement SSO to Forumbee from your web site. SSO Settings for Your Community To utilize the SSO API, SSO must be enabled for your account. To enable SSO, navigate to the Admin area Settings SSO, check Enable SSO then click Save. Secret key You will use this secret key later when you construct your URL to generate a SHA- 1 hex digest. You should keep your secret key private and never publish it FORUMBEE Single Sign- On (October 2015) 1

2 Handling direct community login/logout Remote login URL When you implement SSO you manage the login process for users into the community from your remote application. However it is still possible for a user to access your community directly, such as through a bookmark or a link in an notification. When a non- logged in user accesses your community directly, they will be prompted to login. To transfer control of the login to your remote application, specify a remote login URL. When prompted to login or sign up, the user will be redirected to the URL you specify. This should be a URL in your remote system that allows the user to login or sign up and then passes them back to your community via SSO. NOTE Your remote login URL replaces the standard Forumbee login page. If you still need to login through the Forumbee login page after you set your remote login URL, use the direct login page. Access the direct login page by appending /login/direct to your community domain URL: Remote log out URL When the user clicks log out in the community they will be sent to the URL you specify. Typically this would be a URL that also logs the user out of your remote system. The user key is passed (Base64 and URL encoded) on the Remote log out URL as a convenience for you to track the user FORUMBEE Single Sign- On (October 2015) 2

3 SSO Implementation Instructions From your remote application construct a unique URL login link for the user that includes a Base64- encoded JSON object containing user fields as shown below and a message digest ensuring the validity of the data. Use this URL to redirect the user to the community or to present a navigation link to the user. SSO login URL structure: }&data={ } During your implementation, use the SSO Developer Tool described below for documentation and testing. SSO Parameters Parameter Description Required Char length User (must be unique) Yes name Display name for the user Yes key Unique member key from your system It is good practice to use this if you need the ability to make updates to the user at a later time. avatar URL to the avatar picture for the user tagline Job title or tagline for the user role Access role type 0=normal (default), 1=moderator (See User Roles section below for details on roles) forums Comma separated list of private categories and/or groups to grant access Specify categories using the category link. Use the final portion of the category URL, in this example discussions : Specify groups using the group ID. Go to Users > Groups and select the group. Use code at the end of the URL, in this example f8mkt : To revoke access to a category or group, prefix the category or group ID with the! character. For example:!private-discussions 2015 FORUMBEE Single Sign- On (October 2015) 3

4 redirect Destination URL to send the user after successful login When not specified the user is sent to the community home. overwrite By default, only blank fields will be updated. Set to 1 to force an overwrite. (Applies to name, avatar and tagline.) Steps to create the login URL token 1. Construct a JSON object containing the following: i. Your Forumbee sub- domain ii. URI (/sso/1/login) iii. Date in milliseconds since 1970 UTC iv. SSO parameters from above. All parameters should be passed as quoted strings. Example: {"domain":"mysubdomain","uri":"/sso/1/login","date":" ", " ":"hank@forumbee.org","name":"hank Manning","role":"0","key":"100"} 2. Base64 encode the result of step Compute a SHA- 1 hex digest by combining your SSO secret key and the Base64 result from step Convert the digest from step 3 and the Base64 data from step 2 into URL Encoded parameters. 5. Construct the final URL with the digest and data from step 4 as query parameters. URL structure: }&data={ } If you are using domain aliasing, replace mysubdomain.forumbee.com with your domain alias. Example: }&data={ } 2015 FORUMBEE Single Sign- On (October 2015) 4

5 Using the SSO Developer Tool During your implementation, use the SSO Developer Tool for documentation and testing. Navigate to the Admin area Settings SSO, and click SSO Developer Tool. Create SSO URL 1. To create an actual working SSO URL, enter test data in the fields and click Create. 2. This returns the SSO login URL. Copy and paste this SSO link into a different browser to try it out. If you paste it in the current browser you are using, you will be logged out of your current session and logged in as the SSO user FORUMBEE Single Sign- On (October 2015) 5

6 3. Click the Show Steps button to reveal the steps to create the URL. Each step in the process is documented and output is shown. Validate SSO URL To test whether your SSO URLs are constructed properly, use the Validator. 1. In the SSO Developer Tool, click Validate SSO URL. 2. Paste the SSO URL and click Validate FORUMBEE Single Sign- On (October 2015) 6

7 3. The URL will be evaluated and a descriptive status will be returned. Source parameters will be deconstructed in JSON format. User account creation and updates When a user clicks through on your SSO link, Forumbee will look for the user in the community based on their SSO key or . If no matching user is found, SSO will create a new user with the SSO parameters provided. If a matching user is found, by default SSO will not update existing values for name, user- uploaded avatar, or tagline. If avatar or tagline were previously blank, or if the avatar was previously set by SSO, they will be updated by SSO. Example scenario 1: Janet previously joined the community, uploaded her avatar and created her tagline. Later she logs in with SSO. Her existing name, avatar and tagline will not be updated by SSO by default. This ensures that the edits she made to her profile are not lost when she logs in again with SSO. Example scenario 2: Ross previously joined the community, but did not upload an avatar or set a tagline. Later he logs in with an SSO link that includes values for the avatar and tagline parameters. His profile is updated with the avatar and tagline passed by SSO. Overwrite Parameter If the SSO overwrite parameter is set to 1, it will update the user name, avatar and tagline with the values provided. It is a best practice to only use this parameter in cases where you need to reset a member. If no avatar is provided, it will revert the user avatar to the original setting. The original setting is Gravatar or the Forumbee avatar if the user originally established their account with an avatar prior to SSO login. If no tagline is provided, it will reset the user s tagline to blank FORUMBEE Single Sign- On (October 2015) 7

8 User roles One of the following roles can be assigned to a user with the SSO role parameter. rmal: This is the member role and is the default if no role is specified. Permissions: Access all unrestricted categories (forums.) Access restricted categories (forums) when granted access via SSO link. Add topics (if allowed in forum settings.) Post replies to topics. Moderator: Permissions include all member capabilities plus: Monitor the community activity stream. Receive the community moderator report . Edit/remove postings. Manage the community moderation queue. View and invite members. Suspend or block members. Category Moderator Category moderators are members with additional abilities for categories to which they are assigned as a moderator: Monitor category activity stream. Receive the moderator report for that category. Edit/remove postings in that category. Manage the moderation queue for that category. To assign a category moderator through SSO, set role = 1 and list the categories in the forums parameter. The user will be assigned as a category moderator to all listed categories FORUMBEE Single Sign- On (October 2015) 8