Single Sign On API

From KickApps Documentation

The following SOAP SSO Integration Guide assumes that you have already created an affiliate account with KIT Cloud Social and you have enabled Single Sign On (SSO) for your community.

Log into the Affiliate Center and read through the rest of this document to learn how to configure SSO capabilities for your community.

Contents 1 What is SSO? 2 Why should I use SSO? 3 High Level Overview 4 How do I enable SSO in the KIT Cloud Social Affiliate Center? 5 Configuring SSO for your KIT Cloud Social community 6 SSO Frequently Asked Questions 6.1 When someone logs in what do I need to do? 6.2 When someone registers what do I need to do? 6.3 Is there a combined sign on and register call? 6.4 When a user logs out, what do I need to do? 6.5 When a user wants to change their email address or username, what do I need to do? 6.6 How do I create an edit profile page? 7 SSO Methods 8 SOAP and Web Services 9 Example: Mandatory Authentication Header XML 10 Appendix

What is SSO?

Single Sign On is a process and corresponding API, which can be used to leverage your existing authentication framework to log a user into your KIT Cloud Social community.

Why should I use SSO?

1. Your website already has an existing registration system.
2. You want to provide your users with a seamless browsing experience between your website and your KIT Cloud Social community.

High Level Overview

1. Check that you or your developers have access to the existing registration framework on your web server.
2. Enable SSO in the KIT Cloud Social Affiliate Center.
3. Modify your existing login, forgotten password and edit profile logic to communicate with the KIT Cloud Social SSO API.

This document is intended for those looking to understand the KIT Cloud Social SSO process and API. Any user looking to follow all of the steps through to implementation will need to have a strong technical understanding of their existing authentication / registration system and the access permissions to make changes to their system

How do I enable SSO in the KIT Cloud Social Affiliate Center?

Login to your KIT Cloud Social Affiliate Center as the Webmaster user and navigate to the Single Sign On configuration area. Once there perform the following actions (outlined in the screen capture below):

1. Click on the Configure Tab in the Affiliate Center
2. Click on the Advanced Tab
3. Click on the Single Sign-on option
4. You will now be presented with your single sign-on information, please print this, or copy it, as you will need it during development.

Configuring SSO for your KIT Cloud Social community

Scroll down to the bottom of the SSO configuration page and you'll be presented with the following options that need to set to enable single sign-on for your site (outlined in the screen capture below):

1. Click the "Activate SSO" radio button and optionally the "SSO Key to authenticate SOAP requests" radio button. The former will activate SSO for your KIT Cloud Social Community and the latter will protect your community with a key that will be needed for all incoming soap requests.
2. Make sure that your unique site ID is pre-populated in this field, if its not, simply hit the "Generate new key" link to create a new key.
3. This is the most important change that will be made in the affiliate center. There are three required fields: "Registration", "Sign-on" and "Sign-out destination" and all three fields need to point to the appropriate pages that are part of your existing authentication framework. If you also have existing "Forgotten password" and "Edit Member account" pages, feel free to add those URL's here as well.

SSO Frequently Asked Questions

This section contains a list of frequently asked questions related to SSO.

When someone logs in what do I need to do?

1. Modify your existing user login page so that it calls the Member Sign On SSO API method
2. Store the session token and transaction ID that are returned by the Member Sign On method.
3. Be sure to include the session token and transaction ID in all requested to pages in your KIT Cloud Social community that require authentication. More about this step can also be found in the Member Sign On documentation.
4. If you would like to avoid appending the st and tid to subsequent requests to KIT Cloud Social , you can transparently log a user into KIT Cloud Social by accessing any one of our hosted pages from a hidden iframe:
   1. Create a 1x1 pixel iframe in your custom login page (the page that talks to our SSO API). Be sure not to hide the iframe with CSS, this will prevent the iframe from correctly loading the KIT Cloud Social page.
   2. Have the iframe load any KIT Cloud Social Hosted page. We recommend using the blank page template, because it is very lightweight and loads extremely fast: http://affiliate.kickapps.com/service/openCustomPage.kickAction?as=XXXXXX Note: please be sure to replace XXXXXX with your communities ASID

When someone registers what do I need to do?

1. Modify your existing user registration page so that it calls the Member Register SSO API method.
2. This method will register the user with the username, password and additional information provided in the XML. Please see the Member Register information page for a full list of the user attributes that can be included in this method call.
3. If the method is successful, a session token and transaction ID are returned.
4. Store the session token and transaction ID.
5. Be sure to include the session token and transaction ID in all requested to pages in your KIT Cloud Social community that require authentication. More about this step can also be found in the Member Register documentation.
6. If you would like to avoid appending the td and tid to subsequent requests to KIT Cloud Social , you can transparently log a user into KIT Cloud Social by accessing any one of our hosted pages from a hidden iframe:
   1. Create a 1x1 pixel iframe in your custom register page (the page that talks to our SSO API). Be sure not to hide the iframe with CSS, this will prevent the iframe from correctly loading the KIT Cloud Social page.
   2. Have the iframe load any KIT Cloud Social Hosted page. We recommend using the blank page template, because it is very lightweight and loads extremely fast: http://affiliate.kickapps.com/service/openCustomPage.kickAction?as=XXXXXX *Note: please be sure to replace XXXXXX with your communities ASID

