Difference between revisions of "Pass Through Authentication"

From AgileApps Support Wiki
imported>Aeric
imported>Aeric
 
(65 intermediate revisions by the same user not shown)
Line 1: Line 1:
Pass Through Authentication (PTA) lets a user go straight to the platform from an organization's web page or application, without having to log in again.
Pass Through Authentication (PTA) lets a user go straight to the platform from an organization's web page or application, without having to log in again.


===How it Works===
===Working with pass through authentication===


As part of an enterprise application, the user would like to visit a page hosted on the platform, without having to log in to the platform to see it. To accomplish that goal, the application sends a small SOAP message to the platform, in an HTTP request.  
After logging on to an enterprise application, you might want to visit a page hosted on the platform without logging on to that platform. A single log on to the enterprise application gives you access to all the pages hosted on the platform. The application sends a SOAP message to the platform in an HTTP request. That SOAP message contains the information needed to log on to the platform. The data in it is passed to an authentication server which sends back a message saying whether the authentication has succeeded or failed. The user is directed to the appropriate page, as displayed in the following diagram:
:[[File:SSO-PTA.png]]


That message contains the information needed to log into the platform. Data in it is passed to an authentication server, which sends back a message saying that authentication has succeeded or failed, after which the user is directed to the appropriate page.
Here is an explanation of the steps:
 
