Integration Documentation. Automated User Provisioning Common Logon, Single Sign On or Federated Identity Local File Repository Space Pinger

Transcription

1 Integration Documentation Automated User Provisioning Common Logon, Single Sign On or Federated Identity Local File Repository Space Pinger

2 Revision History Version No. Release Date Author(s) Description of Revision GGernert GGernert Hash Only added to valid landing pages Windows server 2008 on page 5 Copyright 2013 ioffice Inc. All Rights Reserved.

3 AUTOMATED USER PROVISIONING... 1 SUMMARY... 1 Import via SFTP... 1 Implementation Steps... 1 File Format and Requirements... 1 COMMON LOGON, SINGLE SIGN ON OR FEDERATED IDENTITY... 2 SUMMARY... 2 FEDERATED IDENTITY... 2 SAML WS Federation... 2 TOKEN AND HASH BASED... 2 Details... 3 URL... 3 Sample Hash Results... 3 Parameters... 4 Example Call... 4 LOCAL FILE REPOSITORY... 5 SUMMARY... 5 ATTACHMENT WORKFLOW... 5 REQUIREMENTS... 5 INSTALL PROCESS... 6 File Upload Component Setup... 6 Information Exchange... 6 Testing... 6 Troubleshooting... 6 SPACE PINGER... 7 SUMMARY... 7 HASH BASED... 7 Details... 8 URL... 8 Sample Hash Results... 8 Parameters... 8 Example Call... 8

4 Automated User Provisioning Summary This section describes options for importing users into the application from a corporate directory. An ioffice representative will work with the customer to understand needs and requirements, as each process varies based on module, customer and business requirements. Import via SFTP 1 The customer uploads a file to ioffice s SFTP server on an interval determined at their discretion. The SFTP account is exclusive to the customer, securely isolated from other customer accounts. The customer s developer has the option of using either a password or key based authentication. Implementation Steps ioffice creates an account on the SFTP server for the customer. Customer will upload the first file to the SFTP site and notify ioffice once the file is available. See the section titled File Format and Requirements below. ioffice builds a process according to the business rules provided by the customer. ioffice notifies the customer the process is online, customer begins sending the file at a regular interval. ioffice s directory watcher process will pick up the file and begin processing automatically. Customer can view process logs in the application under the Admin > Automated Process Logs section. File Format and Requirements File format options are flexible, allowing delimiter separated values (comma, tab, pipe) or XML. Delimited files must have a header row and fields should be qualified with double quotes. It is iofficeʼs experience that XML is the most reliable file format, as a closing element confirms a complete file has been received. ioffice requires a field with a unique key (such as an employee id). This key maps existing user records with data in the customer s file. Users in the file without a matching record in the application will have an account created for them. Accordingly, users in the application without a matching record in the file are deactivated. Matching user records are updated if required. Standard required fields are: employeeid (any unique identifier maybe used as a substitute), first name, last name and . Depending on use case, other fields may be needed. Partial data cannot be extracted from a column, the customer should provide any data to be imported in a separate defined columns. Download Sample XML Download Sample CSV 1 SSH file transfer protocol 1

5 Summary Common Logon, Single Sign On or Federated Identity This section describes options for what is known as common login, single sign on, or federated identity. This frees users from the need to maintain an additional user name and password for access to the application. Federated Identity ioffice supports a variety of federated identity options in partnership with Ping Identity. Specifics may vary between customers or protocol used. Business requirements define that the customer s user information be loaded during application configuration, because of this requirement just in time or on the fly user provisioning is not supported. This means that only an identifying attribute needs to be sent in the assertion (as the SAML_SUBJECT). SAML 2.0 Both IDp initiated and SP initiated Single Sign On/Single Log Out are supported with SAML 2.0. The customer will provide their entity id, base URL, end point URL(s) and signature verification certificate. The verification certificate may be an unanchored certificate. Alternatively, if the customer is using Ping Federate, the customer and ioffice have the option of exchanging a connection metadata file to automate the configuration process on both ends. Base URL: Endpoint: /sp/acs.saml2 Metadata: Download Certificate: Download WS-Federation Only RP initiated Single Sign On is supported with WS-Federation. The realm for use with WS-Federation in both staging and production is urn:iofficeconnect.com. The customer will provide their realm, base URL, end point URL and signature verification certificate. The verification certificate may be an unanchored certificate. ioffice will provide the signing certificate upon request. Endpoint: /sp/prp.wsf Certificate: Download Token and Hash Based The token and hash based interface is designed for customers that do not have an existing federated identity solution or are looking for a simple solution for use with their corporate intranet. 2

