This document outlines the backend specifications of the CITI Program Single Sign On Portal.

SSO Developer Handbook This document outlines the backend specifications of the CITI Program Single Sign On Portal. 1 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

Revision Sheet Release No. Date Revision Description Rev. 0 05/25/2010 Created by Monique Boea Rev. 1 06/28/2012 Added HTTP Compression section Rebecca Palmberg Rev. 2 08/14/2012 Updated CITI Contact Email Address Rev. 3 01/16/2013 Updated to reflect CITI 2.0 changes CONTACTS Test Institution If you are interested in having a test institution created please contact: citisupport@med.miami.edu. Once the test institution is set up you may use it as a development environment for trying the Remote Login service. Get started To sign up for Remote Login Service please contact: citisupport@med.miami.edu. Once you are subscribed you will be given a unique Institution ID and Key. Hang on to these! Your IT staff/programmer will need them for the remote login scripts on your server. Technical Assistance For technical assistance please contact: monique@atlaref.org. 2 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

The CITI Single Sign On portal allows institutions the option to offer a remote login into the CITI Program website. Users can log in to the Institution s system, click on a specified URL which will automatically log the user into CITI (after the user is authenticated). Each Institution is responsible for developing the code on their respective servers which will be used to forward a user to the CITI servers for authentication. Visit http://citiprogram.desk.com/customer/portal/articles/235727-single-sign-on-and-automateddownloads-portal- to view code samples in the following languages: ASP COLDFUSION.NET PHP NOTE: These samples are not intended to be production level code. They are provided to illustrate the process of remote login. Your production implementation of remote login should take the process outlined by these samples and incorporate it into your existing code base. The following rules will ensure that the remote login process works successfully: Fields should be posted to the remote login URL at CITI: https://www.citiprogram.org/remotelogin.asp When a user is authenticated successfully, he/she will be redirected to if gotociti = yes : : https://www.citiprogram.org/members/index.cfm?pageid=50 You can use the following form to test submission prior to setting up your SSO links: https://www.citiprogram.org/ remoteloginform.asp 3 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

There are required fields that all institutions must pass to the remote login URL as well as optional fields. The following explains the fields which can be passed to the remote login URL. Please note required fields vs. optional fields. Description Field Name Field Type, Size or Acceptable Values When is the field required? Institution ID institution integer always required Login Key key 255 characters always required Institutional Username (unique within institution) instusername 50 characters required when CITI username and password are not provided CITI username (unique within CITI) username 50 characters CITI password password 50 characters First Name first 100 characters Last Name last 100 characters required when Institutional Username is not provided required when Institutional Username is not provided required for new learners, required when "Update Name and CITI Email" is "yes" required for new learners, required when "Update Name and CITI Email" is "yes" 4 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

CITI Email email 150 characters required for new learners, required when "Update Name and CITI Email" is "yes" New Institutional Username (unique in institution) instusernamenew 50 characters required when "Update Institutional Username" is "yes" New Username (unique in CITI) usernamenew 50 characters New Password passwordnew 50 characters required when "Update CITI Login" is "yes" required when "Update CITI Login" is "yes" Update CITI Login with "New Username" and "New Password" updatecitilogin yes or no (default) always required Update Institutional Username with "New Institutional Username" updateinstusername yes or no (default) always required Update Institutional Profile updateinfo yes or no (default) always required Update Name and CITI Email updatename yes or no (default) always required Allow User to Change Institutional Username allowchanges yes or no (default) always required Redirect to CITI web site gotociti yes or no (default) always required 5 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

(only applies to registered CITI members) New or Returning Learner type returning or new (default) always required Test login logintest yes or no (default) always required Institutional User ID instuserid 50 characters see note above, field is unique within institution Institutional Email instemail 150 characters see note above Gender gender 50 characters see note above Degrees degrees 50 characters see note above Employee Number employeenum 50 characters see note above Department department 255 characters see note above Research Role researchrole 255 characters see note above Address 1 address1 255 characters see note above Address 2 address2 255 characters see note above Address 3 address3 255 characters see note above 6 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

