1. Overview

The ISAPI JOSSO Agent enables transparent Single Sign-On capabilities to web assets, such as ASP pages and resources, thus allowing seamlessness integration without any programmatic intervention.
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 Gateway instance.

2. Installing the Agent

The artifacts that compose the ISAPI Agent are :

• JOSSOIsapiAgent.dll : its where the agent logic realizing both ISAPI Filter and Extension contracts
• josso-agent-config.ini : agent descriptor containing configuration properties

Download the ISAPI Agent and its dependencies from here : JOSSOIsapiAgent.zip

From JOSSO 1.8.4 agent installation is available from installation console.

You can issue following command:

josso> agent install --target C:/InetPub/josso --platform iis

josso> agent install --target C:/InetPub/josso --platform iis64

This will create files in folders:

• C:\InetPub\josso\bin\JOSSOIsapiAgent.dll
• C:\InetPub\josso\config\josso-agent-config.ini
• C:\InetPub\josso\config\JOSSO-ISAPI-Config.reg (with corresponding paths, need to be applied manually)
• C:\InetPub\josso\config\JOSSO-ISAPI-EventLog.reg (with corresponding paths, need to be applied manually)
• C:\InetPub\josso\log\josso_isapi.log

Make sure that you apply these registry keys and then proceed to 3. Setup the Agent.

2.1 Install the ISAPI Agent and required dependencies

Create a virtual directory within the IIS Web Site that will hold the Agent DLL and its dependencies. In our we will map this virtual directory to the C:\Inetpub\josso folder.

Expand the ISAPI Agent zip file onto C:\Inetpub\josso.

2.2 Setup the ISAPI Agent home

The Agent configuration and log files should be located stored a separate folder, outside the scope of IIS.
We'll use c:\josso\isapi as the JOSSO ISAPI Agent home, having the config and log folders for storing the agent descriptor and the generated log files.

Copy josso-agent-config.ini file to the config folder which will be referenced from the Windows Registry entry as showed in the next step.

Folders Security Make sure that the IIS user has read permission for the config folder and read/write for the log one.

2.3. Prepare the registry

Generate JOSSO-ISAPI-Config.reg and JOSSO-ISAPI-EventLog.reg files based on the content below.

Make sure to use valid values for the ExtensionUri, LogFile and AgentConfigFile properties by doubleclicking the registry file with the following content :

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/JOSSOIsapiAgent.dll"
"LogFile"="c:\\josso\\isapi\\log\\josso_isapi.log"
"AgentConfigFile"="c:\\josso\\isapi\\config\\josso-agent-config.ini"

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Eventlog\Application\JOSSO Isapi]
"TypesSupported"=dword:00000007
"EventMessageFile"="C:\\Inetpub\\josso\\JOSSOIsapiAgent.dll"
"CategoryCount"=dword:00000007
"CategoryMessageFile"="C:\\Inetpub\\josso\\JOSSOIsapiAgent.dll"

3. Setup the Agent

3.1 Create Partner Application

Partner applications live within IIS virtual directories of a web site.

Create a virtual directory pointing it to the folder containing JOSSOIsapiAgent.dll and enable ISAPI extension execution.

3.2 Enable JOSSO ISAPI agent for adding SSO capabilities to the virtual directory.

3.3. Restart the WWW Publishing Service

Restart of the World Wide Web Publishing Services must be performed for ISAPI component upgrades and configuration updates.

4 Setup Partner application

The JOSSO ISAPI Agent can be used for protecting resources as well as to provide a security context - in case one is available - to specific public resources.

The agent descriptor has three main sections :

• endpoint configuration
• partner application definitions
• security constraints definitions

The endpoint configuration has the following properties :

