Single Sign Specification using Oauth 1.0 HMAC

Introduction

The Brainfuse single sign-on service is a simple integration mechanism that allows Brainfuse clients who use their own authentication mechanism to sign their users directly into the Brainfuse Learning Suite. The integration is accomplished by embedding a dynamically-generated Integration URL into the client's LMS. Brainfuse generates the Integration URL(s) soon after receiving the client's setup specifications.

Table of Contents

Introduction
Authentication
1. Libraries
Integration URL
1. Definitions
  1. brainfuseServiceURI
2. URL Parameters:
  1. · lis_person_name_fname : The first name of the currently logged on user on the client system. Another name of the parameter can also be lis_person_name_given
Brainfuse side of the Integration

Authentication

The Brainfuse integration URL is typically secured by using OAUTH 1.0 Authentication. Brainfuse will provide the URL, consumer key and consumer secret to be used with OAuth 1.0 protocol.

Brainfuse utilize OAUTH 1.0 authentication mechanism to ensure the user arrived at the link at the partner's website. The OAUTH specification can be found on this url http://tools.ietf.org/html/rfc5849

The OAUTH 1.0 Guide can be found here on security http://hueniverse.com/oauth/guide/security/.

Libraries

OAuth 1.0 is a well tested and well implemented specification and there are many libraries that are already written in almost every language. Please click here for a list of libraries.

The signature generation method can be found here http://oauth.net/core/1.0/#signing_process

Integration URL

The Integration URL is generally dynamically generated at the time the user clicks on the Brainfuse link. The URL is composed of the landing page URL along with the brainfuseServiceURI(optional) and the url parameters.

http://landing.brainfuse.com/[brainfuseServiceURI/]index.asp?<url parameters>

Definitions

brainfuseServiceURI

brainfuseServiceURI is an optional parameter that identifies the service requested so that the user can be directly redirected to the service URL. If the serviceURI is omitted, the user will be redirected to the account home page. The possible values for the service URI can be one of the following:

• test: For accounts that opt into the Test Center service. This URI will direct the user to the Test Center service.

• helpnow: For accounts that opt into the HelpNow and JobNow services. This URI will direct the user to the HelpNow service homepage.

• jobnow: For accounts that opt into the JobNow and JobNow services. This URI will direct the user to the JobNow service homepage.

• writinglab: For accounts that opt into the Writing Lab services. This URI will direct the user to the writing lab services.

URL Parameters:

URL parameters provide the main communication method with the Brainfuse single sign-on system. The parameters in bold are required, others are optional but recommended to ensure a better user experience.

· user_id: (Required if using single sign-on system) The userId consists of up to 50 alpha-numeric characters. The userId must be unique for the currently logged in user on the client system of the branch or sub-entity to which the user belongs.

· lis_person_name_fname : The first name of the currently logged on user on the client system. Another name of the parameter can also be lis_person_name_given

· lis_person_name_lname: The last name of the currently logged on user on the client system. Another name for this parameter is lis_person_name_family

· lis_person_contact_email_primary: The email address of the currently logged on user on the client system.

The OAUTH specification requires the entity generating the URL to include few parameters in the request namely:

oauth_signature_method: currently the only supported method of authentication is HMAC-SHA1.

oauth_signature This is a HMAC-SHA1 digest of the request method in this case is get or post, the request url as well as the combination of all the parameters of the request URL. The signature is calculated using the method described here https://oauth.net/core/1.0/#sig_norm_param using the consumer key provided by Brainfuse.

More details on how the signature is calculated using a consumer key as well as a consumer secret provided by Brainfuse during the setup process.

oauth_consumer_key: the key provided by Brainfuse during the setup process if this is the method of authentication chosen.

oauth_nonce: a unique number to prevent replay attacks.

oauth_version: the default value for this is 1.0

Examples:

https://landing.brainfuse.com/index.asp?user_id=213123&lis_person_name_full=kcts+kcts&lis_person_name_fname=kcts&lti_message_type=basic-lti-launch-request&launch_presentation_document_target=window&resource_link_id=12345&oauth_callback=about%3Ablank&tool_consumer_instance_guid=9E22137B&lis_person_name_family=kcts&lis_person_contact_email_primary=&tool_consumer_instance_description=&launch_presentation_locale=en_US&launch_presentation_return_url=http%3A%2F%2Fbb.dev.trustforte.com%2Fwebapps%2Fbfus-BrainfuseSSO-BBLEARN%2Ftools.jsp%3Fcourse_id%3D_3_1%26id%3D32432&context_type=CourseSection&lis_person_name_given=kcts&lti_version=LTI-1p0&tool_consumer_instance_url=http%3A%2F%2Fbb.dev.trustforte.com&tool_consumer_instance_name=&lis_person_name_lname=kcts&resource_link_title=KCTS&oauth_consumer_key=9E22137B&oauth_signature_method=HMAC-SHA1&oauth_timestamp=1330638202&oauth_nonce=1344726845579987&oauth_version=1.0&oauth_signature=mBUQAFKLsvz3KKAvv8tREurz2jo%3D

This URL will register or login the user with the id 213123 into the main subdivision of the of the Demo client and then redirect the client to the service home page.

Brainfuse side of the Integration

Once the user clicks on the integration URL, the system will look up a user with the unique user id provided. If a user exists on the Brainfuse side, the system automatically logs the user into the Brainfuse system and brings them to the homepage or to the Brainfuse service specified in the URL.

If the userId was not found:

1. If the account is setup to prompt the user with the landing page, the system will prompt the user to either connect to an existing Brainfuse account or create a Brainfuse account with information not provided in the URL.

If the user clicks Save they will not be prompted again with this page. If the user clicks Skip and Proceed, they will be prompted again upon visiting the Integration URL. The user also has an option to connect their client userId to an existing Brainfuse username and password.

2. If the account setup is setup not to show a landing page and most accounts do, the user will be directed into our home page directly and they will see the Brainfuse Services launch page immediately.