NIH Login Technical Overview Installation Configuration and Basic

NIH Login Technical Overview: Installation, Configuration, and Basic Functionality

Section 1 Basic Functionality

How Site. Minder Works A simplified example 1. 2. Client makes request to Web Application with installed Web Agent checks with Policy Server to see if the requested resource is protected by Site. Minder. a. 3. 4. If client presented a cookie*, the cookie information is sent to the policy server, which determines whether it is current. If the resource is protected and no cookie is present, client is redirected to NIH Login. Upon successful login, NIH Login returns a cookie to the client and the client is returned to the application. * - This is a session cookie, valid in the current browser and any child windows. Closing the browser destroys the cookie and ends the session. Contact: NIHISCSupport@mail. nih. gov

Firewall Considerations The Web Agent, by default, interacts with the Policy Server on ports 44441, 44442 and 44443 If your firewall blocks all unspecified ports you will be required to open these ports for communication between your Web Agent and the Policy Server Contact: NIHISCSupport@mail. nih. gov

User Attributes Overview of user attributes for NIH applications such as NIH Login and NIH Federated Identity Service. User attributes information on authentication user directories, authorization user directories, core user attributes, NIH Active Directory attributes, NIH External Active Directory attributes, e. RA Commons OID, federation attributes, IMPACII, and special attributes. Contact: NIHISCSupport@mail. nih. gov

Authentication User Directories Authentication is validated against the following directories: NIH AD NIH External AD e. RA Commons OID Federation Store Contact: NIHISCSupport@mail. nih. gov

Authorization User Directories Authorization is validated against the following directories: IMPACII LDAP_ALL Contact: NIHISCSupport@mail. nih. gov

Core User Attributes There are 15 core user attributes. Five of these core attributes (SM_USER, USER_EMAIL, USER_AUTH_LOA, USERAUTHN_SOURCE, and USER_AUTHZ_SOURCE, bolded in the listing below) must be populated. Examples are included after each definition: Contact: NIHISCSupport@mail. nih. gov

Continued…. SM_USER = the user's authentication login ID for NIH Login SM_USER = smithjd USER_EMAIL = user's email address USER_EMAIL = smithjd@mail. nih. gov USER_AUTHN_LOA = authentication loa USER_AUTHN_LOA = 230 USER_AUTHN_SOURCE = authentication source user authenticated against USER_AUTHN_SOURCE = NIH-External USER_AUTHZ_SOURCE = authorization source the user is mapped against USER_AUTHZ_SOURCE = LDAP_ALL Contact: NIHISCSupport@mail. nih. gov

Continued… USER_UPN = the user's user principal name: *unique to NIH Login system* USER_UPN = smithjd@mail. nih. gov USER_DN = user's distinguished name USER_DN = cn = smithjd, ou = cit, ou = nih, dc = gov USER_UID = UID value for the username USER_UID = smithjd USER_FIRSTNAME = user's firstname USER_FIRSTNAME = Jane USER_LASTNAME = user's lastname USER_LASTNAME = smith USER_MIDDLENAME = user's middle name USER_MIDDLENAME = dawn Contact: NIHISCSupport@mail. nih. gov

Continued… USER_ADDRESS = user's address USER_ADDRESS = 123 NIH Boulevard Suite 500 Bethesda MD 20817 USER_ORG = users parent organization USER_ORG = NCI USER_TELEPHONE = user's telephone number USER_TELEPHONE = 3018721000 USER_GROUPS = user's groups USER_GROUPS = NCI, FDA The link to the Headers document http: //isc. nih. gov/ISCSupport/Login/User. Attributesfor. NIHApplications. docx Contact: NIHISCSupport@mail. nih. gov

NIH Login Specific Attributes There are several HTTP headers that are sent to the application that should be used by NIH Login internally. These attributes have the “HTTP_SM” prefix. However, there is one attribute, SM_USER, that the application can utilize. This attribute is populated by the log-in value the user used during successful authentication against a particular user directory. � � User directory NIH Active Directory User directory authentication attribute samaccountname NIH External Active Directory samaccountname e. RA Commons OID UID Federation UPN Contact: NIHISCSupport@mail. nih. gov

