GlassFish Wiki : How-To Use OAM Security Provider for JavaEE WebApp Authentication with GlassFish 2.1.1

Introduction

GlassFish V2.1.1 Patch #7 introduces a new Security Provider which allows WebApplications 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. The OAM Security Provider can be used in two modes.

As an Authenticator
As an Identity Asserter

As an Authenticator

This usecase would occur when GlassFish is directly recieveing 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 OAM for the resource being accessed.

The Provider challenges the user, collects the credentials and sends them over to OAM via its configured AccessGate. OAM would authenticate the credentials and upon successful authentication create an OBSSOSession. The Provider would recieve 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 achieveing Single Sign-On access to resources.

Note: OAM supports several modes of authentication between the AccessGate hosted on GlassFish and the OAM instance. This includes plain-text (with/without password), SSL with OAM generated certificates or any general third party trusted certificates. Refer OAM documentation for more details on this. This aspect is out-of-scope of the OAM security provider. The type of communication channel and authentication requirements depends on the topology of the deployment (for example : if the GlassFish instance with its AccessGate is colocated with the OAM instance on the same Network then SSL maynot be required for the channel).

As an Identity Asserter

This usecase would occur when GlassFish is FrontEnded by a Proxy WebServer which has an installed WebGate plugin. It is assumed that there is a ModJK/AJP connector to GlassFish WebContainer from the Proxy. In this case the WebGate would be responsible for challenging the enduser resquests 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 WebContainer.

In this function the OAM 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 Memembership information for the authenticated end-user from the OAM Backend. This information is set in a SecurityContext which is then passed onto the Authorization System of the Container to determine if Access to the resource should be allowed.

Process overview: User authentication (FORM and BASIC)

A user attempts to access a Oracle Access Manager-protected GlassFish resource.
The GlassFish Server challenges the user for a username and password (not Oracle 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 must can be specified as an option to the Security Provider.
The GlassFish Server forwards the username and password to the Security Provider for authentication and authorization.
The Authentication Provider uses the AccessGate to communicate with the Access Server to verify the user's identity.
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 Oracle Access Manager-protected non-GlassFish resources, reauthentication 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.
The control returns to Container Authorization mechanism which 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 Oracle 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.
If authorization is successful, the GlassFish Server enables the user to access the requested resource.

Prerequesites

What you need to know

Basic GlassFish V2.1.1, JavaEE WebApplication development, application deployment processes, Oracle Access Manager (OAM 10g) (Configuring AccessServer, AccessGate, WebGate, creating users in the OAM backend, defining Policy Domains and specifying their Authentication and Authorization policies).

Software Requirements

GlassFish V2.1.1 with Patch #7
Oracle Access Manager (OAM) 10g.
OAM Access Server SDK API 10g.
JDK 1.5.0_07 or above.

Notations

<GLASSFISH_HOME> : The install root for glassfish V2.1.1 application server.

Assumption

The JavaEE 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 JavaEE supported authentication methods. The Security Provider instead infers the authentication mechanisms based on AuthenticationScheme configured for the resource at OAM. 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 OAM 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 JavaEE WebApplication with security-constraint's and associated auth-constraint's. Attached is a sample application that can be used [ Sample Application WAR |http://wikis.sun.com/download/attachments/215071314/BasicAuthen.war].

Running the Application

Install AccessServer SDK 10g on your system Access Server SDK Please download from OAM (2nd row). We shall refer to the install dir for AccessServer SDK as <AccessServerSDK-install-dir>
Configure AccessServer SDK on your system from where you intend to run the glassfish hosted Application
```
for 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 OAM Security Provider hosted on GlassFish. Please read the OAM user guide for more details on Configuring AccessGate.
In GlassFish JVM options add the following : <jvm-options>-DOBACCESS_INSTALL_DIR=<AccessServerSDK-install-dir></jvm-options>
Copy jobacces.jar from from <AccessServerSDK-install-dir>/oblix/lib into <Glassfish>/lib

Create a new httpservlet layer MessageSecurityProvider in GlassFish V2.1.1 via Admin GUI or CLI which configures the OAM Security Provider (SAM), example :

 
          <message-security-config auth-layer="HttpServlet">
          <provider-config provider-type="server" provider-id="MySAM" class-name="com.sun.glassfish.oamsam.OAMAuthenticatorSAM">
            <property name="oam.resource.hostid.variation" value="sm224050-chamaka.india.sun.com" />
            <!--property name="form.login.page" value="" /-->
          </provider-config>
        </message-security-config> 
         

Deploy the attached Application [#http://wikis.sun.com/download/attachments/215071314/BasicAuthen.war] on your GlassFish V2.1.1 instance.
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">.
set OBACCESS_INSTALL_DIR in the commandline where you start GlassFish (should do this before glassfish is started), set PATH to contain <AccessServerSDK-Install-Dir>/oblix/lib

Configure LDAPRealm in GlassFish (using Admin GUI or CLI) to point to OAM 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://140.87.134.98:1389" />
          <property name="search-bind-dn" value="cn=Directory Manager" />
          <property name="search-bind-password" value="welcome1" />
        </auth-realm> 
         

Make ldaprealm the default realm in glassfish <security-service default-realm="ldaprealm">
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
For GF V2.X we also need to set ApplicationServer->JVM Settings->Path Settings->Native Library Path Prefix : to contain <AccessServerSDK-Install-Dir>/oblix/lib
Create a test user "glassfish" with some password on the OAM instance and make sure the user is in the following group : Glassfish_group
This is incase 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 WebApplication hosted on GlassFish.
RESTART GLASSFISH and Access 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 OAM

Identity System Console:
1. User Manager - create user(s) - (eg) glassfish
2. 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.
Access System Configuration:
1. Add a new Access Server: Provide the required parameters including name, host name , enable it. Refer OAM users guide for more details on how to create and configure an Access Server.
2. Add a new Access Gate : Provide the required parameters including name, host name (in which Access Gate would be configured), cookie domain (eg) .oracle.com. and Enable it. Refer OAM users guide for more details on how to create and configure an Access Server.
3. Associate the Access Gate and the Access Server.
4. Host Identifiers - Create a new Host Identifier with a hostname variation that points to the IP address or the FQDN of the machine where the Access Gate is configured.
5. 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
  1. 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 OAM Request parameters are mapped correctly here.Also make sure that you setup the the Authentication Flow at OAM 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 OAM User 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
Policy Manager
1. Policy Domains - Create a policy domain.(eg) GlassfishPD:
  1. Configure a resource
    The glassfish protected resources could be configured individually here if authorization is also desired at OAM. 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
  2. Add an authentication rule (under Default rules). Choose the auth-scheme that has been configured in step 2(v) above
  3. Policies - Provide a name, choose the operations and choose the configured resource (HostIdentifier + resourceURL)

Configuring Glassfish AccessGate

This has been explained in the section above on Running the Application.

Configuring the OAM Security Provider for the WebApplication

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. Refer to GlassFish user guide for more details on how to deploy an Application using Admin GUI or CLI.

Running the WebApplication

To run the sample application attached type the following in your browser : http://<hostname>.<domainname>:8080/BasicAuthen/SecureServlet

Summary

The OAM Security Provider for GlassFish V2.1.1 provides for authentication and establishing Single Sign-On with Enterprise class Oracle Access Manager.

JavaDoc of options supported by the OAM Security Provider

The OAM Security Provider supports various options which can be configured to affect the behavior of the SAM. More details can be found in the JavaDocs. JavaDocs Internal Site