JOSSO 2.4. Internet Information Server (IIS) Tutorial

JOSSO 2.4 Internet Information Server (IIS) Tutorial

JOSSO 2.4 : Internet Information Server (IIS) Tutorial

1. Introduction... 1 2. Prerequisites... 2 3. Defining Identity Appliance Elements... 3 3.1. SAML Service Provider... 3 3.2. JOSSO 1 Resource... 3 3.3. Windows IIS Execution Environment... 3 4. Activating the Execution Environment... 5 4.1. Installing Agent Resources... 5 4.2. Configuring IIS... 6 4.2.1. Windows Registry Configuration... 6 4.2.2. Create JOSSO Agent Application... 7 4.2.3. Setup JOSSO ISAPI Filter... 7 5. Partner Application Integration... 9 5.1. Accessing the Security Context... 9 5.2. Triggering login and logout explicitly... 10 iii

Chapter 1. Introduction Normally you will install an agent in each container that will host SSO partner applications. For example, if you have applications deployed on IIS and Apache, you will have to install an agent in each container. Agents are part of the Service Provider (partner application) runtime environment. The ISAPI (Internet Server Application Programming Interface) JOSSO Agent enables transparent Single Sign-On capabilities to web assets, such as ASP pages and.net applications, thus allowing seamlessness integration without any programmatic intervention. Once installed, the agent will create a local security context that IIS applications can access to obtain information about the current user: identity, properties, roles/groups. As with every JOSSO Agent, the ISAPI Agent must rely on a working Identity Provider for handling the full lifecycle of a single sign-on session, from establishment to disposal. The Identity Provider role must be realized through a configured JOSSO 2 Identity Appliance instance. This tutorial describes the different steps required to install the JOSSO ISAPI Agent and establishing user identity on sample ASP application using the available SSO security context. 1

Chapter 2. Prerequisites Before starting, make sure that the following prerequisites are meet. JOSSO 2.4.x instance Internet Information server (v6, v7 or v7.5) IIS application resource 2

Chapter 3. Defining Identity Appliance Elements The first step is to define the elements that represent your application and execution environment in the Identity Appliance. The following components must be added to the model: SAML Service Provider: JOSSO 1 Resource: The resource represents the IIS application, it holds information about the application base URL Windows IIS Execution Environment: This elements represents the IIS server where the application is running. Here you can specify the server architecture, agent install folder, etc. Once the appliance is compiled, JOSSO will create several configuration resources that will be used to install the agent in the IIS server, based on the different elements' properties. 3.1. SAML Service Provider This element represents SAML 2 services for the application, with JOSSO 2 you can SAMLenable. For details on how to modify the default SAML options refer to JOSSO 2.4 reference guide. Use a lower-case meaning full name for the SP, in our example we selected partnerapp-sp 3.2. JOSSO 1 Resource This elements represents a web resource/application that uses a JOSSO agent as SSO enabling mechanism. In this case, this represents our ASP application. The key properties are name and location. The name should also be a meaningful value describing the application (i.e. crm). It is also a good practice using a value similar to the one selected for the Service Provider (SP). For this tutorial partnerapp was selected. The location property refers to the application base URL (i.e. http://www.mycompany.com). In this tutorial the application is actually not the entire site, but resources under the /partnerapp path. The configured location is: http:// www.mycompany.com:80/partnerapp 3.3. Windows IIS Execution Environment The final element is the execution environment. The Windows IIS Execution Environment has information used to install the JOSSO ISAPI Agent. The key properties are: Property ISAPI Agent URI Description This is a special path that the agent will use to provide SSO endpoint services. The 3

Defining Identity Appliance Elements default value /josso/agent.sso works in most environments and is normally not modified. Target Host Install Home Activation Service Endpoint Local when JOSSO and IIS are running on the same OS intance, otherwise Remote is selected. Path where the JOSSO ISAPI Agent will be installed. Keep in mind that site will be defined in IIS pointing to a sub-folder of this path. You can set this value to c:\inetpub \josso. This is only available when Remote Target Host is selected, it represents the URL where a second JOSSO instance running in the Windows server will be listening for execution environment activation requests. The activation allows JOSSO to perform an initial agent setup on the execution environment. For remote activations a second JOSSO 2 server to perform the local tasks (install files, etc) that the main JOSSO server requires. You don t need the second JOSSO server running at all times, only when performing the agent activation. You can also remove JOSSO from the server once the activation is completed. The process can also be performed manually, but the execution environment properties configured in the appliance need to reflect the target environment. 4

