HireRight Integration Platform and API: HireRight Connect. Third Party Developer Guide

Transcription

1 HireRight Integration Platform and API: HireRight Connect Third Party Developer Guide

2 Table of Contents INTRODUCTION... 3 SECURITY... 3 LOGICAL VIEW OF API ARCHITECTURE... 5 NETWORK VIEW OF API ARCHITECTURE... 5 OPERATIONS... 6 WSDL & XSD ARTIFACTS... 7 USEFUL TOOLS... 8 APPENDIX A: SCENARIO 1 - CREATE A NEW ORDER... 9 APPENDIX B: SCENARIO 2 SSO CREATE ORDER PROCESS APPENDIX C: SCENARIO 3 EVENT-TRIGGERED BACKGROUND REPORT RETRIEVAL 31 APPENDIX D: USER SYNCHRONIZATION-RELATED APIS APPENDIX E: SIMPLE SSO APIS... 40

3 Introduction HireRight provides a robust technology integration platform called HireRight Connect. HireRight Connect makes it easy for third party vendors and partners to build custom integrations using standard tools and technologies. HireRight Connect allows other applications to seamlessly integrate with HireRight because it is built using a standards-compliant Service-Oriented Architecture (SOA). HireRight Connect also supports the HR-XML Consortium guidelines for XML data exchange. As part of HireRight Connect, HireRight offers a SOAP-based API that exposes most of the critical functions necessary to place and track background screening orders. The API toolkit is a library of data and services available to build integrations with HireRight applications. The integration provides a similar user experience and feature set available in our existing pre-integrated solutions. Because of our strong commitment to data security and integrity, HireRight Connect uses a SOAP-based interface (instead of a REST-based API) with the WS-Security framework in place. HireRight regularly adds new operations and services to HireRight Connect. SECURITY HireRight s API uses the WS-Security standard for authenticating inbound requests. Within the WS-Security framework, several different implementation profiles are supported. We use the UsernameToken with PasswordDigest method for authenticating users. This requires the presence of certain SOAP Headers, and relies upon an SHA-1 encryption digest to encrypt the password we provided (see the section WSDL & XSD ARTIFACTS for a test account username/password). The best source of information on how to implement this can be found in the specifications themselves, found at: The WS-Security UsernameToken Profile is currently provided, out-of-the-box by many different vendors/tools. Microsoft s.net environment includes support, as does popular Java-based tools such as Apache Axis (Rampart module) and Spring-WS, to name a few. Page 3 of 40

4 The basic principal used by these tools is to take a SOAP envelope: <soapenv:envelope xmlns:soapenv=" <soapenv:body> <hr_objs:list xmlns:soapenc=" xmlns:hr_objs="urn:enterprise.soap.hireright.com/objs" xmlns:xsi=" xmlns:xsd=" <hr_objs:hrobject xsi:type="hr_objs:listaccounts"> <hr_objs:companycode>xyz</hr_objs:companycode> </hr_objs:hrobject> </hr_objs:list> </soapenv:body> </soapenv:envelope> And wrap it with the appropriate SOAP WS-Security Headers: <soapenv:envelope xmlns:soapenv=" <soapenv:header> <wsse:security xmlns:wsse="[abbreviated]wss-wssecurity-secext-1.0.xsd" soapenv:mustunderstand="1"> <wsse:usernametoken xmlns:wsu="[abbreviated*]" wsu:id="xwssgid "> <wsse:username>john</wsse:username> <wsse:password Type="[abbreviated*]">wrbuq1vbuB9II7/UswhPaxHkwnU= </wsse:password> <wsse:nonce EncodingType="[abbreviated*]">Js91z1AfVAU2bvBlilTbPCBg </wsse:nonce> <wsu:created> t01:21:09z</wsu:created> </wsse:usernametoken> </wsse:security> </soapenv:header> <soapenv:body> <hr_objs:list xmlns:hr_objs="urn:enterprise.soap.hireright.com/objs" xmlns:soapenc=" xmlns:xsd=" xmlns:xsi=" <hr_objs:hrobject xsi:type="hr_objs:listaccounts"> <hr_objs:companycode>xyz</hr_objs:companycode> </hr_objs:hrobject> </hr_objs:list> </soapenv:body> </soapenv:envelope> [abbreviated*] = Namespaces abbreviated for presentation purposes see the cited PDF files for full examples. The Nonce value is simply a unique identifier, similar to a GUID, that is used in conjunction with the Created timestamp to prevent reply type attacks. The Password digest value is composed by the following algorithm: Password_Digest = Base64 ( SHA-1 ( nonce + created + password ) ) Page 4 of 40

5 Logical View of API Architecture Network View of API Architecture Page 5 of 40

