Foundation Integrations

Kenexa XML Integrations

SSO KRB Enterprise Integrations:

1.1        Purpose

The purpose of this document is to describe the Kenexa Recruiter BrassRing single-sign-on (SSO) functionality and explains the steps a client must perform to implement it.

1.2        Scope

·         This document is not specific to any one HRIS (Human Resources Information Systems); rather it is a generic overview, which is applicable to any system that the client uses to authenticate its users, including “home-grown” systems that clients create themselves.

·         Implementation details of external systems are outside the scope of this document.

1.3        Audience

This is a technical document whose intended consumer is the engineer responsible for the actual implementation of the client’s SSO integration with Kenexa Recruiter BrassRing.

2         BEFORE YOU BEGIN

Before beginning a Kenexa Recruiter BrassRing SSO implementation, the client should review the following lists, which describe the integration tasks performed by Kenexa and those performed by the client. The remaining sections in this document describe each checklist item in more detail.

2.1        Tasks Performed by the Client

·         Let Kenexa know if you want login page redirection implemented as part of the integration. See “Login Page Redirection” in section 3.4 for more information.

·         The client is responsible for authenticating its internal candidates and may use any authentication mechanism to do so. Let Kenexa know which external method you will use to authenticate candidates who access the Gateway. See “Client Authentication Mechanisms” in section 3.1 for more information.

·         Provide initial employee data to Kenexa. Kenexa recommends implementing User XML integration to send user information into the Kenexa system.

·         Implement the sample XML provided by Kenexa and incorporate it into your SSO integration. See “XML Details” in section 5 for more information.

·         Create one or more public keys, each with its own start date/time. The client is responsible for maintaining its private keys on its own servers and for using the correct key during each SSO exchange. See “EncryptionError! Reference source not found.” in section 3.3 for more information.

·        Handle all errors and failed requests. See “Processing and Error Handling” in section 5.3 for more information.

2.2        Tasks Performed by Kenexa

·         Import the client’s public keys into Kenexa Recruiter BrassRing, and then specify keys to associate with the SSO application.

·         Generate sample integration XML specific to the Gateway and sends the XML to the client.

·         Implement login page redirection, if the client requests it.

·         Check if the client’s Kenexa Recruiter BrassRing site is SSL-enabled (Kenexa highly recommends this.) and if the site requires 128-bit SSL encryption.

3         ARCHITECTURAL OVERVIEW

Kenexa Recruiter BrassRing SSO is provided as a hosted XML web service that allows a client to send a request to Kenexa Recruiter BrassRing to confirm the validity of the user’s identity and grant them Kenexa Recruiter BrassRing access.

The client sends an XML request that contains at least the following information about an authenticated user who is to be granted access to Kenexa Recruiter BrassRing:

·         Userid that has been set in KRB; this is a unique identifier that identifies a user (this is the decrypted value of the User name in the users table in KRB) (case sensitive)

·         an email address of the user (case sensitive)

·         timestamp

If the request is successfully validated, the user is then logged into Kenexa Recruiter BrassRing with the correct identity. For more details about this process flow, see “WEB SERVICES WORKFLOW” in section 4. For more details about the XML request and possible responses, see “XML DETAILS” in section 5.

NOTE: When a client configures Kenexa Recruiter BrassRing for SSO, everyone who accesses Kenexa Recruiter BrassRing must be validated and authenticated through an external system. There will be no other way to access Kenexa Recruiter BrassRing but through the external system’s SSO portal.

3.1        Client Authentication Mechanisms

The client is responsible for authenticating its internal candidates and may use any authentication mechanism to do so. Here are some examples of possible authentication mechanisms:

·         Username/password authentication against a database maintained by the client

·         Microsoft™ Windows™ domain authentication

·         Oracle™ authentication

·         SAP™ authentication

This list is by no means exclusive. The client may authenticate users however it wishes, as long as each user is properly authenticated by the client before the user’s identity is submitted to Kenexa Recruiter BrassRing.

3.2        SSO Protocol Options

Kenexa Recruiter BrassRing requires identity assertion and verification of user credentials for successful login.

·         Identity assertion: The client’s server informs Kenexa Recruiter BrassRing of the identity of the user. If the specified identity matches a user configured in Kenexa Recruiter BrassRing, the user is logged in. This document discusses identity assertion.

·         Identity verification: The client’s server informs Kenexa Recruiter BrassRing of the identity of the user. Kenexa Recruiter BrassRing contacts the client’s server and asks for confirmation of the user’s identity and request for access. The client’s server informs Kenexa Recruiter BrassRing that they are valid, and then if the specified identity matches a user configured in Kenexa Recruiter BrassRing, the user is logged in. This kind of verification requires special configuration and is outside the scope of this document.