HTTP Headers The following HTTP headers are passed from Site. Minder to your application: REMOTE_USER HTTP_CONNECTION HTTP_CONTENT_LENGTH HTTP_ACCEPT_ENCODING HTTP_ACCEPT_LANGUAGE HTTP_COOKIE HTTP_HOST HTTP_USER_AGENT HTTP_SMTRANSACTIONID HTTP_HTTPS HTTP_REQUEST_METHOD HTTP_SMSDOMAIN HTTP_SMREALMOID HTTP_SMAUTHTYPE HTTP_SMSESSIONDRIFT HTTP_SMAUTHDIROID HTTP_SMAUTHDIRNAME HTTP_SMAUTHDIRSERVER HTTP_SMAUTHDIRNAMESPACE HTTP_COOKIE HTTP_SMUSERDN HTTP_SMSERVERSESSIONID HTTP_SMSERVERSESSIONSPEC HTTP_SMTIMETOEXPIRE HTTP_SMSERVERIDENTITYSPEC HTTP_SMAUTHREASON § These headers provide information including login name and domain. Headers can also be customized for your application. Contact: NIHISCSupport@mail. nih. gov

Determining Level of Assurance The authentication level of assurance (LOA) is determined by evaluating the USER_AUTHN_LOA header value. Since NIH Login is able to authenticate users with different credential types (such as user name/password, client certificates, smartcard certifications, federation assertions, etc. ), the system uses a ranged approach to the NIST 800 -63 level of assurance values (1 -4). This allows the application to know what authentication mechanism was used during authentication and allow only specific authentication credentials to access a resource. For example, an application could be setup to only allow level 4 NIH issued PIV card certificates (USER_AUTHN_LOA = 460) and not allow FDA PIV card certificates (USER_AUTHN_LOA=440). 800 -63 LOA NIH Login LOA Range 1 100 -199 2 200 -299 3 300 -399 4 400 -499 Contact: NIHISCSupport@mail. nih. gov

Section 2 Supported Systems

Supported Systems Operating Systems: ◦ Windows – NT, 2000, 2003, 2008 ◦ Solaris – 8, 9, 10 ◦ HP-UX – 11. 0, 11 i ◦ AIX – 5. 1, 5. 2 ◦ Red Hat Linux – AS 2. 1, AS 3. 0 Web Servers: ◦ Apache – 1. 3, 2. 0, 2. 2 ◦ Microsoft IIS – 4, 5, 6, 7 ◦ Others include: Sun One, IBM HTTP, Domino, Apache variants q Not all OS/web server combinations are officially supported. Support matrix available. Contact: NIHISCSupport@mail. nih. gov

Application Servers Tomcat, JBoss, etc. Many NIH Login clients are using application servers such as Tomcat or JBoss. These – and most open source utilities – are not officially supported by Netegrity. The simplest way to use NIH Login to protect these resources is to install Apache and the mod_jk module – Netegrity-supported resources - on the web server. More information is available by contacting the NIH Login team (see contact information below). Contact: NIHISCSupport@mail. nih. gov

Section 3 Installation / Configuration

Installing The Web Agent Windows – Before You Begin Installation on Windows requires the creation of a local user with Administrator privileges ◦ Systems Administrators should coordinate with the NIH Login team in creating a username and password since these credentials must be known by the Policy Server A web server should be installed prior to configuration of the Web Agent Contact: NIHISCSupport@mail. nih. gov

Installing The Web Agent Windows Installation on Windows is a simple process that uses the Install Wizard. This is essentially a “double-click. ” ◦ Most installations are done in the default directory (under Program Files), but you should be prepared to choose another directory if required for your server. You may choose to run the installation yourself or provide remote access to a member of the NIH Login team who will gladly perform the installation for you. Installation is followed by configuration. Contact: NIHISCSupport@mail. nih. gov

Configuring The Web Agent Windows When you are ready to install your web agent, the NIH Login team will provide you with: ◦ ◦ Agent Configuration Object name Host Configuration Object name IP Address of Policy Server Administrator username and password The simple Web Agent Configuration Wizard will allow you to enter this information. It will: ◦ Register your host with the Policy Server ◦ Create the SMHost. conf and Web. Agent. conf files Note: Configuration for Apache on Windows is a slightly different process. Information is available upon request. Contact: NIHISCSupport@mail. nih. gov

