API – Single Sign On

API – Single Sign On



INTRODUCTION

The printIQ Single Sign On (SSO) API can be called to obtain a URL with a token that has been pre-authenticated to log a user in, and begin a customer quote. The API calls are restricted by IP address, which must be configured manually by IQ, as well as a special SSO Application Key - separate to the application keys used for other API calls.

 

The API can be found at http://gpo.printiq.com/webservice/Authentication.asmx/SSORequest and supports both SOAP and JSON requests. A WSDL can be generated from http://gpo.printiq.com/webservice/Authentication.asmx?wsdl.

 

For security reasons, the API is not able be called for an admin user. Users with Factory Admin, or Admin roles may not use this API.

 

 

INPUT

The API takes just one parameter, which is an SSORequestInput object.

 

SSORequestInput object definition

SOAP

<SSORequest xmlns="http://printiq.co.nz/">

      <input>

        <CusCode>string</CusCode> <!-- Optional, customer code to make the quote for -->

        <UserName>string</UserName> <!-- User to auto-login as -->

        <AppKey>string</AppKey> <!-- Your SSO application key, provided by IQ -->

        <OpportunityRef>string</OpportunityRef> <!-- Optional, add to Ref1 on the printIQ Quote -->

      </input>

</SSORequest>

JSON

POST http://printiq.co.nz/WebService/Authentication.asmx/SSORequest HTTP/1.1

Host: printiq.co.nz

Content-Type: application/json; charset=utf-8

Content-Length: 142

 

{ 

   "input":{ 

      "CusCode":"string", // Optional, customer code to make the quote for

      "UserName":"string", // User to auto-login as

      "AppKey":"string", // Your SSO application key, provided by IQ

      "OpportunityRef":"string" // Optional, reference to add Ref1 on the printIQ quote

   }

}

The below example shows a call to log in as testuser, generating a new quote for customer CUST001, with the Ref1 set to website.

Example SSORequestInput

SOAP

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

  <soap12:Body>

    <SSORequest xmlns="http://printiq.co.nz/">

      <input>

        <CusCode>CUST001</CusCode>

        <UserName>testuser</UserName>

        <AppKey>F0F4F147-3C2E-4B57-A6B7-66165A6C4226</AppKey>

        <OpportunityRef>website</OpportunityRef>

      </input>

    </SSORequest>

  </soap12:Body>

</soap12:Envelope>

JSON

 

POST http://printiq.co.nz/WebService/Authentication.asmx/SSORequest HTTP/1.1

Host: printiq.co.nz

Content-Type: application/json; charset=utf-8

Content-Length: 173

 

{ 

   "input":{ 

      "CusCode":"CUST001",

      "UserName":"testuser",

      "AppKey":"F0F4F147-3C2E-4B57-A6B7-66165A6C4226",

      "OpportunityRef":"website"

   }

}

 

 

OUTPUT
The API will output an SSORequestResponse object, which will contain any error messages, or a URL to use for single sign on. If IsError is set to true, SimplifiedURL and LandPageURL will be empty.

 

SSORequestResponse object definition

SOAP

<SSORequestResponse xmlns="http://printiq.co.nz/">

      <SSORequestResult>

        <IsError>boolean</IsError>

        <ErrorMessage>string</ErrorMessage>

        <SimplifiedURL>string</SimplifiedURL>

        <LandPageURL>string</LandPageURL>

      </SSORequestResult>

</SSORequestResponse>

 

JSON

 

{ 

   "d":{ 

      "__type":"string",

      "IsError":boolean,

      "ErrorMessage":"string",

      "SimplifiedURL":"string",

      "LandPageURL":"string"

   }

}

 

 

Example success

SOAP

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

  <soap12:Body>

    <SSORequestResponse xmlns="http://printiq.co.nz/">

      <SSORequestResult>

        <IsError>false</IsError>

        <ErrorMessage></ErrorMessage>

        <SimplifiedURL>http://gpo.cloudapp.net/Simplified/CreateQuote.aspx?cusID=13926&quoteref1=website&AuthToken=2b0162fed3f248cf8321fca279d197c3</SimplifiedURL>

        <LandPageURL>http://gpo.cloudapp.net/LandPage.aspx?AuthToken=2b0162fed3f248cf8321fca279d197c3</LandPageURL>

      </SSORequestResult>

    </SSORequestResponse>

  </soap12:Body>

</soap12:Envelope>

 

JSON

 

HTTP/1.1 200 OK

Cache-Control: private, max-age=0

Content-Type: application/json; charset=utf-8

Server: Microsoft-IIS/8.5

X-AspNet-Version: 4.0.30319

X-Powered-By: ASP.NET

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, PUT, POST, DELETE, HEAD, OPTIONS

Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept

Date: Tue, 24 Nov 2015 22:25:16 GMT

Content-Length: 338

 

{ 

   "d":{ 

      "__type":"PrintIQ.Authentication+SSORequestResponse",

      "IsError":false,

      "ErrorMessage":null,

      "SimplifiedURL":"http://printiq.co.nz/Simplified/CreateQuote.aspx?cusID=1&quoteref1=TestOpp&AuthToken=8e081323f0dd472f8267e2d1fe0b7836",

      "LandPageURL":"http://printiq.co.nz/LandPage.aspx?AuthToken=8e081323f0dd472f8267e2d1fe0b7836"

   }

}

 

Example failure

SOAP

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap12="http://www.w3.org/2003/05/soap-envelope">

  <soap12:Body>

    <SSORequestResponse xmlns="http://printiq.co.nz/">

      <SSORequestResult>

        <IsError>true</IsError>

        <ErrorMessage>No user found with username testuser</ErrorMessage>

        <SimplifiedURL></SimplifiedURL>

        <LandPageURL></LandPageURL>

      </SSORequestResult>

    </SSORequestResponse>

  </soap12:Body>

</soap12:Envelope>

 

JSON

 

HTTP/1.1 200 OK

Cache-Control: private, max-age=0

Content-Type: application/json; charset=utf-8

Server: Microsoft-IIS/8.5

X-AspNet-Version: 4.0.30319

X-Powered-By: ASP.NET

Access-Control-Allow-Origin: *

Access-Control-Allow-Methods: GET, PUT, POST, DELETE, HEAD, OPTIONS

Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept

Date: Tue, 24 Nov 2015 22:25:16 GMT

Content-Length: 138

 

{ 

   "d":{ 

      "__type":"PrintIQ.Authentication+SSORequestResponse",

      "IsError":true,

      "ErrorMessage":"No user found with username testuser",

      "SimplifiedURL":"",

      "LandPageURL":""

   }

}

 

 

EXAMPLE ERROR MESSAGES

  • Invalid appkey returned, expecting guid with format: 00000000-0000-0000-0000-000000000000
  • Origin "{IPAddress}" is not authorized to use "SingleSignOn" API
  • No user found with username {username}
  • User {UserName} is not allowed access using this API because they have Admin rights, please ensure your user does not have Admin rights and try again
  • No customer found with code {CusCode}