Chapter 4. Activating the Execution Environment 4.1. Installing Agent Resources Because we want the tutorial to provide as much information as possible about the IIS integration, the manual activation process will be used. The following resources will be used to configure the agent: Agent binary file: a Windows Dynamic-lik Library (DLL) for the ISAPI Agent. Choose the version that matches your architecture. The files are provided with JOSSO, and can be found at the following location: 32bit ISAPI Agent: $JOSSO2_HOME/josso/dist/agents/bin/ JOSSOIsapiAgent32.dll 64bit ISAPI Agent: $JOSSO2_HOME/josso/dist/agents/bin/ JOSSOIsapiAgent64.dll Agent configuration file: Once your appliance has been compiled, you can select the execution environment element and access the Activation section. Use the Export config button to get a copy of the agent configuration required by your setup. Windows Registry scripts: These scripts will configure the Windows registry based on your settings. The files are created by JOSSO during appliance building process. To get the scripts access the following location: $JOSSO2_HOME/data/work/maven/projects/<APPLIANCE>/project/idau/src/main/ resources/meta-inf/spring/<exec-env>/josso/ josso-agent-eventlog.reg josso-agent-isapi.reg Agent Configuration Resources Path Make sure to replace <APPLIANCE> and <EXEC-ENV> whith the Identity Appliance and Windows IIS execution environment names. Once gathered, the resources must be installed in the IIS server using the following structure. Make sure that the base folder matches the one configured in the execution environment (i.e. c: \InetPub\josso) 5

Activating the Execution Environment C:\InetPub\josso\bin\JOSSOIsapiAgent64.dll C:\InetPub\josso\config\josso-agent-config.ini C:\InetPub\josso\config\josso-agent-isapi.reg C:\InetPub\josso\config\josso-agent-eventLog.reg C:\InetPub\josso\log\ Folder Permissions Make sure that IIS system account has the proper permissions over the created folders (i.e. read/write/execute) 4.2. Configuring IIS 4.2.1. Windows Registry Configuration The ISAPI Agent uses Windows registry entries to obtain basic information about agent specific resources like binary, configuration and log locations, log verbosity level, etc. JOSSO Agent ISAPI Registry entries: Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Atricore] [HKEY_LOCAL_MACHINE\SOFTWARE\Atricore\JOSSO Isapi Agent] [HKEY_LOCAL_MACHINE\SOFTWARE\Atricore\JOSSO Isapi Agent\1.8] "LogLevel"="trace" "ExtensionUri"="/josso/agent.sso" "LogFile"="c:\\InetPub\\josos\\log\\josso_isapi.log" "AgentConfigFile"="c:\\InetPub\\josos\\config\\josso-agent-config.ini" Property LogLevel ExtensionUri LogFile AgentConfigFile Description supported values are: trace (max verbosity), debug, info (recommended for production environments), warn and error. value used by JOSSO ISAPI Extension to process SSO specific services. Agent log file location. Agent configuration file location. The ISAPI Agent also integrates with Windows Event viewer to provide troubleshooting information related to errors occurred before the agent log system is initialized. The following entries register 6

Activating the Execution Environment the agent s DLL as Event Viewer resource messages for errors triggered by the agent. Make sure to select the proper DLL for your architecture. Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application \JOSSO Isapi] "TypesSupported"=dword:00000007 "EventMessageFile"="c:\\InetPub\\josso\\bin\\JOSSOIsapiAgent64.dll" "CategoryCount"=dword:00000007 "CategoryMessageFile"="c:\\InetPub\\josso\\bin\\JOSSOIsapiAgent64.dll" Simply double-click each file using an Administrator account and the changes will be added to the system registry. 4.2.2. Create JOSSO Agent Application To enable SSO services on your execution environment, a web application needs to be created for JOSSO. The application physical path must be set to the agent bin folder: c:\inetpub\josso \bin, and the virtual path /josso. Now that the application is ready, we need to configure a Handler Mapping that relates all requests ending with.sso with the ISAPI agent. Select the created application, and then click the Add Module Mapping option on the right menu. Use the following values: Property Value Description Request Path *.sso Request path for the module, can also be an expression. All requets ending with.sso will be handled by the agent. Module IsapiModule IIS Module type, make sure that IsapiModule is selected Executable c:\inetpub\josso\bin \JOSSOIsapiAgent64.dll Isapi Module binary file Name JOSSOIsapiAgent The module mapping name Request Restrictions Access: Execute Make sure to enable execute access for the module. 4.2.3. Setup JOSSO ISAPI Filter The final step requires to configure the Agent ISAPI filter to ensure that all requests targeted to your partner application will be protected by the SSO agent. ISAPI filters are configured in IIS at 7