Configuring The Web Agent Windows 2003/IIS 6 – Special Considerations IIS 6 on Windows 2003 requires additional configuration if you are employing its capabilities for virtual servers running in isolation mode A Netegrity “tech note” is available to support configuration for IIS 6 and can be provided by the NIH Login Team Basic steps: 1. Remove Web Agent ISAPI filter from default web site and place it under appropriate virtual server 2. Configure “Wildcard Application Maps” to load ISAPI DLL 3. Enable Web Agent DLL as a “Web Service Extension” 4. Map extensions to Sm. PWServices. CGI. exe in both /pw/ and /pw_default/ directories Contact: NIHISCSupport@mail. nih. gov

Installing The Web Agent Unix Installation on Solaris begins by unpacking the. tar file that the NIH Login team will send you The Web Agent is installed by running the nete-wainstall utility from the directory where the. tar file was unpacked ◦. /nete-wa-install Installation is followed by host registration and configuration of the Web Agent. Contact: NIHISCSupport@mail. nih. gov

Configuring The Web Agent Unix When you are ready to install your web agent, the NIH Login team will provide you with: ◦ Agent Configuration Object name ◦ Host Configuration Object name ◦ IP Address of Policy Server Configuration is controlled by the nete-wa-config utility found in the install directory. ◦. /nete-wa-config Contact: NIHISCSupport@mail. nih. gov

Configuring The Web Agent Unix – Continued The configuration script will ask you a series of questions including the names of agent and host configuration objects ◦ Note: Configuration for Apache is an explicit option. Answer “N” when prompted to install for Netscape or i. Planet The httpd. conf must be modified to load the Site. Minder Apache module. The following line must be added: ◦ Load. Module sm_module <path>/mod_sm. so ◦ Note: The module name in the previous line may vary among operating systems and Web Agent versions. Please see the provided Web Agent Installation Guide. The Web Agent Installation Guide Provides detailed instructions for configuring your Web Agent Contact: NIHISCSupport@mail. nih. gov

Can I Point to a Different Tier? Smreghost utility As your application moves from Development to Staging to Production, it is preferable to have separate machines for each. At times however, there are good reasons for simply pointing your machine to a different Policy Server. ◦ Site. Minder provides a utility called smreghost. This allows you to: ◦ ◦ ◦ Change the Policy Server to which your Web Agent points Generate a new SMHost. conf file Register your host with the Policy Server to which you are moving You will: ◦ ◦ Example: You have a new application that exists only on one machine (or set of machines). You have completed configuration and development and wish to promote this machine up the line to Staging and/or Production with the intention of later adding boxes for the lower tiers. Run smreghost Backup or delete your old SMHost. conf file Place your new SMHost. conf file in the proper location Restart your web server Smreghost is documented in the Web Agent Installation Guide. Values will be provided to you by the NIH Login team for the following syntax: ◦ smreghost -i <policy_server_IP_address: [port]> -u <administrator_username> -p <Administrator_password> -hn <hostname_for_registration> -hc <host_configuration_object> Contact: NIHISCSupport@mail. nih. gov

Section 4 Sample Code

Putting It All Together When the user is returned to the application from NIH Login, the HTTP headers are populated with appropriate information from the Active Directory. This information may be accessed by adding code to the application. The following slides contain samples in several scripting languages. Contact: NIHISCSupport@mail. nih. gov

ASP The following string variable will contain all Site. Minder and UI variables Complete. Header. String = Request. Server. Variables("ALL_RAW"); A function to retrieve the username Function Get. SMUser. Name() on error resume next Dim arr. All. Raw, tmp. User_Name, i arr. All. Raw = split(replace(Request. Server. Variables("ALL_RAW"), VBCRLF, ": ") for i=0 to Ubound(arr. All. Raw)-1 if Right(Trim(arr. All. Raw(i)), 7)="SM_USER" then tmp. User_Name = UCase(Trim(arr. All. Raw(i+1))) exit for end if next Contact: NIHISCSupport@mail. nih. gov

. NET The following code sample retrieves the user’s first name, last name and email address str. User. Email = (string)Request. Headers. Get("UI_mail"); str. User. Full. Name = Request. Headers. Get("UI_sn")+" " + Request. Headers. Get("UI_given. Name"); Contact: NIHISCSupport@mail. nih. gov

Java The following code retrieves the username and email address username = request. get. Header("SM_USER"); user. Email = request. get. Header("UI_mail"); Contact: NIHISCSupport@mail. nih. gov

Contact Information

More Information For more information, please contact: ◦ Jeff Erickson – Erickso. J@mail. nih. gov ◦ NIH Login support group – Support@mail. nih. gov Contact: NIHISCSupport@mail. nih. gov