City city 50 characters see note above State state 50 characters see note above Zip/Postal Code zip 50 characters see note above Country country 50 characters see note above Custom 1 custom1 1000 characters see note above Custom 2 custom2 255 characters see note above Custom 3 custom3 255 characters see note above Custom 4 custom4 255 characters see note above Custom 5 custom5 255 characters see note above Learner Stages stages 255 characters see note above 7 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

There are 2 scenarios where a user is sent from the institution to the remote login form: 1. RETURNING USER - Users should be initially passed from the institution to the portal as a returning user. Returning is the default value if no type parameter is provided. The following fields are required for a returning user: INSTITUTION USERNAME (instusername) INSTITUTION KEY (key) INSTITUTION ID (institution) NOTE: If the INSTITUTION USERNAME (instusername) is not provided, the CITI username and password is required for all returning users. When the information is passed to the remote login form, it is processed by a stored procedure (stored proc) on the CITI Program server. Before the stored proc processes the user, it conducts a few institution level checks and will redirect the user accordingly i.e. ensure that the portal logins max has not been exceeded for this institution, ensures that the institution has remote access enabled, makes sure the correct login key was passed for the institution, etc. If the information passes the institution level validations, the stored proc will conduct RETURNING USER validations: a. Check to see if the user is affiliated with the institution within CITI i. If no, check to see if the CITI username and password has been provided 1. If not, show an error message. This user is not affiliated with the institution in CITI nor does he/she have a CITI account. The user must be resubmitted by the Institution as a NEW USER. ii. If yes, check to see if the user has an existing CITI account 1. If no, show an error message. 8 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

2. If yes, continue validating the data 3. If no errors, create affiliation with institution 4. OR, update profile if applicable 5. Continue with misc updates 2. NEW USER - If the user being submitted to the remote login form is not found in the system, the user s information must be resubmitted by the institution as a new user. The following fields are required when submitting a new user: INSTITUTION USERNAME (username) USER S FIRST NAME (first) USER S LAST NAME (last) USER S EMAIL ADDRESS (email) INSTITUTION KEY (key) INSTITUTION ID (institution) When the form is submitted, the remote login form ensures that the required fields listed above have been submitted. If not, an error message is shown for each missing field. 9 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

Before the stored proc processes the user, it conducts a few institution level checks and will redirect the user accordingly i.e. ensure that the portal logins max has not been exceeded for this institution, ensures that the institution has remote access enabled, makes sure the correct login key was passed for the institution, etc. If the information passes the institution level validations, the stored proc will conduct NEW USER validations: The stored proc conducts several validations on the data submitted for the user before processing i.e., ensure that the userid submitted is not currently in use; ensures that the user s name and email address have been submitted, ensures that the username submitted is not currently in use; ensures that the user does not have an existing CITI account. If the data is processed with no errors, the new user is added. Generate password, if not submitted Create username, if not submitted Add user to the appropriate tables in the CITI database Add user to tblmemberinstitutionsii Partner Affiliations Partner Affiliations allows users to affiliate with an institution other than the one that owns the portal. If the learner has an existing affiliation, neither the learner nor the institution needs know the CITI login to create the new affiliation. If the learner is coming through the portal for the first time and is not affiliated with the institution that owns the portal, they will have to know (or create) the CITI login, but this only will have to be done once. Another advantage of the partner affiliation is that the same institutional username can be used for each of the partner institutions. This makes it easy for the institutions to identify learners across institutions. 10 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

The following is an example of how/why partner affiliations are used: University X has several campuses. Their learners may be affiliated with more than one campus or they may switch campuses. A learner s institutional username for all campuses is the same. They want their learners who are affiliated with the University X West Campus to be able to affiliate with University X East Campus and have the same institutional username WITHOUT knowing their CITI username and password. By using partner affiliations, we can find them using their West Campus affiliation, create the East affiliation, and log them in. When a user is submitted to the remote login form, after being processed as a new or returning user, the system determines if the user needs to be affiliated with a partner institution. A partnered ID (intpartnerid) is required. The stored proc conducts various partner level validations, i.e. verify the institution, verify that the institution is set up for remote access, verify the login key, etc. After partner validations are passed, the system checks to ensure that there is no one else with the same userid. If the above validation passes, a member/ partner affiliation record is created OR the existing affiliation is updated. Member Log in When a submitted user passes all validations in the scenarios mention above, the system will automatically log the user into CITI. After a few database housekeeping steps, the user is forwarded to the CITI member area, if gotociti = yes : <!--- CITI success redirect URL ---> https://www.citiprogram.org/members/index.cfm?pageid=50 11 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

