Topic Doc: Single Sign-On
RecTrac 3.1 - Single Sign On
Table of Contents
Document Summary
This document discusses integrating RecTrac and/or WebTrac with your organization's Single Sign-On (SSO) system. With SSO, your organization has a single point of authentication after which integrated applications will launch without asking for additional credentials. This is convenient for your users, who have just a single set of credentials to remember to launch multiple applications. The RecTrac and WebTrac Single Sign-On Interface is free.
- RecTrac - Use Shibboleth or Microsoft Active Directory for your SSO.
- WecTrac - Use Shibboleth for your SSO.
Overview - Shibboleth
Shibboleth is an open-source project providing Single Sign-On (SSO) capabilities (see Shibboleth Consortium for additional information). You can use Shibboleth with RecTrac and/or WebTrac depending on your organization's SSO needs.
- For RecTrac - Your organization might have a SSO page used by employees, after which they can launch RecTrac and other programs as is needed.
- For WebTrac - Universities might have a SSO page for students, after which they can launch WebTrac to register for activities or register for sports.
Overview - Active Directory
Active Directory is Microsoft's trademarked directory service that automates network management of user data, security and distributed resources.
What Does Active Directory Do for You in RecTrac?
- Allows you to restrict which users on your domain are allowed to log into RecTrac.
- Allows RecTrac Users to bypass the RecTrac login and go straight into RecTrac upon logging into Windows. This is accomplished by linking a Windows User ID to a RecTrac User ID within User Management.
Before You Begin
This document is written with the following assumptions. If any of the items listed is NOT true, contact Vermont Systems Support prior to continuing.
- In order to complete the process in this document, it is assumed that you are the network IT administrator, with great familiarity with your organization's network and all needed information.
- You must implement and be fluent in your organization's Microsoft's Active Directory or Shibboleth systems prior to completing this document. As this document does NOT provide detailed instructions for the installation or use of Active Directory or Shibboleth.
- You must be comfortable editing XML documents.
- Your organization is running RecTrac 3.1.05.02 or greater.
- You understand RecTrac Profile Management and hierarchy.
- You understand RecTrac User Management.
Setup Steps
This document will walk you through the basic steps required to set up and link a Single Sign-On profile and to configure your system to allow RecTrac users to bypass the RecTrac Login.
If you have additional questions about Single Sign-On after reading this document, please contact Vermont Systems Customer Service by phone at 877-883-8757 or generate a Support Case through the Customer portal of the Vermont Systems web site using your Customer ID and password.
File Maintenance Setup
Shibboleth
Download and then run the latest version of the Shibboleth Service Provider (https://shibboleth.net/downloads/service-provider/) as an administrator on your RecTrac server. Shibboleth needs to be also installed on the WebTrac server ONLY if your department uses WAN or if you plan to use Shibboleth with WebTrac.
Configuring the Shibboleth Service Provider
To configure the Shibboleth Service provider two files need to be changed: shibboleth2.xml and attribute-map.xml.
Editing Shibboleth2.xml
- In Windows Explorer, browse to \opt\shibboleth-sp\etc\shibboleth\ or the path Shibboleth SP was installed to in the instructions above.
- Open the Shibboleth2.xml in an XML or text editor.
- In the opening SPConfig XML tag, add the following attribute:
xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata" - Under the InProcess tag • ISAPI tag • and Site tag. Change name="sp.example.org" with the DNS name for your web server. For Example: webtrac.myuniversity.edu.
- Make sure the id is set to 1 for the Default Website in IIS. If WebTrac is installed in a different site you can find the id of that site in IIS (Choose the Website, click on Advanced Setting, and click in the list of properties using the ID property).
- Under the RequestMapper tag • Request Map tag • and Host tag.
- Find name="sp.example.org and replace the sp.example.org with the DNS name for this web server. For Example: webtrac.myuniversity.edu.
- RecTrac: Under the Host tag, add a new <Path> tag entry. <Path name="retrac/wbwsc" authType="shibboleth" requireSession="false"/>.
- WebTrac: Under the <Host add a new <Path> entry which is securing the WebTrac path. Replace webtrac/wbwsc with the relative path to the WebTrac wbwsc folder: <Path name="webtrac/wbwsc" authType="shibboleth" requireSession="false"/>.
- Under the ApplicationDefaults tag:
- Change the entityID="https://sp.example.org/shibboleth" property to the web server DNS name. For Example: https://webtrac.myuniversity.edu/shibboleth.
- Under the ApplicationDefaults • Sessions tag change the checkAddress and handerSSL attribute values to true and the cookieProps value to https.
- Replace the entirety of the ApplicationDefaults tag • Sessions tag • SSO tag to look as follows <SSO>SAML2</SSO>.
- Under the ApplicationDefaults tag • Errors tag, update the supportContact address to the email that will be used for issues with login.
- Save the file and restart the Shibboleth Windows Service via Services.
Retrieving Service Provider Metadata
- Open a web browser and go to https://webtrac.<myuniversity.edu>/Shibboleth.sso/Metadata replacing <myuniversity.edu>with your proper DNS name.
- The URL is case sensitive.
- The metadata may be displayed in the browser or you might be asked to save the file. Save this file to a known location, if needed.
- Open the file in a text editor, or if saved as a *.xml file type, you can open it in your browser directly.
- Make sure there are no entries of sp.example.org in this file.
- Exit the file when done.
Creating a RecTrac SSO Shibboleth Profile
If using Shibboleth for RecTrac single sign-on, complete this section.
- In RecTrac, search for and go to Profile Management.
- Highlight/select your SSO profile with a Shibboleth subtype and click Change.
- For the HTTP Header Name field, identify the attribute to share between RecTrac and Shibboleth to uniquely identify this user on your organization's network. This value usually starts with HTTP_ and will be the attribute that will be sent from the Identity Provider. For instance if the Identity Provider sends the Employee Id as an attribute through the SSO process, that attribute is named employeeId then the HTTP header will be called HTTP_EMPLOYEEID. RecTrac's OpenEdge/Progress environment is not Case Sensitive (either uppercase or lowercase will work).
- The Logout Destination field might be one of three (3) different values. This configuration determines whether or not to end the Shibboleth session, and where the user's web browser navigates to when ending a RecTrac session. You may or may not want to end the Shibboleth session. Keeping the Shibboleth session open enables the user to open other single sign-on programs within your network without entering credentials again.
- First, you can log out of RecTrac without ending the Shibboleth session, and return to the RecTrac login page. The first option leaves this field blank/empty. The user is automatically redirected to a RecTrac screen with a message "You have successfully logged out of RecTrac. It is strongly advised that you close your browser to ensure that you complete the logout process."
- Second, you can end the RecTrac Session, end the Shibboleth session, and return to the Shibboleth login page. The second option uses the SSO Logout URL for this field. For Shibboleth, this is usually the domain URL with /Shibboleth.sso/Logout at the end of the URL. For Example: The user might be redirected to the following URL: https://rectrac.myparks.org/Shibboleth.sso/Logout.
- Third, option ends the RecTrac session, ends the Shibboleth session and returns you to the RecTrac login page. The third option begins with the URL from option 2 and ends with an additional value, return=<RecTracLogoutURL>. For Example: https://rectrac.myparks.org/Shibboleth.sso/Logout?return= where rectraclogoutURL is their RecTrac URL + &Logout=yes.
- Click Save to save your changes. You will return to Profile Assignments.
- In Profile Assignments, assign the SSO Shibboleth profile to the Default Level.
- In User Management, assign the Single Sign-On Cross Reference for each user (could be an Employee ID that ties a RecTrac user with a single sign-on user on your network). This needs to be the value that is returned from step #3 within this section.
Creating a WebTrac Parameters Profile
If using Shibboleth for WebTrac single sign-on, complete this section.
- In RecTrac, search for and go to Profile Management.
- Highlight/select your WebTrac Parameter profile and click Change.
- Change the Login Destination to the following:
https://<webtrac.myuniversity.edu>/Shibboleth.sso/Login?target=https://<webtrac.myuniversity.edu>/webtrac/wbwsc/live.wsc/login.html?Action=SSOProcess.- Replace <webtrac.myuniversity.edu> with the proper web server DNS name.
- Change the WebTrac wbwsc file location, if needed.
- Change the Logout Destination to the following:
https://<webtrac.myuniversity.edu>/Shibboleth.sso/Logout?return=https://<webtrac.myuniversity.edu>/webtrac/wbwsc/live.wsc/splash.html.- Replace <webtrac.myuniversity.edu> with the proper web server DNS name.
- Change the WebTrac wbwsc file location, if needed.
- If desired, use the return= portion of the URL to specify any URL outside of WebTrac to return your users.
- Change the Allowed Referrer to the IdP domain name with an asterisks at the end for wildcarding all applicable URLS on that domain. For Example: https://idp.myuniversity.edu/*.
Note: Vermont Systems does not assist in the configuration of IDP servers or IDP software configuration.
- In the Login Settings group, set the Login Match 1 field to "External FMID."
- In the New/Forgotten Settings group, set the Allow Password Changes and Require Password Change on 1st Login field values to "No."
- Click Save to save the changes. You will return to Profile Management. Proceed to the next section.
Creating a WebTrac Single Sign-On Profile
If using Shibboleth for WebTrac single sign-on, complete this section.
Note: Prior to completing the steps in this section, Vermont Systems recommends creating Splash Page Comment Codes called ShibbolethStart and ShibbolethFail. These are needed for Steps 5 and 6. Comment Codes are maintained in Comment Code Management.
- In RecTrac, search for and go to Profile Management. Click Add.
- Choose "WebTrac Single Sign-On" as your Profile Type and Profile Subtype. Enter a Profile Code and Description as needed and click Create.
- Set the SSO Method to Shibboleth
Note: If your organization wishes to use both a Public and a Private WebTrac Interface Parameter, then they MUST each be created and assigned to the WebTrac Single Sign-On profile. See the on-screen help for more details.
- Set the Start URL to a location where a user can start the login process. Vermont Systems recommends making a Splash Page Comment Code called ShibbolethStart and using the example URL:
https://webtrac.myuniversity.edu/webtrac/wbwsc/live.wsc/splash.html?InterfaceParameter=PrivateInterface&ccode=ShibbolethStart.- Modify the URL according to your WebTrac setup and the proper interface parameter record.
- Contents of this comment code would have a link to the WebTrac login page.
- Set the Fail URL to a location where a user will be redirected if the WebTrac SSO login fails. Vermont Systems recommends making a Splash Page Comment Code called ShibbolethFail and using the example URL:
https://webtrac.myuniversity.edu/webtrac/wbwsc/live.wsc/splash.html?InterfaceParameter=PrivateInterface&ccode=ShibbolethFail .- Modify the URL according to your WebTrac setup and the proper interface parameter record.
- Contents of this comment code would have an error message and someone to contact in case of error.
- Set the HH/FM Not Found Option to the option in case the HH is not found during login. Use the "i" Information icons on the screen for field definitions, if needed.
- On the Shibboleth Settings group, set the Shibboleth CGI Attribute accordingto the Attribute the Service Provider will give WebTrac during login.
- By default this is HTTP_EPPN.
- If you are not sure what this is, you can enable Output CGI Values to log and, as long as WebSpeed debugging is on, it will output all of the values during login to the log file so you can find the proper CGI name.
- Click Save to save your changes. You will return to Profile Assignments.
- Link the WebTrac Single Sign-On profile to the Default level of the Hierarchy.
- In the Available Profiles left-hand column, click to highlight the WebTrac Single Sign-On profile you just created.
- Click again and hold the mouse button down. When you have "grabbed" the profile, a red box will appear that displays the profile name.
- Drag and drop. Drag to the Default folder in the middle column. When the box turns green, release the mouse. The Profile will be linked. Profile Assignments are saved automatically. Changes take effect immediately.
- Exit back to the main menu.
Active Directory
- Active Directory - File Maintenance is minimal for Active Directory in RecTrac. To set this up, you will create and link an SSO (Single Sign-On) profile of the Active Directory subtype. You will also link Windows IDs on your Domain to RecTrac User IDs. The following sections will walk you through this process.
Note: All file paths and screen/tab locations in this document refer to file paths and screen/tab locations as they appear in the standard, default Vermont Systems design. Your setup and design may vary.
Creating and Linking an Active Directory SSO Profile
- In RecTrac, search for and go to Profile Assignments.
- Click Add.
- Enter a Profile Code.
- Expand the Drop-down list for Profile Type and select SSO. Expand the Drop-down list for Profile Subtype and select Active Directory.
- Enter a Profile Description.
- Click Create. You will continue to the Profile Update screen.
- Determine your Bypass RecTrac Login/Authentication Method option. The Bypass RecTrac Login and Authentication Methodfields work independently of each other and dictate how your Active Directory SSO Profile works.
- Select the Bypass RecTrac Login option to use Bypass Logic and allow RecTrac users to skip the RecTrac login dialog and go straight into RecTrac from a shortcut or bookmark upon logging into Windows with their Windows ID.
OR
Use Authentication Method. Authentication Method allows users to log into RecTrac using their Windows login credentials at the RecTrac login dialog.
To use Authentication Method, leave the Bypass option de-selected and make a selection from the Drop-down list.- Authenticate User on Backend Server - The system will look to your RecTrac Server and its Domain to authenticate the match between a Windows ID and a RecTrac ID.
- Authenticate User on Local VIC - The system will use VIC (Service or EXE) to authenticate the match between the a Windows ID and a RecTrac ID.
- Refer to How Bypass Logic Works below for examples.
Notes:
- If using Bypass Logic (when the Bypass RecTrac Login option is enabled), Vermont Integration Client (VIC) is required on the workstation, either as a Service or .EXE. VIC is the only way for RecTrac to obtain the Windows User ID that is logged into the workstation.
- Vermont Systems Hosted Customers cannot use the "Backend Server" Authentication Method because the Hosted Domain is its own domain, unrelated to your Domain.
- The Local VIC Authentication Method assumes VIC is installed on the Windows workstation being used to access RecTrac, either as a Service or an .EXE.
- Select the Bypass RecTrac Login option to use Bypass Logic and allow RecTrac users to skip the RecTrac login dialog and go straight into RecTrac from a shortcut or bookmark upon logging into Windows with their Windows ID.
- Enter the domain for which you are granting login rights. For Example: PARKSDEPARTMENT.net, if you want to include the entire domain
OR
DC=PARKSDEPARTMENT,DC=.net, if you want to use Groups.Note: As described above, you can search the entire Domain (i.e. PARKSDEPARTMENT.net) OR you can start the search for Active Directory Groups used by RecTrac at a selected branch in the Active Directory structure. To do this, enter a starting point in the format DC=PARKSDEPARTMENT, dc=net. Users who want to use this feature need to know their Active Directory structure and Active Directory acronyms as well. Vermont Systems advises you to use one option or the other. Do not mix and match between fields.
- Enter the starting point within your Active Directory that you would like to begin looking for users, OR leave this field blank to search for all users. See the Note: above.
- Enter the starting point within your Active Directory that you would like to begin looking for workstations, OR leave this field blank to search for all computers. See the Note: above.
- Enter the name of the Group(s) that will be allowed to log into this workstation. To enter multiple groups, separate entries by a comma and no space. For Example: aquatics,frontdesk.. Leave this field blank to allow access from users in any/all Groups.
- Enter the name of the User(s) that will be allowed to log into this workstation. To enter multiple users, separate entries by a comma and no space. For Example: marks,michaelp. Leave this field blank to allow access by any/all User IDs.
- Click Save to finish the Profile creation process. The Profile Assignments screen opens.
- The Active Directory SSO Profile should be linked at the Default Level of the Profile Hierarchy.
- In the Linked Profiles middle column, click to expand the Default folder. Click again to expand the Default Profiles folder.
- In the Available Profiles left-hand column, click to highlight the Active Directory profile you just created.
- Click again and hold the mouse button down. When you have "grabbed" the profile, a red box will appear that displays the profile name.
- Drag and drop. Drag to the Default folder in the middle column. When the box turns green, release the mouse. The Profile will be linked. Profile Assignments are saved automatically. Changes take effect immediately.
- Remain logged into RecTrac under your current session and proceed to the next section. Upon completion of the next session, Vermont Systems strongly recommends testing your set up on a separate workstation - with a separate Windows User ID and RecTrac User ID - to ensure you receive desired results before exiting from your current session. Exiting RecTrac with an Active Directory SSO Profile linked at the Default Level of Hierarchy may prevent you from logging back in the event your set up is not accurate.
How Bypass Logic Works
For Bypass RecTrac Login logic to work, the system must find a match between the Windows User ID and the RecTrac User ID. This setting is maintained by the Network Logon field on the User's RecTrac User ID in User Management as illustrated in the image below.
In the example below, the RecTrac User ID is "DIR" and the Network Logon is "Davidh," and the Bypass RecTrac Login option on the Active Directory SSO Profile is enabled.
- When "Davidh" logs into Windows, he will log directly into RecTrac upon clicking the RecTrac desktop icon or selecting the RecTrac bookmark in his browser. A second login will not be required. He will log into RecTrac as the "DIR" user because the system will find the match.
- IF the Network Logon field for RecTrac User ID "DIR" was blank, then the DIR user would NOT bypass the RecTrac login screen when Davidh logs into Windows because no match would be found.
If opting NOT to enable the Bypass RecTrac Login option, then Authentication Method will be used. Upon login to Windows, Davidh could click his RecTrac shortcut and log into the "DIR" RecTrac User ID with his Windows credentials. This is a good option if your intention is to limit the number of User IDs and passwords a user must memorize.
Note: As of RecTrac 3.1.06.14 (and later), RecTrac Usernames and Active Directory - Windows Usernames can be the same. Using the example here, the Active Directory domain login for Windows is Davidh. 'Davidh' could also be the RecTrac user name.
Linking RecTrac User IDs to their Windows User ID
Active Directory allows users to:
- Log into Windows and go directly into RecTrac from a desktop icon or browser bookmark without having to log in again. This is the Bypass RecTrac Login option and is a good choice if your intention is to expedite the login process for RecTrac.
- Log into Windows and then log into their RecTrac User ID using their Windows login credentials at the RecTrac login screen instead of their RecTrac User ID and password. This is the Authentication Method and is a good choice if your intention is to minimize the number of User IDs and passwords your users must memorize.
For users to do either option outlined above, the system must find a match between the user's Windows User ID and his/her RecTrac User ID. This setting is maintained by the Network Logon field on the User's RecTrac User ID in User Management. Steps for this are provided below.
- In RecTrac, search for and go to User Management.
- Highlight/select a user within the DataGrid and click Change.
- Click Build Windows User List. The system will display a list of all Windows user logins that are allowed to log into RecTrac.
- This button works only if an Active Directory SSO Profile is linked.
- Expand the Network Logon User List Drop-down list and select the appropriate Windows User ID. The ID you select will populate the Network Logon field above.Note: To clear the Network Logon field, expand the Network Logon User List Drop-down list and select "None."
- Click Save. You will be returned to the User Management DataGrid.
- Repeat these steps for each applicable RecTrac User ID.
OR
Exit to the main menu when done. - Remain logged in to RecTrac under your current session. Vermont Systems strongly recommends testing your setup on a separate workstation - with a separate Windows User ID and RecTrac User ID - to ensure you receive the desired results before exiting from your current session. Exiting RecTrac with an Active Directory SSO Profile linked at the Default Level of Hierarchy may prevent you from logging back in the event your setup is not accurate.
RecTrac Login with an Active Directory SSO profile Linked
- You can optionally bypass the RecTrac login screen when the Active Directory SSO Profile is set to Bypass AND a Windows User is associated with a RecTrac User in User Management.
- When you land on the RecTrac Login screen, you have the option to either your RecTrac User ID/password to login to RecTrac OR you can use your Windows User ID/password to login to RecTrac
- You land on the RecTrac login screen either because Bypass is DISABLED or because you're logged out of RecTrac.