Category:Single Sign On

From KickApps API Reference

The following assumes that you have already created an affiliate account with KickApps and you have enabled Single Sign On (SSO) for your community.

If this is not the case please sign up for an affiliate account at http://www.kickapps.com/. Then, log in to 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? 1.1 Why should I use SSO? 1.2 High Level Overview 1.3 Audience 2 How do I enable SSO in the KickApps Affiliate Center? 2.1 Activate SSO Screenshot 3 Configuring SSO for your KickApps community 3.1 Configure SSO Screenshot 4 SSO Frequently Asked Questions 4.1 When someone logs in what do I need to do? 4.2 When someone registers what do I need to do? 4.3 Is there a combined sign on and register call? 4.4 When a user logs out, what do I need to do? 4.5 When a user wants to change their email address or username, what do I need to do? 4.6 How do I create an edit profile page? 5 SSO Methods 6 SOAP and Web Services 7 Example: Mandatory Authentication Header XML 8 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 KickApps community.

Why should I use SSO?

1. Your website already has an existing registration system.
2. You want to provide your users a seamless browsing experience between your website and your you KickApps 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 KickApps Affiliate Center.
3. Modify your existing login, forgotten password and edit profile logic to communicate with the KickApps SSO API.

Audience

This document is intended for those looking to understand the KickApps 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 KickApps Affiliate Center?

Login to your KickApps 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.

Activate SSO Screenshot

Configuring SSO for your KickApps 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 KickApps Community and the later 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.

Configure SSO Screenshot

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 KickApps 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 td and tid to subsequent requests to KickApps, you can transparently log a user into KickApps 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 KickApps page.
   2. Have the iframe load any KickApps 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 KickApps 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 KickApps, you can transparently log a user into KickApps 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 KickApps page.
   2. Have the iframe load any KickApps 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 KickApps system is to forward the user to the KickApps 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 KickApps 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 KickApps real-time information for the following information. Each method is sent to KickApps 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, KickApps 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 KickApps database, the user is registered. If the user does exist, then no other action occurs. In either case, KickApps will establish a session for the user.
• Member Sign On
  Returns a response stating the request status. If successful, KickApps will establish a session for the user.
• Member Sign Out
  Returns a response stating the request status. If successful, KickApps will establish a session for the user.
• Member Change Username
  Returns a response stating the request status. If successful, KickApps will establish a session for the user.
• Member Change Email
  Returns a response stating the request status. If successful, KickApps 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). KickApps 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.

KickApps SOAP-based SSO Web Service expose the methods that enable you to start a user session on behalf of the user, on KickApps 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 KickApps 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 KickApps 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 KickApps 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.

This page was last modified on 26 February 2010, at 03:13. - This page has been accessed 4,500 times. -

About KickApps API Reference