• gatewayEndpoint : must point to where the JOSSO Gateway (Identity Provider) is listening, for example "130.5.5.9:8080"
• gatewayLoginUrl : must point to the Gateway URL where the user will be redirected for authenticating, for example "http://130.5.5.9:8080/josso/signon/login.do"
• secureTransport : tells the agent if we are communicating with the JOSSO Gateway over SSL. Default value is false
• soapTransportTimeout : if we are using SSL, we need to specify the timeout for send and receive operations. Value is in seconds
• caFile : location of the file containing certificates of certificate authority in .pem format. This is used to verify the authentication of JOSSO Gateway's certificate. If you are using self-signed certificate for testing purposes, location should point to the self-signed certificate
• sslSkipHostCheck : if we are using SSL, specify if the host name verification check should be skipped. Default value is false
• sslAllowExpiredCerts : if we are using SSL, allow connecting to a host with an expired certificate. Default value is false
• If HTTP Basic authentication is enabled on JOSSO Gateway, we need to send the username and password in our request(s). For that we use basicAuthUserId to specify the username and basicAuthPassword to specify the password

Within the partner application section, with with prefix "partnerapp" several partner application entries may be defined having the following attributes :

• base-uri : its the URI where the partner application is bound to, for example "/partnerapp".
• splash-resource : Optional property holding the URL to which the user will be redirected to upon successfully authenticating.

Incoming HTTP requests matching partner application URIs will be authenticated using the corresponding SSO Session information. The resources listed in this section are not protected if security constraints are not bound to it as we will see in the next step.

Within the security constraints section, access control lists may be specified for defining web access control constraints. Entries must be prefixed with security-constraint and have the following attributes :

• base-uris : may be used for specifying the URIs for the protected resources, for example /public,/admin,/partnerapp . The regular expression format is supported.
• roles: specifies one or more roles that a user will be required to have in order to be granted access to the protected resource(s).

Lets look at a sample configuration file :

[agent]
gatewayEndpoint=130.5.5.9:8080
gatewayLoginUrl=http://130.5.5.9:8080/josso/signon/login.do

;;SSL setup
secureTransport=false
;;caFile=/location/of/the/ca_file
;;sslSkipHostCheck=false
;;sslAllowExpiredCerts=false

;;HTTP Basic Authentication setup
;;basicUserId=username
;;basicPassword=password

;; ---------------------------------------------------------
;; SSO Partner Applications
;;
;; All sections starting with 'partnerapp' will be treated
;; as partner app declarations.
;; ---------------------------------------------------------

[partnerapp.1]
base-uri=/partnerapp

[partnerapp.2]
base-uri=/partnerappb
splash-resource=http://192.168.90.55/partnerapp/welcome.asp

;; ---------------------------------------------------------
;; SSO Security Constraints for 'Applications'
;;
;; All sections starting with 'security-constraint' will be treated
;; as security constraint declarations
;; ---------------------------------------------------------

[security-constraint.admin]

;; Comma separated list of required roles (optional)
;; Do not leave empty spaces between elements!
roles=role1,admin

;; Comma separated list of base uris for this constraint (required)
;; Do not leave empty spaces between elements!
base-uris=/public/.*\.pdf,/admin/[sS]ec_.*\.*,/partnerapp

[security-constraint.public]
base-uris=/public

4.1. Accessing the security context from an ASP Applications

You can access user information as ASP Server variables. All JOSSO server variables have the HTTP_JOSSO prefix.

Lets have a look at how to dump the server variables of a single sign-on session using an ASP script :

<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
                    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>

4.2 Triggering authentication explicitly

A partner application can force a user to authenticate by redirecting him to the agent .

The URL is based on the JOSSO Isapi Extension URI, for example if the host name is myhost and the extension URI is /josso/JOSSOIsapi.dll, the login URL should be :

http://myhost/josso/JOSSOIsapi.dll?josso_login&back_to=<myCurrentResource>

5. Some Useful Links

• MS VS Dependency Walker (x86) http://www.dependencywalker.com/depends22_x86.zip
• MS VS Dependency Walker (x64) http://www.dependencywalker.com/depends22_x64.zip