3.3        Encryption

The data exchanged between Kenexa Recruiter BrassRing and the client’s servers must be encrypted with RSA encryption. For details on encryption specifics, key management, etc. please refer to the Kenexa RSA Encryption Application Guide.

3.4        Login Page Redirection

At the client’s request, Kenexa can configure the client’s Kenexa Recruiter BrassRing site to redirect to the client’s Kenexa Recruiter BrassRing landing page any users who attempt to access Kenexa Recruiter BrassRing directly. This is especially useful for clients who were previously using standard Kenexa Recruiter BrassRing username/password logins but wish to transition to SSO – users who have bookmarked the client’s Kenexa Recruiter BrassRing site will be automatically redirected to the page from which they can log into Kenexa Recruiter BrassRing. If the client’s site is not configured to redirect, then users who attempt to access the site directly will see an error rather than a login page.

4         WEB SERVICES WORKFLOW

This table describes the Kenexa Recruiter BrassRing SSO workflow as experienced by a user trying to access Kenexa Recruiter BrassRing.

Action

Responsibility

1

(optional)The user attempts to access the client’s Kenexa Recruiter BrassRing site directly and is redirected to the client’s SSO landing page.

User

2

The user clicks a link on the landing page.

User

3

The client’s login landing page determines whether the user is already logged into the client application.

Client System

4

If the user is not already logged in, they log into the client application, which authenticates and validates the user. See “Client Authentication Mechanisms” in section 3.1 for more information.

·         If the client cannot validate the user, the client application displays an error message to the user.

·         If the user is authenticated, the client application makes an XML request to the KRB hosted web service. The request contains the Session ID, Timestamp and Employee data, which are encrypted. See “Sample Request” in section 5.1 for more information about these elements.

Client System

5

KRB receives the web service request, processes the information in the request, and determines if the request is for eLink authentication or Kenexa Recruiter BrassRing login and if the client is configured for SSO. See Sample Request in section 5.1 for a sample request.

KRB

6

KRB validates the web service request and evaluates the timestamp to determine if the request was made within the specified limit. These guards against replay attacks.

KRB

7

If KRB successfully validates the request and determines the transaction to be authentic, a re-direct URL is sent in a success message. See “Success Response” in section 5.3.1 for a sample successful validation response.

KRB

8

If KRB cannot validate the request, an error message that describes the cause for failure in sent in a failure message. See “Failure Response” in section 5.3.2 for a sample unsuccessful validation response.

KRB

9

The client system processes the information received in the XML response from KRB.

·         If the handshake is not successful, an error message is displayed to the user.

·         On a successful handshake, the user is re-directed to the URL received.

Client System

5         XML DETAILS

The hosted web service uses XML messages to pass user login information to Kenexa Recruiter BrassRing. The client can customize the sample XML in this section and incorporate it into their own SSO integration.

5.1        Sample Request

This self-documented XML sample sends user credentials for validation by Kenexa. The <ApplicationType> node specifies that this message is for Kenexa Recruiter BrassRing SSO login. The <Timestamp> element helps guard against replay attacks.

<?xml version="1.0"?>

