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.
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:
(for x64 architecture)
This will create files in folders:
- 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)
Make sure that you apply these registry keys and then proceed to 3. Setup the Agent.
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.
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.
Make sure that the IIS user has read permission for the config folder and read/write for the log one.
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 :
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.
Restart of the World Wide Web Publishing Services must be performed for ISAPI component upgrades and configuration updates.
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 "220.127.116.11:8080"
- gatewayLoginUrl : must point to the Gateway URL where the user will be redirected for authenticating, for example "http://18.104.22.168: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 :
You can access user information as ASP Server variables. All JOSSO server variables have the HTTP_JOSSO prefix.
|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_USER_PROPERTY_EMAIL, value email@example.com for a property email: firstname.lastname@example.org|
|HTTP_JOSSO_ROLE_<NAME>||Represents a user role||HTTP_JOSSO_ROLE_ROLE1, value role1 for user with role role1|
|HTTP_JOSSO_ORIGINAL_RESOURCE_URL||the protected resource URL that was originally requested||http://myapp/partnerapp/protected/myprotected.asp|
Lets have a look at how to dump the server variables of a single sign-on session using an ASP script :
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 :