Error Messages There are several error messages that may occur when a user is submitted to the remote login form for various reasons. Here is a list of error messages and what the developer must do when each occurs: ISSUE: If the number of portal logins exceeds the max allowed -remote login denied, maximum logins exceeded RESOLUTION: There is a limit of 50 logins per minute for each institution through the portal. If you are testing the system using a script to login multiple users, set the logintest parameter to yes to bypass this limit. You will be able to test the remote login procedure, but the learners will not be logged in to CITI. If you are not testing the system, resubmit the login information. ISSUE: Institution does not have remote login access -remote login access denied RESOLUTION: Contact CITI support at citisupport@med.miami.edu to obtain remote login access. 12 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Institution ID was not provided -Institution missing RESOLUTION: Enter the institution ID and resubmit. If you do not know your institution ID, contact CITI support at citisupport@med.miami.edu. ISSUE: Invalid institution ID was provided -Institution invalid RESOLUTION: Enter the correct institution ID and resubmit. If you do not know your institution ID, contact CITI support at citisupport@med.miami.edu. 13 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Institution key is missing -institution key missing RESOLUTION: Provide the institution key and resubmit. If you do not know your institution key, contact CITI support at citisupport@med.miami.edu to obtain your login key. ISSUE: Wrong login key for institution -wrong login key RESOLUTION: Contact CITI support at citisupport@med.miami.edu to obtain your login key. 14 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Wrong ip address -ip invalid RESOLUTION: Your institution has requested that access only be allowed through specific IP addresses. These IP addresses must be on record with CITI. Contact CITI support at citisupport@med.miami.edu to obtain a list of valid IP addresses or register new ones. ISSUE: The user ID (instusername) is missing -user ID missing RESOLUTION: You are attempting to register a new member, but have not provided a user ID (instusername) for this member. Enter a user ID and resubmit. 15 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: First name is missing -first name missing RESOLUTION: You are attempting to register a new member, but have not provided a first name for this member. Enter a first name and resubmit. ISSUE: Last name is missing -last name missing RESOLUTION: You are attempting to register a new member, but have not provided a last name for this member. Enter a last name and resubmit. 16 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: CITI email address is missing -CITI email missing RESOLUTION: You are attempting to register a new member, but have not provided a CITI email address for this member. Enter a CITI email address and resubmit. ISSUE: If there is more than one person with this user ID at this institution - error: ## logins with user ID provided, user ID must be unique RESOLUTION: You have provided a value for the instusername parameter. ## members at your institution are using this value as their user ID. Each member s user ID must be unique within the institution. Provide a new user ID (instusername) for this member and contact CITI support at citisupport@med.miami.edu to find and remove the duplicate user IDs that have been recorded. 17 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Someone else at the institution is using this user ID - error: user ID already in use, user ID must be unique RESOLUTION: You are attempting to register a new member. The user ID (instusername) you have provided is already in use. Each member s user ID must be unique within the institution. Provide a different user ID (instusername) for this member and resubmit. ISSUE: Missing name or email - error: name or email missing RESOLUTION: You are attempting to register a new member and have not provided either the name or the email address. Provide the name and email address and resubmit. 18 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Duplicate username - error: username in use RESOLUTION: You are attempting to register a new member and the username provided is already being used by another member of CITI. Provide a different username and resubmit. ISSUE: User not affiliated with institution and username and password were not provided - error: learner not affiliated with institution, add learner or provide username and password RESOLUTION: A returning learner is attempting to login. The user ID (instusername) was provided, but was not found affiliated with your institution. Change the type of learner to new or provide the CITI username and password for the learner. 19 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: There is an existing registration - existing registration found with this email, username sent to {email address} RESOLUTION: You are attempting to register a new member. Someone has registered using the email address provided. The message shown below has been sent to the email address. Provide another email address or login the individual as a returning member. Subject: {Member Name} CITI registration information You attempted to register as a new user through the CITI portal at {Institution Name}. However, you already have a CITI registration with username, {username}. Please use this username to register through the {Institution Name} portal. If you need to contact us, call the CITI Office at the University of Miami at 305 243 9862 or send an email to citisupport@med.miami.edu. Paul Braunschweiger Ph.D. Professor, University of Miami Director Office of Research Education CITI Course Coordinator 20 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Person is not in database - error: learner not in database RESOLUTION: A returning learner is attempting to login. The CITI username and password were provided, but were not found. Change the type of learner to new or correct the CITI username and password. ISSUE: User ID or CITI username and password are required to login -user ID OR username and password required RESOLUTION: A returning learner is attempting to login. The user ID (instusername) or CITI username and password is required to login, but were not provided. Enter the user ID or the CITI username and password and resubmit. 21 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: If updating CITI login, and login is missing - error: must provide new citi login for update OR -new CITI username and password required to update CITI login RESOLUTION: Provide values for passwordnew and usernamenew parameters and resubmit. ISSUE: If updating user ID and new user ID is missing - error: must provide new institutional user ID for update OR -new institutional user ID required to update user ID RESOLUTION: Provide a value for the instusername parameter and resubmit. 22 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