<Envelope version="01.00">

       <Sender>

             

             <Id/>

             

             <Credential>25119</Credential>

       </Sender>

       <Recipient>

             

             <id type=""/>

       </Recipient>

       <TransactInfo transactType="data">

             

             <transactId>123XYZ</transactId>

             

             <timeStamp>2007-04-24 15:47:59.213</timeStamp>

       </TransactInfo>

       <Packet>

             <PacketInfo packetType="data">

                    <PacketId>1</PacketId>

                    

                    <Action/>

                    

                    <Manifest/>

                    

                    <PacketCode/>

             </PacketInfo>

             <Payload>

                    <BrassRing>

                           

                           <applicationtype>login</applicationtype>

                    </BrassRing>

                    <EncryptedData xmlns="http://www.w3.org/2001/04/xmlenc#">

                           <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

                           <CipherData>                   <CipherValue>Z8uYYkFKEvKKg9vIStphIVtVO4VGTuI9ZSyMi6QcTlyKAL57QqiiYc9TVTXDEtTSiFwYuX6HWuiibBzMiIUmSPfm+YQUNIDUr5SWX72JWgCdA+HnJm489mSVABNcDoJBglCSfR6iWuPGDhLk1owBj2x3at4/KL66Q0bHwwrtOnyQB/uqVSHlhODbMD+ejfSHy7g3itdGAxQsR5C4jjxDNE8/UkHurJ2RNFeLxGbXUCmOjD9e9qo21GoRVY5yuDQY2JNqpc2qcfqGzjvan29wEF0fDFhGXteGMos6PIob32EmFv3pJykrg7KtlVaZQIDFyYJMWUD7IX+ukHr3yNLF3XGgGqrAYKWY1g4/xcEsR5bSR5zseCzCMsP8ZfCW33uxHHqJNcVrADiTTfgLU/RhyHGG34COhU1ybvSvVB3S4smsJdaaVkT6tGDoiTOciIX8aKs5SSjrXyXBP/wDrtJcVICEbLk1k3f0Q96syT8dvwBIVaKXdTkErBXN1VjSepZmIHXbsmb7es3+EqsIHElpd3x7vpCvomAmhK3IplMHuks1UYa4n2peHmmGTbsBXe0SOljy8eMX+PIRkK0OwmuGzDziXqXmHYUSt4Vc2wSRhITil1yBsHw5xluHi2jJoKtZtx90l04bHj9k5djTmgwGIKlZLGt6sUJREfWIvdM9oc4=</CipherValue>

                           </CipherData>

                    </EncryptedData>

                    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

                           <SignedInfo>

                                 <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>

                           </SignedInfo>

                           <SignatureValue>kWnG6qMnPrmi7YdcrzwOiFFEMP22yZCItZZzJBx45VW5pjdaxCv7rOf9jdiREzctipLvkmcajf8gWqmSHoHtwhFhMw9u4+2kGQh86AYDPeeYc/LXyobMCjWWadiRTNkipPQys/jNGokAj1+jhF9zBuZgWZNl2PEKIHw/uoQf1D4=</SignatureValue>

                    </Signature>

             </Payload>

       </Packet>

</Envelope>

5.2        Kenexa Recruiter BrassRing SSO schema

<?xml version="1.0" encoding="UTF-8"?>

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">

   <xs:element name="BRSIntegration">

      <xs:complexType>

         <xs:sequence>

            <xs:element ref="EmployeeData"/>

         </xs:sequence>

      </xs:complexType>

   </xs:element>

   <xs:element name="EmployeeData">

      <xs:complexType>

         <xs:sequence>

            <xs:element ref="employeeID"/>

               <xs:annotation>

               <xs:documentation>

                A string that specifies the Username in KRB

               </xs:documentation>

               </xs:annotation>

<xs:element ref="emailID"/>

                           <xs:element ref="TimeStamp"/>

                           <xs:element ref="token"/>

                    </xs:sequence>

             </xs:complexType>

       </xs:element>

       <xs:element name="TimeStamp" type="xs:string"/>

       <xs:element name="emailID" type="xs:string"/>

       <xs:element name="employeeID" type="xs:string"/>

            <xs:element name="token" type="xs:string"/>

</xs:schema>

5.2.1       CipherData Example

                           <CipherData>

                                 <CipherValue>

                                        

                                        <BRSIntegration>

                                               <EmployeeData>

                                                     

                                                     <employeeID>KRB User name goes here</employeeID>

                                                     

                                                     <emailID>KRB User email goes here</emailID>

                                                     

                                                     <TimeStamp>2007-04-24 14:37:01.033</TimeStamp>

                                                     

                                                     <token/>

                                               </EmployeeData>

                                        </BRSIntegration>

                                 </CipherValue>

                   </CipherData>

5.3        Processing and Error Handling

This section provides sample success and failure responses, and provides guidelines for resubmitting failed transactions.

5.3.1       Success Response

The nodes within the XML are processed in a linear “first-come, first-served” order. If the XML is successfully validated, a success response like the one that follows is returned synchronously:

<Envelope version="01.00">

       <Sender>

             <Id/>

             <Credential>25037</Credential>

       </Sender>

       <Recipient>

             <Id/>

       </Recipient>

       <TransactInfo transactType="response">

             <TransactId>3368XYZ</TransactId>

             <TimeStamp>2005-08-03T12:20:18.000000-0400</TimeStamp>

       </TransactInfo>

       <Packet>

             <PacketInfo packetType="response">

                    <PacketId>1</PacketId>

                    <Action/>

                    <Manifest/>

             </PacketInfo>

             <Payload>

                    <EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xsi="http://www.w3.org/2001/04/xmlenc#">

                           <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

                           <CipherData>

                                 <CipherValue>

                                        

                                        

                                 </CipherValue>

                           </CipherData>

                    </EncryptedData>

                    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

                           <SignedInfo>

                                 <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>

                           </SignedInfo>

                           <SignatureValue/>

                    </Signature>

             </Payload>

       </Packet>