6 OPERATIONS HireRight s API uses a verb-noun type metaphor to manage how services are invoked. Below are a list of supported operations (i.e., verbs,), along with their supported objects ( nouns ). Operation Object Description Create Applicant Use to create an Applicant. Application Order User Use to create an Application. Requires Applicant Id. Use to place a background Order. Requires Application Id. User to create one or more HireRight users. GenerateWebLink SingleSignOnWL Returns a URL to the main HireRight landing page (user logged in). OrderApplicationWL Returns a URL to place an Order. List ListAccounts Returns a list of Accounts for a given CompanyCode. ListProductCatalogRequest ListUsers Returns a list of Packages for a given CompanyCode & AccountId. Returns a list of Users for a given CompanyCode & AccountId. Move EASApplication Used to move an EAS Application from one HireRight account to another. ReceiveReportFromQueue StatusScreeningReport Returns all queued Status Messages for a given API account. Will span across all HireRight accounts associated with that API account. Search ScreeningStatusReport Returns a single Screening Status Report for a given ApplicantId or OrderId, specified using ObjId. BackgroundScreening Report Returns a single Background Report for a given ApplicantId or OrderId, specified using ObjId. Update ModifyUser Allows updates to HireRight users. ActiveUser DeactiveUser Activate a HireRight user. Deactivate a HireRight user. What can be a source of confusion is that, if the Operation/Service has the same name and works with the same base XSD object, how do you differentiate the inbound requests? This is accomplished by way of an XSD extension. For example, the Application element is defined as: Page 6 of 40

7 <xsd:complextype name="applicant"> <xsd:complexcontent> <xsd:extension base="hr_objs:hrobject"> <xsd:sequence> <xsd:element name="candidate" type="hr_applicant:candidatetype"/> </xsd:sequence> </xsd:extension> </xsd:complexcontent> </xsd:complextype> Thus, the Applicant XSD element extends the HRObject, and adds additional elements that are unique to that object (CandidateType). This is expressed in the resulting XML as: <hr_objs:create xmlns:soapenc=" xmlns:hr_objs="urn:enterprise.soap.hireright.com/objs" xmlns:s1=" xmlns:s2="ext:enterprise.soap.hireright.com" xmlns:xsi=" xmlns:s0="urn:enterprise.soap.hireright.com/applicant" xmlns:xsd=" <hr_objs:hrobject xsi:type="hr_objs:applicant"> <hr_objs:companycode>xyz</hr_objs:companycode> <hr_objs:userid>2222</hr_objs:userid> <hr_objs:accountid>3333</hr_objs:accountid> <hr_objs:candidate> <s0:candidateprofile> <s1:personaldata> <s1:personname> <s1:formattedname></s1:formattedname> <s1:middlename></s1:middlename> </s1:personname> ** NOT SHOWN ** </s1:personaldata> </s0:candidateprofile> </hr_objs:candidate> </hr_objs:hrobject> </hr_objs:create> In the above example, the xsi:type attribute defines what extension object is being used. WSDL & XSD ARTIFACTS HireRight has been a long-time supporter and member of the HR-XML consortia, and as such, we leverage the HR- XML specifications as closely as possible. We deviate only where there are no established schema elements which we can utilize. Since the HR-XML specification is extremely broad, we have paired down the HR-XML schemas to a more manageable size, based upon only those elements/attributes that we support. In other words, HireRight has implemented a fully compliant subset of the standard HR-XML schemas. The HireRight API WSDL can be found at: This is currently a test-only environment, and does not interface or otherwise directly connect to HireRight s underlying backend. It is a testing sandbox that returns dummy data for each service call made, and is intended primarily for connectivity and WS-Security compatibility testing. NOTE: This is considered the official WSDL, and may likely be more up-to-date than this document describes. The URL used for placing service calls is found at: (as identified in the WSDL). However, you may also use (the trailing / is required) if you want to test without including the WS-Security SOAP Headers. This is beneficial for initial testing. We suggest first testing without WS-Security, and then adding it later once you ve established that you can successfully request/receive service calls. When connecting to the testing environment, use the following user name and password: User Name: john Password: changeme Page 7 of 40

8 HireRight has certified that our WSDL and operations are WS-I Basic 1.0 Compatible (using SOAPScope 5.2 from Mindreef). USEFUL TOOLS We ve found the following tools to be very useful: TOOL DOWNLOAD URL DESCRIPTION Mindreef SOAPScope scope/index_temp.php Excellent commercial SOAP testing/invocation & documentation tool. soapui Powerful open-source testing/invocation & inspecting tool. Alternative to SOAPScope. TCP Mon Tool for intercepting in-transit SOAP messages. Shows you raw XML as it s being exchanged. Very helpful. WebServiceStudio sersamples/details.aspx?sampleguid= 65a1d4ea-0f7a-41bd e916ebc4159c Useful tool for testing compatibility with.net applications. Page 8 of 40