Partner Affiliation Errors ISSUE: Institution does not have remote login access -remote login access denied for partner RESOLUTION: Contact CITI support at citisupport@med.miami.edu to discuss login access for the partner institution. ISSUE: Login key for partner institution was not provided -partner institution key missing RESOLUTION: Enter the partner institution key. If you do not have the key, contact CITI support at citisupport@med.miami.edu to obtain the login key for the partner institution. The partner login key is not the value partner institution submits as the key parameter to login through their portal. 23 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: Wrong login key for partner institution -wrong login key for partner {Name of Institution} RESOLUTION: Contact CITI support at citisupport@med.miami.edu to obtain the login key for the partner institution. The partner login key is not the value partner institution submits as the key parameter to login through their portal. ISSUE: User ID (partnerusername) is missing -user ID partner institution missing RESOLUTION: You are attempting to register a new member and have provided an institution ID for a partner institution, but you have not provided a user ID for the partner institution. Enter the user ID for the partner institution and resubmit. 24 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: There is more than one person with this user ID at this institution - error: ## logins with user ID provided, user ID must be unique for partner {Name of Institution} RESOLUTION: You have provided a value for the instusername parameter for the partner institution. ## members at the partner institution are using this value as their user ID. Each member s user ID must be unique within the institution. Provide a new user ID (instusername) for this member for the partner institution and contact CITI support at citisupport@med.miami.edu to find and remove the duplicate user IDs that have been recorded. ISSUE: User ID (partnerusername) is missing -user ID partner institution missing RESOLUTION: You are attempting to register a new member and have provided an institution ID for a partner institution, but you have not provided a user ID for the partner institution. Enter the user ID for the partner institution and resubmit. 25 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

ISSUE: If updating partner user ID and partner user ID is missing -new partner user ID required to update partner user ID RESOLUTION: Provide a value for the partnerusernamenew parameter and resubmit. 26 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

Frequently Asked Questions GENERAL Q. My institution is interested in using the portal. What are the technical requirements? A. You will need a programmer available to you at your institution. The programming language you choose to use is up to your institution. The CITI portal is currently accessed by institutions using Java,.NET, PHP, and ColdFusion. CITI will provide documentation, guidance, and code samples, but programming is required at the institution to use the portal. Interacting with CITI is as simple as submitting form data, but there is complexity involved in properly handling CITI's responses to your data. It is imperative for your programmer(s) to carefully review the documentation and code samples. CITI is constantly improving the documentation to improve and simplify interacting with the portal, but ultimately your programmer builds the interface your institution will use. The portal is not an "out of the box" solution. Q. What is the turnaround time for setting up portal access? A. There are many factors that determine how long the process will take. The number one factor is the amount of programming support you have available at your institution. A typical portal implementation currently runs around 4-6 months. See the FAQ on "interested in using the portal" for additional information. Q. Does my institution have to use both remote login and automated downloads? A. No, although they are bundled together the services work independently. You may use one without the other. Some institutions use a "phased approach" and choose to implement the automated downloads first because there is less complexity involved. Q. My institution currently has many users already using CITI. How can I set up portal access for them? A. Portal access is made available to users by associating existing CITI users with unique usernames at your institution (referred to as "institutional username" or strinstusername). CITI can furnish a spreadsheet of current CITI users for your institution. You then 27 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