</Envelope>

5.3.2       Failure Response

If an error is detected during validation, the entire message is rejected and an error response like the one that follows is returned synchronously:

<Envelope version="01.00">

   <Sender>

      <Id/>

         <Credential>25037</Credential>

   </Sender>

   <Recipient>

      <Id/>

   </Recipient>

   <TransactInfo transactType="response">

      <TransactId>3368XYZ</TransactId>

      <TimeStamp>2005-08-03T12:20:18.000000-0400</TimeStamp>

   </TransactInfo>

   <Packet>

      <PacketInfo packetType="response">

         <PacketId>1</PacketId>

         <Action/>

         <Manifest/>

      </PacketInfo>

      <Payload>

         <EncryptedData Type="http://www.w3.org/2001/04/xmlenc#Element" xmlns:xsi="http://www.w3.org/2001/04/xmlenc#">

            <EncryptionMethod Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-1_5"/>

            <CipherData>

               <CipherValue>

                  

                  

               </CipherValue>

            </CipherData>

         </EncryptedData>

         <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">

            <SignedInfo>

               <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#dsa-sha1"/>

            </SignedInfo>

            <SignatureValue/>

         </Signature>

      </Payload>

   </Packet>

</Envelope>

5.3.3       Analyzing Failed Requests

If an error is detected during validation of an integration XML request, the entire message is rejected and a failure response is returned synchronously. Failure responses include the following information in the <Status> node to help you diagnose the error:

·         The <Code> element contains the HTTP status code associated with the outcome of the request. See “HTTP Status Codes” below for more information.

·         The <ShortDescription> element simply indicates that the request failed.

·         The <LongDescription> element contains a descriptive error message that describes the reason the request failed.

5.3.3.1     HTTP Status Codes

All synchronous responses sent by Kenexa Recruiter BrassRing in an XML integration – both success responses and failure responses – include one of the following HTTP status codes:

HTTP Status Code

Description

200

The request sent by the client was successful.

401

Access was denied because of a security or authentication problem. This type of error might occur while Kenexa and the client are setting up the integration in a test environment.

405

All failures related to anything other than security and authentication. When the <Code> for a failure response is 405, check the detailed error message in <LongDescription> to see if the error is the result of:

·         A permanent condition that must be fixed before the request can be resubmitted. For example, the request did not include the authenticated user’s email address.

·         A transient condition for which retrying the request is appropriate. For example, there was a system problem like a database timeout.

5.3.3.2     Retrying Failed Requests

If the system responds to the request with a system error or gives no response from the system at all, the client should retry the request up to five times.

The SSO scenario differs from other types of integration scenarios because submissions for most integrations are automated. For SSO, a user is actually at his or her computer, clicking a link, so a large number of retries and any waits between retries are not acceptable.

5.3.4       SSO Error Messages

This section lists the error messages that Kenexa Recruiter BrassRing could return for SSO implementations.

5.3.4.1     General XML Validation Error Messages

·         We have successfully received the candidate XML. Once the xml is processed and the data is loaded, another message will be send to you in the form of communication you have selected.

·         SSO XML is empty.

·         Unexpected system error occured.

·         Data could not be decrypted and validated. Security exception generated.

·         Invalid xml.

·         Invalid Credential

·         Invalid SiteId

·         Invalid SsoId

·         The Client ID or Key Group Name cannot be validated against the Site ID provided.

·         Invalid xml. A valid SsoId is required.

·         Invalid xml. Invalid or unexpected nodes present under /Envelope/Packet/Payload/EncryptedData/CipherData/CipherValue/ TGIntegration node.

·         SiteId does not follow expected path: /Envelope/Packet/Payload/BrassRing/SiteId.

·         Credential does not follow expected path: /Envelope/Sender/Credential.

·         TGIntegration does not follow expected path: //CipherData/CipherValue/TGIntegration.

·         SsoId does not follow expected path: //CipherData/CipherValue/TGIntegration/SsoNodes/SsoId.

·         CipherData TimeStamp does not follow expected path: //CipherData/CipherValue/TGIntegration/TimeStamp.

5.3.4.2     Security Error Messages

·         Invalid EncryptedData

·         EncryptionMethod not supported

·         Invalid CipherData TimeStamp

·         EncryptionMethod not supported

·         Invalid Signature

·         SignatureMethod not supported.

·        Invalid SignatureValue.

5.4        Web service URLs

Kenexa exposes individual web services for each environment. Your Kenexa integration consultant will provide you the web service URLs at the time of implementation