6 Details The customer s corporate intranet provides user authentication, generates a hash and forwards the user to a URL. The hash is used to verify the link was generated by an authorized source, such as the customer s corporate intranet. The hash is generated in part by using a salt and the user s identifying value. The salt is a string, similar to a password, provided to ioffice by the customer. Optionally, adding the current date (in GMT) ensures that the hash is only valid for twenty-four hours. Append the date to the hash using the YYYY-MM-DD format. URL The below address is the URL the customer s intranet will forward the user to. Parameters are accepted via HTTP POST or HTTP GET. Sample Hash Results The customer s developer verifies their hash implementation using the below samples. Pseudo code MD5("myemployeeid mysalt") MD5("myemployeeid mysalt ") MD5( my @example.com mysalt ) Hash Result d39b6b4e fd4f14b0f48fd071 d2c9cfea80e391cb79bc2bcc4a36448c fe5ffb4c5ab3378e46aed327e05c32eb 3

7 Parameters Name property user hash landing (optional) HASH ONLY Value Ex: employeeid, , username... The value used to identify the user (see property). A MD5 representation of the id, a salt, and optionally a date; these fields are be separated by the pipe character. A Landing Page to redirect the user to after logging in instead of the desktop (default). When used all users must have permission in the application to the desired landing page. The following are valid landing pages: SPACE_DESKTOP COPY_DESKTOP MOVE_DESKTOP MOVE_REQUEST Example Call As an example, a users browser would be directed to the below by the customer s intranet or back end systems. d39b6b4e fd4f14b0f48fd071 4

8 Local File Repository Summary This section describes the install process for the local file repository used with job ticket attachments. This functionality requires a Microsoft IIS server. The process involves installing an ISAPI plug-in called Tabs Upload and creating a url for use with a set of ASP pages. Attachment Workflow Requirements To enable the local file repository, an account with access to the application and at least center administrator permissions is required. In Windows server 2003 (32 or 64 bit) or higher "ASP Classic" must be enabled in IIS. In Windows server 2008, the ASP role under IIS must be enabled. Minimal CPU and memory not to exceed 10 GB. (Able to run IIS and execute ASP pages) Disk space varies by customer. (Depends on documents and retention period) Application works in a shared environment and on a virtualized machine (VM). 5

9 Install Process File Upload Component Setup Install Microsoft IIS and enable ASP Classic / ASP. Download the tabs upload software at: Run the appropriate Tabs Upload installer (x64 for 64bit Windows, x86 for 32bit), contact ioffice to receive your Tabs Upload license key. Create a new website or virtual directory in IIS. Move the contents of the asp folder to the websites home directory. The URL to this IIS site is referred to as the website URL. Create a folder on the server. IIS must have the appropriate security rights to read and write to this folder. This folder is referred to as the storage directory. Information Exchange Provide the internal website URL to ioffice. This can be either the local IP address or the DNS name. ioffice uses this to direct the users browser to the repository. Provide the storage directory to ioffice, this is used to direct the Tabs Upload application to store the files in the aforementioned directory. Testing To verify functionality, open up the web browser and head to the website URL. For example, If the website is setup correctly, the customer will see a simple file upload form. Log into the application. Create a new copy ticket, upload a file and submit the ticket. Log into the server, verify that the file was transferred to the storage directory successfully. Troubleshooting If the file is not in the storage directory, verify permissions on the folder and in IIS. Make sure appropriate permissions (read/write) have been set for the IIS account. Verify the website URL forwarded to ioffice. Check the server address, virtual site name, and full path. 6

10 Space Pinger Summary This section describes how to configure the Space Pinger. Implementation is very similar to the single sign on integration. The Space Pinger is commonly used to integrate into directory systems (e.g. Lotus Notes, Exchange) or lobby kiosks to view a live floor plan of an employee s location. Hash Based The hash based interface is a simple method of passing the needed information to the Pinger. 7

11 Details The customer s corporate intranet provides a unique key for the desired user, generates a hash and forwards the user to a URL. The hash is used to verify the link was generated by an authorized source, such as the customer s corporate directory. The hash is generated in part the target user s identifying value concatenated by a pipe ( ) and a salt. The directory pinger salt is a string, similar to a password, provided to ioffice by the customer. Optionally, adding the current date (in GMT/UTC) ensures that the hash is only valid for twenty-four hours. Append the date to the hash using the YYYY-MM-DD format. URL The below address is the URL the customer s intranet will forward the user to. Parameters are accepted via HTTP GET. Sample Hash Results The customer s developer verifies their hash implementation using the below samples. Pseudo code MD5("targetemployeeid mysalt") MD5("targetemployeeid mysalt ") Hash Result B3DE27CFB6AF571ADB5C C5BD83F8D7C476399B383605D03F4 Parameters Name method property target hash Value The value should always be hash when using this method Ex: employeeid, , username... The value used to identify the user (see property). A MD5 representation of the id (target), a salt, and optionally a date; these fields are be separated by the pipe character. Example Call As an example, a users browser would be directed to the below by the customer s intranet or back end systems. ployeeid&hash= 4E05717C11BAAAC91A95955BC8AEADD1 8