GlassFish V2.1.1 Patch #7 introduces a new Security Provider which allows web applications to authenticate and obtain single sign-on functionality by authenticating against Oracle Access Manager 10g. The Security Provider has been implemented as a JSR-196 Server Authentication Module (SAM) and must be configured at the HttpServlet layer interception point in GlassFish Server. The Access Manager Security Provider can be used in two modes.
· As an Authenticator
· As an Identity Asserter
As an Authenticator
This use case would occur when GlassFish Server is directly receiving unauthenticated requests from end-user Clients for applications deployed. As an Authenticator the Provider would challenge the user for credential collection. The form of challenge issued (BASIC, FORM, Client-Certificate) and the security characteristics of the Transport (SSL or PlainText) depends on the Policies configured at Access Manager for the resource being accessed.
The Provider challenges the user, collects the credentials and sends them over to Access Manager via its configured AccessGate. Access Manager would authenticate the credentials and upon successful authentication create an OBSSOSession. The Provider would receive this session and set its identifier as a cookie in the response. This allows subsequent requests from the client for other resources protected by the same policy-domain to not require authentication, thus achieving single sign-on access to resources.
Note: Access Manager supports several modes of authentication between the AccessGate hosted on GlassFish Server and the Access Manager instance. This includes plain-text (with/without password), SSL with Access Manager-generated certificates or any general third party trusted certificates. Refer to the Access Manager documentation for more details on this. This aspect is out-of-scope of the Access Manager Security Provider. The type of communication channel and authentication requirements depends on the topology of the deployment (for example: if the GlassFish Server instance with its AccessGate is co-located with the Access Manager instance on the same Network then SSL may not be required for the channel).
As an Identity Asserter
This use case would occur when GlassFish Server is front-ended by a proxy web server that has an installed WebGate plug-in. It is assumed that there is a mod_jk/AJP connector to GlassFish Server web container from the proxy. In this case the WebGate would be responsible for challenging the end user requests for resources. It is assumed that the connector would pass either the authenticated user principal or the OBSSOCookie in a designated header while forwarding the request to GlassFish web container.
In this function the Access Manager Security Provider tries to assert the identity of the user, or the OBSSOCookie that was sent in the configured http header. If the cookie has expired since the header was sent then the Security Provider would reject the requested resource access.
In both functions the Security Provider also tries to obtain group membership information for the authenticated end-user from the Access Manager backend. This information is set in a SecurityContext that is then passed on to the authorization system of the container to determine if access to the resource should be allowed.
Process overview: User authentication (FORM and BASIC)
1. A user attempts to access an Access Manager-protected GlassFish Server resource.
2. The GlassFish Server challenges the user for a username and password (not Access Manager) using a predefined login form because the application’s deployment descriptor requires authentication from the container. You may use your own login form, which can be specified as an option to the Security Provider.
3. The GlassFish Server forwards the username and password to the Security Provider for authentication and authorization.
4. The Authentication Provider uses the AccessGate to communicate with the Access Server to verify the user's identity.
5. If authentication is successful, the Security Provider would create a Subject with the authenticated principal and also set a Cookie in the response. The ObSSOCookie is set so that when the user attempts to access additional Access Manager-protected non-GlassFish resources, re-authentication is not performed. In this scenario, if the ObSSOCookie is already set and the user has logged in using form-based authentication, the user is logged in without being challenged.
6. The control returns to container authorization mechanism that would check if the user has permission to access the requested resource. The policies that protect resources are specified in the Policy Manager application in Access Manager. Policies that are defined in web.xml are honored by default and authorization based on policies at the Policy Manager can be configured as an option. In case the Security Provider is configured to do additional authorization check based on policies at the Policy Manager, the resource access would still be disallowed if the policies defined at web.xml are not satisfied.
7. If authorization is successful, the GlassFish Server enables the user to access the requested resource.
What you need to know
· Basic GlassFish V2.1.1, Java EE web application development application deployment processesAccess Manager 10g (Configuring AccessServer, AccessGate, WebGate, creating users in the Access Manager backend, defining Policy Domains and specifying their authentication and authorization policies).
· GlassFish Server v2.1.1 with Patch #7
· Oracle Access Manager 10g
· Access Manager Access Server SDK API 10g
· JDK 1.5.0_07 or above.
<GLASSFISH_HOME> : The install root for glassfish v2.1.1 application server.
The Java EE Web applications are assumed to have been configured with deployment descriptors containing required <security-constraint> and associated <auth-constraint> specifying the roles. The descriptors would not be assumed to contain the <login-config> elements that specify the Java EE supported authentication methods. The Security Provider instead infers the authentication mechanisms based on AuthenticationScheme configured for the resource at Access Manager. The mechanisms supported are BASIC, FORM or Client-Cert as the authentication methods. The default being BASIC. Options for configuring SSL transport in all the cases is also present. The authentication schemes supported at Access Manager include BASIC, FORM and Client-Cert and use of SSL transport is optional for BASIC and FORM.
Building the application
The application can be any Java EE web application with security-constraint's and associated auth-constraint. A sample application is provided.
Running the Application
1. Install AccessServer SDK 10g on your system Access Server SDK Please download from Access Manager (2nd row). We shall refer to the install dir for AccessServer SDK as <AccessServerSDK-install-dir>
2. Configure AccessServer SDK on your system from where you intend to run the GlassFish Server hosted application
Example :<AccessServerSDK-install-dir>/oblix/tools/configureAccessGate>configureAccessGate -i <AccessServerSDK-install-dir> -t AccessGate -w GlassFishAG -m open -h staqh24-5.us.oracle.com -p 6021 -a GlassFishAS
The above command configures the AccessGate named "GlassFishAS" for use by the Access Manager Security Provider hosted on GlassFish Server. Please read the Access Manager user guide for more details on configuring AccessGate.
3. Add the following GlassFish Server JVM options: <jvm-options>-DOBACCESS_INSTALL_DIR=<AccessServerSDK-install-dir></jvm-options>
4. Copy jobacces.jar from from <AccessServerSDK-install-dir>/oblix/lib into <GlassFish>/lib
5. Create a new httpservlet layer MessageSecurityProvider in GlassFish Server 2.1.1 via Admin GUI or CLI which configures the Access Manager Security Provider (SAM), example :
<provider-config provider-type="server" provider-id="MySAM classname="com.sun.glassfish.oamsam.OAMAuthenticatorSAM">
<property name="oam.resource.hostid.variation" value="sm224050-chamaka.india.sun.com" />
<!--property name="form.login.page" value="" /-->
7. Deploy the (BasicAuthen.war) to your GlassFish Server v2.1.1 instance.
8. Configure the SAM for the attached application in sun-web.xml for example if the SAM was configured as MySAM then here is what the first line of sun-web.xml would contain : <sun-web-app error-url="" httpservlet-security-provider="MySAM">.
9. set OBACCESS_INSTALL_DIR in the command line where you start GlassFish Server (should do this before GlassFish Server is started), set PATH to contain <AccessServerSDK-Install-Dir>/oblix/lib
10. Configure LDAPRealm in GlassFish Server (using Admin GUI or CLI) to point to Access Manager backend. For example:
<auth-realm classname="com.sun.enterprise.security.auth.realm.ldap.LDAPRealm" name="ldaprealm">
<property name="jaas-context" value="ldapRealm" />
<property name="base-dn" value="o=company,c=us" />
<property name="directory" value="ldap://126.96.36.199:1389" />
<property name="search-bind-dn" value="cn=Directory Manager" />
<property name="search-bind-password" value="welcome1" />
11. Make ldaprealm the default realm in GlassFish Server <security-service default-realm="ldaprealm">
12. In case of Windows make sure the PATH environment variable is set to contain <AccessServerSDK-Install-Dir>\oblix\lib. This should be set in the CMD window from which you start GlassFish Server.
13. For GlassFish Server 2.1.1 we also need to set ApplicationServer->JVM Settings->Path Settings->Native Library Path Prefix : to contain <AccessServerSDK-Install-Dir>/oblix/lib
14. Create a test user "glassfish" with some password on the Access Manager instance and make sure the user is in the following group: GlassFish_group
This is in case you are planning to run the attached sample application. Otherwise generally you will need to make sure that that authenticated user is in a group that is allowed to access the resource from the web application hosted on GlassFish Server.
15. RESTART GlassFish Server and access the protected resource in browser: http://<hostname>.<domainname>:8080/BasicAuthen/SecureServlet
Note: if you are trying to use http://locahost:8080/BasicAuthen/SecureServlet then the case where a cookie needs to be sent from the browser will not work. So for example if you configured Form login for the SAM, you will find that you are in an infinite loop because the cookie is never sent post successful form authentication.
Configuring Access Manager
1. Identity System Console:
a. User Manager - create user(s) - (eg) GlassFish Server
b. GroupManager - create groups and add the user created to the groups (eg) - GlassFish_group.
Note: The above steps can also be done through the backend LDAP directly.
2. Access System Configuration:
a. Add a new Access Server: Provide the required parameters including name, host name , enable it. Refer to the Access Manager user’s guide for more details on how to create and configure an Access Server.
b. Add a new AccessGate: Provide the required parameters including name, host name (in which AccessGate would be configured), cookie domain (eg) .oracle.com. and Enable it. Refer to the Access Manager user’s guide for more details on how to create and configure an Access Server.
c. Associate the Access Gate and the Access Server.
d. Host Identifiers - Create a new Host Identifier with a hostname variation that points to the IP address or the fully qualified domain name (FQDN) of the machine where the Access Gate is configured.
e. Authentication Management - Create a new Authentication Scheme for each login-mechanism method (BASIC, FORM, CERTIFICATE)
(eg 1) - GlassFish BASIC over LDAP: (required for GlassFish BASIC auth mechanism) Challenge Method Basic Challenge Parameter realm:LDAP User Name/Password
i. Plugins: Add a credential mapping plugin for this auth-scheme:
(eg 1) credential_mapping obMappingBase="o=company,c=us",obMappingFilter="(&(objectclass=inetOrgPerson)(genuserid=%userid%))" validate_password obCredentialPassword="password"
This is a mapping between the LDAP attributes of the user (obCredentialPassword, genuserid) and the auth-scheme params (userid,password). Please make sure the LDAP attributes of the user and the Access Manager Request parameters are mapped correctly here. Also make sure that you set up the Authentication Flow at Access Manager for the Authentication_Scheme. For example the validate_password plugin should be the next plugin after credential_mapping and the flow would stop if validate_password fails. Refer to the Access Manager user’s guide for more details on how to setup Authentication Flow for the plugins.
(eg 2) - Client certificate (required for CERTIFICATE auth mech) Challenge Method X509Cert Challenge Parameter X509 SSL Required Yes
3. Policy Manager
a. Policy Domains - Create a policy domain.(eg) GlassFishPD:
i. Configure a resource
The GlassFish Server protected resources could be configured individually here if authorization is also desired at Access Manager. If only authentication and identity assertion are desired, then a proxy resource, (eg) /glassfish-default can be configured here. To run the attached sample application Sample App just create a proxy resource: /glassfish-default
ii. Add an authentication rule (under Default rules). Choose the auth-scheme that has been configured in step 2(v) above
iii. Policies - Provide a name, choose the operations and choose the configured resource (HostIdentifier + resourceURL)
Configuring GlassFish Server AccessGate
This has been explained in the section above on running the application.
Configuring the Access Manager Security Provider for the web application
Configure the SAM for the attached application in sun-web.xml for example if the SAM was configured as MySAM then here is what the first line of sun-web.xml would contain:
<sun-web-app error-url="" httpservlet-security-provider="MySAM">
Deploying the WebApplication
Deploy the web application to GlassFish Server. Refer to GlassFish Server administration guide for more details on how to deploy an Application using Admin GUI or CLI.
Running the web application
To run the sample application attached type the following in your browser:
The Access Manager Security Provider for GlassFish Server v2.1.1 provides for authentication and establishing single sign-on with the enterprise class Access Manager.
JavaDoc of options supported by the Access Manager Security Provider
The Access Manager Security Provider supports various options that can be configured to affect the behavior of the SAM. More details can be found in the JavaDocs.
Access Manager and AccessServer SDK documentation
JSR-196 and GlassFish Server
More Middleware Downloads