provide the users' institutional user name in the spreadsheet and return it to CITI. A process is then run by CITI to set up the association. Q. My institution wants to attach a learnerid (or some other field) to each user in order to correlate downloaded reports with the users' records in another system at my institution. Is this possible? A. Yes. To accomplish this please provide CITI with the name of the field you'd like to add and indicate that you would like it made available in the reporting. See the FAQ "pass in custom data" for additional information. Q. My institution needs to export data from CITI and import it into another Learning Management System at our institution. How can we accomplish this? A. At this time there are 6 reports (each with a few variations). Each of those reports is made available via a secured URL. Your institution is given a "key" which is passed as a URL parameter to grant access to the report. The reports can be downloaded by 1. entering the URLs into a browser 2. setting up batch files to access the URLs 3. initiating HTTP requests from web programming languages such as ColdFusion, PERL, PHP, etc. CITI can provide sample batch files for you, but you will need a programmer at your institution to assist you with implementing them. At this time you will need to ask CITI for the list of reports. See the FAQ "attach a learnerid" for additional information. Q. In what formats are reports currently available? A. Comma-delimited (*.csv), Tab-delimited (*.txt), and Excel (*.xls) Q. Can I download reports nightly? Can I download reports every 3 or 4 hours? A. Yes and yes. You can download the reports on any schedule you set. 28 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

Q. Can reports be emailed to me or ftp'd to a lockbox? A. No. At this time you must initiate the download from a web browser or your system. DEVELOPERS/PROGRAMMERS Q. What is the minimum information required to login via the portal? A. institution, key, instusername, type="returning" Q. What fields are required to create a new user via the portal? A. institution, key, instusername, type="new", first, last, email Q. How do I pass custom data fields in via the portal? A. To pass in custom data via the portal you will need to pass the "updateinfo=yes" parameter and whichever custom field(s) you are using. The current custom field options are: custom1, custom2, custom3, custom4, custom5. See the FAQ "attach a learnerid" for additional information. Q. When attempting to log in a returning user via the portal I receive the following: "learner not affiliated with institution, add learner or provide username and password". How do I resolve this? A. There are two possible explanations for this error. The first is that CITI does not recognize the affiliation between the institutional user name (strinstusername) you are trying to log in and an existing CITI user. See the FAQ "users already using CITI" for an explanation of this affiliation. To set this affiliation you will need to prompt the user for their existing CITI username and password, append this information to your previously submitted data and resubmit to CITI. This will create the affiliation and subsequent logins will not require the CITI username and CITI password. The second explanation is that the user is actually a new user and has 29 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k

never used CITI. If this is the case you need to resubmit the data and change type="returning" to type="new" and additionally provide the following fields: first, last, email. This will create the CITI user and affiliate it to the institutional user name. Subsequent logins using "returning=yes" should work. Q. When attempting to create a new user via the portal I receive the following: "user ID already in use, user ID must be unique". How do I resolve this? A. The institutional user name (strinstusername) you are trying to use is already affiliated with an existing CITI user. You will need to resubmit with a unique institutional user name. Q. When attempting to create a new user via the portal I receive the following: "existing registration found with this email, username sent to abc@def.com". How do I resolve this? A. An existing CITI user has been found with the email address you are submitting. You should create an affiliation between that existing CITI user and the new user you are creating. See the FAQ "users already using CITI" for an explanation of this affiliation. To set this affiliation you will need to prompt the user for their existing CITI username and password, append this information to your previously submitted data and resubmit to CITI. This will create the affiliation and subsequent logins will not require the CITI username and CITI password. Q. How can I log successful logins to CITI? A. The most reliable method for logging successful logins is to pass "gotociti=no" and handle the redirect manually. If CITI returns a 37 character UUID then your user has successfully authenticated. You can then log in the user by redirecting them back to the SSO form: https://www.citiprogram.org/remotelogin.asp?uuid=xxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxx.xxxx (where XXXXXXXXXX would be the 37 character UUID). 30 P a g e C I T I S i n g l e S i n g O n P o r t a l D e v e l o p e r H a n d b o o k