Is there a combined sign on and register call?

In certain circumstances you may want to combine the login process and the registration process. If you need this functionality, please refer to the "Combined Member Sign On and Register method.

When a user logs out, what do I need to do?

If your site displays a "logout" / "logoff" link once a users has logged in, the most efficient way to log them out of the KIT Cloud Social system is to forward the user to the KIT Cloud Social Member Sign Out URL.

A few things to note:

1. This is not an API call.
2. Make sure that a user is forwarded to this link after you've performed your own logout functions.

When a user wants to change their email address or username, what do I need to do?

Anytime a user changes their email address or username on your site, you will need to communicate these changes to KIT Cloud Social using one of the following SSO API methods:

1. Member Change Username
2. Member Change Email

How do I create an edit profile page?

Refer to the Member Profile Edit/Update SSO API documentation.

SSO Methods

In general, affiliate sites send KIT Cloud Social real-time information for the following information. Each method is sent to KIT Cloud Social using an XML request over SOAP. Example requests and the corresponding responses are included later in this document.

• Member Register
  Returns a response stating the request status. If successful, KIT Cloud Social will establish a session for the user.
• Combined Member Sign On and Register
  Returns a response stating the request status. If the user does not exist in the KIT Cloud Social database, the user is registered. If the user does exist, then no other action occurs. In either case, KIT Cloud Social will establish a session for the user.
• Member Sign On
  Returns a response stating the request status. If successful, KIT Cloud Social will establish a session for the user.
• Member Sign Out
  Returns a response stating the request status. If successful, KIT Cloud Social will establish a session for the user.
• Member Change Username
  Returns a response stating the request status. If successful, KIT Cloud Social will establish a session for the user.
• Member Change Email
  Returns a response stating the request status. If successful, KIT Cloud Social will establish a session for the user.
• Member Profile Edit/Update
  Return a response XML document stating the request status.

SOAP and Web Services

SSO uses web services, which support interoperable machine-to-machine interaction over a network. While web services encompass many different systems, the term usually refers to those services that use SOAP-formatted XML envelopes and have interfaces described by WSDL (Web Services Description Language). KIT Cloud Social SSO Web Service’s WSDL can be found at http://affiliate.kickapps.com/soap/KaSoapSvc?WSDL.

The configuration of web services enables systems to interact, regardless of the underlying technology platforms.

KIT Cloud Social SOAP-based SSO Web Service expose the methods that enable you to start a user session on behalf of the user, on KIT Cloud Social domain, as long as the technology you use provides a SOAP stack that implements all specifications that are part of web service’s architecture.

The SSO API Reference lists example requests and responses for all methods exposed by the KIT Cloud Social SSO Web Service. Unless otherwise specified all parameters in the sample request are required.

SOAP requests for SSO must include a mandatory authentication header token containing your credentials, as with the example below. The header token must be sent with every request header. Without this header authentication token, the request will fail.

Example: Mandatory Authentication Header XML

<AffiliateAuthenticationToken xmlns="http://schemas.kickapps.com/services/soap">
  <AffiliateUserName>affiliate_X</AffiliateUserName>
  <AffiliateUserEmail>affiliate_X@affiliate.com</AffiliateUserEmail>
</AffiliateAuthenticationToken>

Appendix

1. The KIT Cloud Social SSO service consumes data from your existing authentication system; it does not (in the default configuration) push data out to an existing authentication system.
2. Since the SOAP requests and responses in the KIT Cloud Social SSO Web Service follow current standards, any programming language with the appropriate library support can be used. Languages known to have this support include C++, C#, Java, PHP, Perl, Python and Ruby.
3. References:
   1. The WSDL (Web Services Description Language) can be found at the following URL: http://affiliate.kickapps.com/soap/KaSoapSvc?WSDL
   2. The XMLNS (XML Name Space) is specified as the following URL: http://schemas.kickapps.com/services/soap
   3. We provide standard plug-ins that work out of the box with our SSO service, please check the Category:SSO_Plug-Ins list before you decide to build your own.
   4. For code examples in PHP, ASP and J2EE, please refer to the SSO / SOAP documentation.
   5. For an in-depth guide to the SSO methods and parameters, please refer to the following Category:Single_Sign-On#SSO_Methods documentation.