The URL of the Authentication Server and the <!--default -->URLs of the pages to visit in the event of success or failure are configured in the platform's [[Single Sign-On]] Settings.<!-- The destination URLs can be overridden dynamically, by the application.-->
{{#if: | UNCOMMENT THE NOTES HERE AND BELOW WHEN OVERRIDES ARE IMPLEMENTED.}}
 
====Actions====
:{| border="1" cellpadding="5" cellspacing="0"
:{| border="1" cellpadding="5" cellspacing="0"
!
!
!User...
!User
!Platform...
!Your organization's web application
!Your Organization's Web Service...
!Platform
!Authentication server
|-
|-
| 1. || || || Provides a web page or application
| 1. || Log on to a web page or application provided of your organization || || ||
|-
|-
| 2. || Visits the page or application  || ||  
| 2. || Click a link that directs to a platform page || || ||
|-
|-
| 3. || Clicks a link to go to a platform page || ||
| 3. || || Pass data to the platform's PTA service in the SOAP payload
* Session ID (optional, but desirable)
* Login ID
|| ||
|-
|-
| 4. || || || Passes data to the platform's PTA service in the SOAP payload
| 4. ||  
|-
|
| 5. ||  
|
|
* Receives data in the SOAP payload:
* Receive data in the SOAP payload:
:* Session ID (optional, but desirable)
* Pass data to the Authentication server
:* Login ID
* Passes data to the Authentication server
|
|
|-
|-
| 6. || || Receives a success- or failure-report from the Authentication Server ||
| 5. || || || ||
* Authenticate the user
* Send back a success-report or failure-report
|-
|-
| 7. || || Redirects the user to the appropriate page. ||
| 6. || || || Redirect the user to the appropriate page. ||
|}
|}


===Enabling Pass Through Authentication===
===Enabling Pass Through Authentication===
#Click '''Settings > Administration > Single Sign-On'''
The URL of the Authentication Server and the URLs of the pages to visit in the event of success or failure are configured in the platform's [[Single Sign-On]] Settings:
#Click the '''[Edit]''' button
 
#For ''Single Sign-On Settings'', choose '''Pass Through Authentication'''
#Click '''[[File:GearIcon.png]] > Administration > Account Management > Single Sign-On Settings'''.
#Fill in the Pass Through Authentication Settings:
#Click the '''[Edit]''' button.
#:;Third party Authentication Service URL: Location of the authentication service. The platform uses this URL to authenticate the USER, passing the appropriate pay load in the HTTP request.
#Choose '''Pass Through Authentication''' from the ''Single Sign-On Using'' drop-down list. Selecting Pass Through Authentication automatically displays the '''Platform Authentication Service URL''' field below the drop-down list.
#:;Success page URL: The page the platform sends the user to when authentication succeeds.<br>If not specified, the default destination is the platform's home page.<!-- (Can be overridden dynamically in the HTTP request.) -->
#Specify the location of the authentication service in the '''Third party Authentication Service URL''' field. The platform uses this URL to authenticate the USER and pass the appropriate pay load in the HTTP request.
#:;Error page URL: The page the platform sends the user to when authentication fails.<br>If not specified, the default destination is the platform’s Login-error page.<!-- (Can be overridden dynamically in the HTTP request.) -->
#Enter the URL of the page where you want to go when the authentication succeeds in the “Success page URL” field.
#: If the URL is not specified then the platform will take you to the home page.
#Enter the URL of the page where you want to go when the authentication fails in the “Error page URL” field.
#: If the URL is not specified then the platform will take you to the login page.
#: This field can be overridden dynamically by the Authentication Server
#Click '''[Save]'''
#Click '''[Save]'''


===Message Formats===
===Message Formats===


====Initial Message Sent to the Platform====
==== Posting a Form to the Platform ====
This message format needs to be delivered to the platform by the Application or web page.
The following is an example of a form which the application or web page uses to make an HTTP ''POST'' to the platform. The user is then seamlessly redirected to the success or failure page depending on the authentication.
 
:<syntaxhighlight lang="xml" enclose="div">
<form id='testForm'
  action='https://{{domain}}/networking/passThroughAuth'
  METHOD="POST" enctype="application/x-www-form-urlencoded"
>
  <input type="hidden" name="loginID" value="jondoe@test.com">
  <input type="hidden" name="sessionID" value="adasd3qw4q4weasdasd">
</form>
</syntaxhighlight>
 
Where,
:;loginID: The user's login name on the platform, typically in the form of an email address.
:;sessionID:The session ID of the user on the organization's website. This field is optional. It is passed on to the authentication service, so the authentication service can make use of it.
 
When the platform receives POSTed form data, it passes the data to the Authentication Service using content type <tt>application/x-www-form-urlencoded</tt>, in a request. See the example below:
:;Method:POST
:;URI:Configured in the [[Single Sign-On]] Settings
:;Content-Type:<tt>application/x-www-form-urlencoded</tt>
:;Payload:A [[URL Encoding|URL Encoded]] version of a data string that looks like this:
::<syntaxhighlight lang="text" enclose="div">
loginID=jondoe@test.com&sessionID=adasd3qw4q4weasdasd
</syntaxhighlight>
 
: The Authentication Service reads the identification parameters from the request as it is in this Java code, for example:
::<syntaxhighlight lang="java" enclose="div">
String loginId  = (String)request.getParameter("loginID");
String sessionId = (String)request.getParameter("sessionID");
</syntaxhighlight>
 
Where '''request''' is the object containing the HTTP request (for example, in an <tt>HttpServlet</tt> instance).
 
==== Sending a SOAP Request to the Platform ====
This message format can be delivered to the platform by an application or web page.


;Method:POST  
;Method:POST  
;URI:<tt><nowiki>https://{domain}/networking/passThroughAuth</nowiki></tt>  
;URI:<tt>{{platformURL}}/passThroughAuth</tt>  
:<syntaxhighlight lang="xml" enclose="div">
:<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
    <soapenv:Body>
<LJAuthenticate xmlns="urn:authentication.soap.ws.longjump.com">
        <LJAuthenticate xmlns="urn:authentication.soap.ws.longjump.com">
<sessionID>...</sessionID>
            <sessionID>...</sessionID>
<loginID>...</loginID>
            <loginID>...</loginID>
</LJAuthenticate>
        </LJAuthenticate>
</soapenv:Body>
    </soapenv:Body>
</soapenv:Envelope>
</soapenv:Envelope>
</syntaxhighlight>
</syntaxhighlight>


where:
Where:
:;sessionID:The session ID of the user on the organization's website. Optional. It is passed on to the authentication service, so the authentication service can make use of it.
:;sessionID:The session ID of the user on the organization's website. Optional. It is passed on to the authentication service, so the authentication service can make use of it.
:;loginID: The user's login name on the platform--typically in the form of an emails address.
:;loginID: The user's login name on the platform--typically in the form of an email address.


====Messages Sent Between the Platform and Authentication Server====
When the platform receives a SOAP request, it sends a message in the following format to the Authentication Server:
These message formats need to be processed and/or delivered by the Authentication Server.
 
;Message sent from the platform to the Authentication Server:
:The Authentication Service reads this request and authenticates the user.
:;Method:POST  
:;Method:POST  
:;URI:Configured in the [[Single Sign-On]] Settings  
:;URI:Configured in the [[Single Sign-On]] Settings  
Line 81: Line 114:
<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
    <soapenv:Body>
<LJAuthenticate xmlns="urn:authentication.soap.ws.longjump.com">
        <LJAuthenticate xmlns="urn:authentication.soap.ws.longjump.com">
<sessionID>...</sessionID>
            <sessionID>...</sessionID>
<originatingDomain>...</originatingDomain>
            <originatingDomain>...</originatingDomain>
<originatingIp>...</originatingIp>
            <originatingIp>...</originatingIp>
<loginID>...</loginID>
            <loginID>...</loginID>
</LJAuthenticate>
        </LJAuthenticate>
</soapenv:Body>
    </soapenv:Body>
</soapenv:Envelope>
</soapenv:Envelope>
</syntaxhighlight>
</syntaxhighlight>
:where:
:Where:
::;originatingDomain:Name of the Domain the request originally came from (e.g. <tt>wwww.paaspartout.com</tt>)
::;originatingDomain:Name of the Domain the request originally came from (e.g. <tt>wwww.paaspartout.com</tt>)
::;originatingIp:IP Address of the domain the request originally came from (e.g. <tt>10.20.30.40</tt>)
::;originatingIp:IP Address of the domain the request originally came from (e.g. <tt>10.20.30.40</tt>)
::;sessionID:Passed on from the original request
::;sessionID:Passed on from the original request
::;loginID:Passed on from the original request
::;loginID:Passed on from the original request
==== Messages Returned by the Authentication Server ====
After authenticating the user, the server sends back a success or failure response.


;Authentication-Succeeded response:
;Authentication-Succeeded response:
Line 101: Line 137:
::<syntaxhighlight lang="xml" enclose="div">
::<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
    <soapenv:Body>
<LJAuthenticateResponse xmlns="urn:authentication.soap.ws.longjump.com">
        <LJAuthenticateResponse xmlns="urn:authentication.soap.ws.longjump.com">
<status>AUTHENTICATED</status>
            <status>AUTHENTICATED</status>
<loginID>userLogin@Login.com</loginID>
            <loginID>userLogin@Login.com</loginID>
</LJAuthenticateResponse>
        </LJAuthenticateResponse>
</soapenv:Body>
    </soapenv:Body>
</soapenv:Envelope>
</soapenv:Envelope>
</syntaxhighlight>
</syntaxhighlight>
Line 116: Line 152:
::<syntaxhighlight lang="xml" enclose="div">
::<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" ?>
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body>
    <soapenv:Body>
<LJAuthenticateResponse xmlns="urn:authentication.soap.ws.longjump.com">
        <LJAuthenticateResponse xmlns="urn:authentication.soap.ws.longjump.com">
<status>NOT_AUTHETICATED</status>
            <status>NOT_AUTHETICATED</status>
<loginID>userLogin@Login.com</loginID>
            <loginID>userLogin@Login.com</loginID>
                        <redirectOnErrorURL>http://www.location.com/somePage</redirectOnErrorURL>
            <redirectOnErrorURL>http://www.location.com/somePage</redirectOnErrorURL>
</LJAuthenticateResponse>
        </LJAuthenticateResponse>
</soapenv:Body>
    </soapenv:Body>
</soapenv:Envelope>
</soapenv:Envelope>
</syntaxhighlight>
</syntaxhighlight>
:where:
:Where:
::;redirectOnErrorURL:URL to send the user to next. (Overrides the [[Single Sign-On]] settings.)
::;redirectOnErrorURL:URL of the next page the user sees. (Overrides the [[Single Sign-On]] settings.)

Latest revision as of 09:23, 9 March 2017

Pass Through Authentication (PTA) lets a user go straight to the platform from an organization's web page or application, without having to log in again.

Working with pass through authentication

After logging on to an enterprise application, you might want to visit a page hosted on the platform without logging on to that platform. A single log on to the enterprise application gives you access to all the pages hosted on the platform. The application sends a SOAP message to the platform in an HTTP request. That SOAP message contains the information needed to log on to the platform. The data in it is passed to an authentication server which sends back a message saying whether the authentication has succeeded or failed. The user is directed to the appropriate page, as displayed in the following diagram:

SSO-PTA.png

Here is an explanation of the steps:

User Your organization's web application Platform Authentication server
1. Log on to a web page or application provided of your organization
2. Click a link that directs to a platform page
3. Pass data to the platform's PTA service in the SOAP payload
  • Session ID (optional, but desirable)
  • Login ID
4.
  • Receive data in the SOAP payload:
  • Pass data to the Authentication server
5.
  • Authenticate the user
  • Send back a success-report or failure-report
6. Redirect the user to the appropriate page.

Enabling Pass Through Authentication

The URL of the Authentication Server and the URLs of the pages to visit in the event of success or failure are configured in the platform's Single Sign-On Settings:

  1. Click GearIcon.png > Administration > Account Management > Single Sign-On Settings.
  2. Click the [Edit] button.
  3. Choose Pass Through Authentication from the Single Sign-On Using drop-down list. Selecting Pass Through Authentication automatically displays the Platform Authentication Service URL field below the drop-down list.
  4. Specify the location of the authentication service in the Third party Authentication Service URL field. The platform uses this URL to authenticate the USER and pass the appropriate pay load in the HTTP request.
  5. Enter the URL of the page where you want to go when the authentication succeeds in the “Success page URL” field.
    If the URL is not specified then the platform will take you to the home page.
  6. Enter the URL of the page where you want to go when the authentication fails in the “Error page URL” field.
    If the URL is not specified then the platform will take you to the login page.
    This field can be overridden dynamically by the Authentication Server
  7. Click [Save]

Message Formats

Posting a Form to the Platform

The following is an example of a form which the application or web page uses to make an HTTP POST to the platform. The user is then seamlessly redirected to the success or failure page depending on the authentication.

<form id='testForm' 
   action='https://{{domain}}/networking/passThroughAuth' 
   METHOD="POST" enctype="application/x-www-form-urlencoded"
>
   <input type="hidden" name="loginID" value="jondoe@test.com">
   <input type="hidden" name="sessionID" value="adasd3qw4q4weasdasd">
</form>

Where,

loginID
The user's login name on the platform, typically in the form of an email address.
sessionID
The session ID of the user on the organization's website. This field is optional. It is passed on to the authentication service, so the authentication service can make use of it.

When the platform receives POSTed form data, it passes the data to the Authentication Service using content type application/x-www-form-urlencoded, in a request. See the example below:

Method
POST
URI
Configured in the Single Sign-On Settings
Content-Type
application/x-www-form-urlencoded
Payload
A URL Encoded version of a data string that looks like this:
loginID=jondoe@test.com&sessionID=adasd3qw4q4weasdasd
The Authentication Service reads the identification parameters from the request as it is in this Java code, for example:
String loginId   = (String)request.getParameter("loginID");
String sessionId = (String)request.getParameter("sessionID");

Where request is the object containing the HTTP request (for example, in an HttpServlet instance).

Sending a SOAP Request to the Platform

This message format can be delivered to the platform by an application or web page.

Method
POST
URI
https://{yourDomain}/networking/passThroughAuth
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <LJAuthenticate xmlns="urn:authentication.soap.ws.longjump.com">
            <sessionID>...</sessionID>
            <loginID>...</loginID>
        </LJAuthenticate>
    </soapenv:Body>
</soapenv:Envelope>

Where:

sessionID
The session ID of the user on the organization's website. Optional. It is passed on to the authentication service, so the authentication service can make use of it.
loginID
The user's login name on the platform--typically in the form of an email address.

When the platform receives a SOAP request, it sends a message in the following format to the Authentication Server:

Method
POST
URI
Configured in the Single Sign-On Settings
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <LJAuthenticate xmlns="urn:authentication.soap.ws.longjump.com">
            <sessionID>...</sessionID>
            <originatingDomain>...</originatingDomain>
            <originatingIp>...</originatingIp>
            <loginID>...</loginID>
        </LJAuthenticate>
    </soapenv:Body>
</soapenv:Envelope>
Where:
originatingDomain
Name of the Domain the request originally came from (e.g. wwww.paaspartout.com)
originatingIp
IP Address of the domain the request originally came from (e.g. 10.20.30.40)
sessionID
Passed on from the original request
loginID
Passed on from the original request

Messages Returned by the Authentication Server

After authenticating the user, the server sends back a success or failure response.

Authentication-Succeeded response
This response is sent when authentication succeeds.
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <LJAuthenticateResponse xmlns="urn:authentication.soap.ws.longjump.com">
            <status>AUTHENTICATED</status>
            <loginID>userLogin@Login.com</loginID>
        </LJAuthenticateResponse>
    </soapenv:Body>
</soapenv:Envelope>
Authentication-Failed response
This response is sent when authentication fails.
<?xml version="1.0" encoding="UTF-8" ?>
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
    <soapenv:Body>
        <LJAuthenticateResponse xmlns="urn:authentication.soap.ws.longjump.com">
            <status>NOT_AUTHETICATED</status>
            <loginID>userLogin@Login.com</loginID>
            <redirectOnErrorURL>http://www.location.com/somePage</redirectOnErrorURL>
        </LJAuthenticateResponse>
    </soapenv:Body>
</soapenv:Envelope>
Where:
redirectOnErrorURL
URL of the next page the user sees. (Overrides the Single Sign-On settings.)