Activating the Execution Environment the Site level, select the site element and then open the ISAPI Filters list. You need to add a new entry for JOSSO. Make sure to agree to the ISAPI extension creation when the filter configuration is confirmed. Property Value Description ISAPI or CGI Path c:\inetpub\josso\bin \JOSSOIsapiAgent64.dll The location of the agent binary file. Description JOSSOIsapiFilter Filter configuration description. Allow Extension path to Exectue Selected This will allow the filter to run. 8

Chapter 5. Partner Application Integration Now that the agent installation is completed, let s take a look at the application integration. 5.1. Accessing the Security Context You can access user information as Web Server variables, this worsk for ASP and ASP.NET or any.net application as well. All JOSSO server variables have the HTTP_JOSSO prefix. Variable Description Example HTTP_JOSSO_USER Authenticated user login name HTTP_JOSSO_USER, value user1 for a user with login user1 HTTP_JOSSO_USER_PROPERTY_<NAME> Represents a user property HTTP_JOSSO_ROLE_<NAME>Represents a user role HTTP_JOSSO_ORIGINAL_RESOURCE_URL the protected resource URL that was originally requested HTTP_JOSSO_USER_PROPERTY_EMAIL, value user1@josso.org [mailto:user1@josso.org] for a property email: user1@josso.org [mailto:user1@josso.org] HTTP_JOSSO_ROLE_ROLE1, value role1 for user with role role1 http://www.mycompany.com/ partnerapp/protected/ myprotected.asp Let s take a look at a sample ASP page: <html> <body> <table width="100%" cellpadding="0" cellspacing="0" border="0" > <tr> <td align="center" class="label"> <table cellpadding="0" cellspacing="3" border="0" > <tr> <td colspan="2" align="center"><b>hello, < %=Request.ServerVariables("HTTP_JOSSO_USER") %>!</b></td> </tr> <%^M 9

Partner Application Integration for each varname in Request.ServerVariables^M If instr(varname, "HTTP_JOSSO") then^m response.write("<tr><td>" & varname & "<td/ ><td>"& Request.ServerVariables(varName) &"</td></tr>")^m end if^m next^m %> </table> </td> </tr> </table> </body> </html> 5.2. Triggering login and logout explicitly A partner application can force a user to authenticate by issuing a HTTP redirect to the proper local agent URL. Depending on the URL parameters, applications can start a login, start a passive login, or perform a logout. The URL is based on the JOSSO Isapi Extension URI, for example if the host name is www.mycompany.com and the extension URI is /josso/agent.sso, the login URL should be: http://www.mycompany.com/josso/agent.sso?josso_login&josso_partnerapp_id=partnerapp-sp Parameter Value Description josso_login No value required Triggers a login process, the IdP will try any available authentication mechanism, like basic authentication josso_login_optional No value required Triggers a passive login process, the IdP will use only passive authentication mechanisms (existing session, WIA, etc). Useful to check for the existence of an SSO session. josso_force_authn true, false Tells JOSSO that an authentication must be forced for the user, even if a session is active. Useful to request an authentication context with different security constraints. For example, require basic authentication 10

Partner Application Integration josso_authn_ctx SAML 2.0 authentication context when remember-me has been detected. When combined with josso_force_authn, it allows applications to request a specific authentication mechanism. josso_logout No value required Triggers the single logout process. josso_partnerapp SP Name Tells the agent which application is performing the request. It must match the SAML service provider name (i.e. partnerapp-sp). associated to the IIS partenra application. Let s take a look at some samples: Intent Login Force a login, even if session exists, using password Passive login (no user interaction) Logout Sample URL http://www.mycompany.com/josso/agent.sso? josso_login&josso_partnerapp_id=partnerappsp http://www.mycompany.com/josso/agent.sso? josso_force_authn&josso_partnerapp_id=partnerappsp&josso_authn_ctx=urn:oasis:names:tc:saml:2.0:ac:classes:pas http://www.mycompany.com/josso/agent.sso? josso_login_optional&josso_partnerapp_id=partnerappsp http://www.mycompany.com/josso/agent.sso? josso_logout&josso_partnerapp_id=partnerappsp Action Parameters The parameters that specify the type of action to be performed (josso_login, josso_login_optional, josso_logout), are exclusive and cannot be combined in the same request. 11