9 Appendix A: Scenario 1 - Create a New Order This scenario is where a faceless integration is required. That is, a complete data set is sent to HireRight for the creation of an order. This model is generally only appropriate where the source/client system can ensure that all data required for the package that is order is valid and complete. The process to create a new Order in this model is straightforward, and requires 3 web service (SOAP) calls to HireRight. The sequence is illustrated below: The steps involved are: Create->Applicant. This is used to create an Application, and only requires personal descriptor information that can be used to uniquely identify the applicant. These descriptors, such as Government ID (SSN) are those that do not change, regardless of the position being applied. This service call returns an ApplicantId. Create->Application. Once an Applicant is created within the HireRight system, an Application for that individual can be created. This is done through the Create->Application method call. HireRight supports multiple Applications per Applicant, which is two operations, are required (for example, different position being applied for may have different data requirements, such as years of employment experience that must be specified etc). Required fields (specified in the WSDL schema) include ApplicantId and contact information. This service call returns an ApplicationId. Create->Order. This operation, which requires an ApplicationId, is used to actually generate the HireRight Order. Similar to the relationship between Applicant and Application, there can be multiple Orders per an Application. This might result from where subsequent products are desired, perhaps based upon the initial results of the first Order placed. The Order requires a PackageId, which can be provided by HireRight, or queried directly using an API call. Page 9 of 40

10 With the OrderId that is returned from the Create->Order service method, the Client can optionally receive status updates pertaining to the ongoing processing of the Order, and also use it to fetch the complete Screening Report. Below are XML examples for the Create Applicant, Application and Order operations (Note: they do not contain the WS-Security SOAP headers, which can be rather verbose). Create->Applicant Example (REQUEST) <hr_objs:create xmlns:soapenc= xmlns:hr_objs="urn:enterprise.soap.hireright.com/objs" xmlns:s1=" xmlns:s2="ext:enterprise.soap.hireright.com" xmlns:s0="urn:enterprise.soap.hireright.com/applicant" xmlns:xsd=" <hr_objs:hrobject xsi:type="hr_objs:applicant" xmlns:xsi=" <hr_objs:companycode>xyz</hr_objs:companycode> <hr_objs:userid>479321</hr_objs:userid> <hr_objs:accountid>ws_someaccount</hr_objs:accountid> <hr_objs:candidate> <s0:candidateprofile> <s1:personaldata> <s1:personname> <s1:givenname>john</s1:givenname> <s1:middlename>j</s1:middlename> <s1:familyname>doe</s1:familyname> </s1:personname> <s1:persondescriptors> <s1:legalidentifiers> <s1:personlegalid countrycode="us" validfrom="notapplicable"> <s1:idvalue name="ssn"> </s1:idvalue> </s1:personlegalid> <s1:userarea> <s2:drivinglicenseinfo> <s2:drivinglicense countrycode="us" idowner="ministry of Transportation" issuingregion="ny" validfrom="notapplicable" validto="notapplicable"> <s2:idvalue name="driver's License">123</s2:IdValue> <s2:nameonlicense>drvname5</s2:nameonlicense> </s2:drivinglicense> </s2:drivinglicenseinfo> </s1:userarea> </s1:legalidentifiers> <s1:biologicaldescriptors> <s1:dateofbirth> </s1:dateofbirth> </s1:biologicaldescriptors> </s1:persondescriptors> <s1:userarea> <s2:othernames> <s2:othername type="" validfrom="notapplicable" validto=" "> <s2:personname> <s2:formattedname>first Name1 Last Name1</s2:FormattedName> <s2:givenname>first Name1</s2:GivenName> <s2:middlename>middle1</s2:middlename> <s2:familyname>last Name1</s2:FamilyName> </s2:personname> </s2:othername> <s2:othername type="" validfrom="notapplicable" validto=" "> <s2:personname> <s2:formattedname>first Name2 Last Name2</s2:FormattedName> <s2:givenname>first Name2</s2:GivenName> <s2:middlename>middle2</s2:middlename> <s2:familyname>last Name2</s2:FamilyName> </s2:personname> Page 10 of 40

11 </s2:othername> </s2:othernames> </s1:userarea> </s1:personaldata> </s0:candidateprofile> </hr_objs:candidate> </hr_objs:hrobject> </hr_objs:create> Create->Applicant Example (RESPONSE) <ns1:createresponse xmlns:ns1="urn:enterprise.soap.hireright.com/objs"> <ns1:result> <ns1:id> </ns1:id> <ns1:success>true</ns1:success> </ns1:result> </ns1:createresponse> Page 11 of 40