printIQ - LDAP Integration

printIQ is a web based application that uses a forms based authentication model.  User accounts must exist or otherwise be created on the fly for each user as this is what drives user access and what account they can order on.  So, what we’re looking to do here is figure out the best way to authenticate the password.

For standard (non admin) type users, we can automatically generate the user account within printIQ when they first login. In all cases, only staff type users will be created this way while admin users need to be manually created within the printIQ instance itself.  

There are three types of Active Directory authentication available:

• Publicly exposed LDAP
  
• Private LDAP with an IQ supplied request handler
  
• ADFS using SAML
  

Our preferred approach is to use ADFS using SAML (configuration option 3).  This uses SAML requests to transport the authentication request.  The SAML request that returns user information to printIQ is what allows us to create the user account on the fly.  Please see the configuration workflow for 3) printIQ exposes an endpoint that receives SAML Requests from customer's ADFS below.

There are 3 configuration options:

1) Publicly exposed LDAP - Your active directory is exposed publicly (perhaps limited to access from our Server’s IP)

1. In this case printIQ can issue an LDAP request over the internet to the domain which will confirm credentials
   

2)  Private LDAP with an IQ supplied request handler - IQ to provide a small web application for you to install on your servers which receives authentication requests from printIQ and passes to your Active Directory.  This is on the basis that you don’t want to expose your AD to be web facing.

1. The application should run over HTTPS
   
2. The application will run under credentials which have Read Access to active directory
   

In both of the above cases, the workflow follows the following process: 

1. User will login to printIQ using your domain/username/password on our forms authentication box          
   
2. Application will check credentials against customer’s Active Directory, If authentication is successful, the user will be logged in
   
3. If the user does not exist in printIQ, printIQ can create it using some default values.
   
4. The default values are as follows:
   
5. Customer code – This is read from the printIQ setting “PrintIQ_DefaultUserCustomerCode”
   
6. Account Manager – This is read from the printIQ setting “PrintIQ_DefaultUserAccountManagerName” – If this setting is not valid, we will select the first Account Manager in the database
   
7. Branding – This is read from the printIQ setting “PrintIQ_DefaultUserBrandID”
   
8. Email – This is read from the printIQ setting “PrintIQ_DefaultUserEmailAddress”
   
9. Once your user has successfully logged in for the first time, they will be presented with a “User Profile” modal where they will be able to set their First name/surname/email and some other information.
   

The final configuration option is ADFS using SAML

3) printIQ exposes an endpoint that receives SAML Requests from customer's ADFS

1. User navigates to printIQ, if they are not logged in, we generate a SAML authentication request and send the user to your authentication page (an IDP initiated sign on page)
   
2. User completes login on your authentication page, which generates a SAML request and pushes to printIQ
   
3. We expose an endpoint that receives SAML Requests from customer's ADFS, this endpoint decrypts SAML messages using the HTTPS certificate of the printIQ site
   
4. The SAML request contains 5 "assertions" which are givenname,surname,emailaddress,name,department - department must link to a valid customer code in printIQ, name should be a unique username, email should also be unique
   

1. If the username (assertion "name") does not exist in printIQ, we will attempt to create it using the assertions passed
   
2. If the “department” assertion does not exist in printIQ (as a customer code) the user will see an error on the printIQ login page “Unable to process user login because department "SOME DEPARTMENT" was unable to be found.  Please contact your system administrator for assistance”
   

In order to configure the Public or Remote LDAP integration (option 1 and 2) (note: this does not apply to the ADFS using SAML workflow) , please follow the following steps:

1. Before we start, please note that this application should be installed on a server where PrintIQ will be able to issue requests
   
2. The app is available on request from IQ (resides in printIQ Utilities)
   
3. Extract the application files into a directory which is readable by IIS (e.g. C:\inetpub\IQRemoteLDAP)
   
4. Open the web.config file and configure your LDAP directory, a sample value exists in the config which much be changed for your environment
   

1. For assistance in determining your LDAP connection, visit this link: http://serverfault.com/a/130556
   

1. Open IIS, create a new site & application pool, point the new site at your IQRemoteLDAP directory
   

1. Note: your application pool may need to have the user changed from the default to a user which has access to domain services on your network
   
2. Note 2: IQ recommends that you configure your site over HTTPS/SSL to prevent domain credentials being passed over the internet in an unencrypted fashion
   

1. In your browser, navigate to {appPath}/Auth.asmx?op=Authenticate
   
2. Confirm that your site has been successfully configured, your screen should look like:
   

1. To further test the application, we will use Fiddler to test a real auth request
   

1. If required, download fiddler at: http://www.telerik.com/download/fiddler (requires windows OS)
   

1. Once installed, open fiddler and click the Composer tab, then the lower Scratchpad tab
   
2. Insert the following text, be sure to replace {appPath} with your application path
   

POST http://{appPath}/Auth.asmx/Authenticate HTTP/1.1

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

Host: {appPath}

Content-Length: 28

{"req": {"Domain":"{UsersDomain}","Username":"{UsersUsername}", "Password":"{UsersPassword}"}}

1. Highlight and execute the request
   
2. If there is any error, it will be written to then ErrorMessage property of the response
   
3. To view the response, double click your request on the left hand side and then click "Json" on the lower right hand side
   
4. If authentication is successful, the application is ready for production
   

1. To activate remote LDAP authentication in PrintIQ
   

1. Naviate to {YourPrintIQPath}/Admin/Settings.aspx
   
2. Login if required
   
3. Search for PrintIQ_DomainAuthenticationRemoteServer 
   

1. Change the value to your newly created IQRemoteLDAP url
   

1. Search for PrintIQ_DomainAuthenticationType   
   

1. Change the value to "Remote" or “Local” (without the quotes) – the chosen value depends on your method of authentication (configuration option 1 or 2)
   

1. Optional: Search for PrintIQ_DomainAuthenticationPresetDomainValue   
   

1. Change the value to the domain which users will authenticate against e.g. "IQ" or "wgtn.iq.co.nz"
   

1. Finally, Search for PrintIQ_EnableDomainAuthentication   
   

1. Change the value to "True" (without the quotes)
   

1. Now you can log out and navigate to the login screen
   

1. Click "Use Domain" to switch authentication to domain mode
   
2. Enter your domain credentials
   
3. Login should be successful
   

In order to configure ADFS using SAML, please follow the following steps:

1. Configure your ADFS IDP Single Sign on
   

1. Ensure these attributes are included in the SAML response:
   

1. surname
   
2. emailaddress
   
3. department
   
4. name
   
5. givenname
   

1. Enter your ADFS IDP Single Sign On url on the printIQ settings page, search for PrintIQ_SAML_SingleSignOnServiceURL
   
2. Enter the HTTPS certificate thumbprint for encrypted transmissions – this will be the thumbprint of the HTTPS certificate serving printIQ requests, into the setting PrintIQ_SAML_CertificateThumbprint 
   
3. This certificate should also be used on your end for encrypted saml assertions (optional)
   
4. Search the settings page for “PrintIQ_SAML_AuthEnabled” and ensure the value is “Yes”
   

Notes for ADFS using SAML:

1. The url to use for sending saml requests to printIQ is {appPath}/saml.aspx e.g. https://mysite.printiq.com/saml.aspx
   
2. In previous implementations of ADFS using SAML – the IDP sign on page url has resembled the following url: https://xx.xx.xx.xx/adfs/ls/IdpInitiatedSignOn.aspx
   
3. From PrintIQ, the SAML Issuer will be your site URL, e.g. https://mysite.printiq.com/