Single Sign-On Using the GlassFish V3.1 OAM Security Provider
By kumarjayanti on Feb 27, 2011
The Oracle GlassFish Server V3.1 release has a new Security Provider called the OAM Security Provider. OAM stands for Oracle Access Manager. Product Documentation for the Oracle GlassFish Server V3.1 is available here. The detailed documentation on configuring the OAM Security Provider is in a chapter called Integrating Oracle Access Manager in the Oracle® GlassFish Server 3.1 Security Guide (Part No: 821-2435).
Oracle Access Manager allows users of your applications or IT systems to log in once and gain access to a broad range of IT resources. Oracle Access Manager provides an identity management and access control system that is shared by all your applications. The result is a centralized and automated single sign-on (SSO) solution for managing who has access to what information across your entire IT infrastructure.
The OAM Security Provider provides a way for WebApplications hosted on GlassFish to be secured using OAM and utilizes the capabilities of OAM to manage Single Sign-On (SSO).
A WebGate is a Web server plug-in access client that intercepts HTTP requests for Web resources and forwards them to the Access Server for authentication and authorization. An AccessGate is a form of access client that processes requests for Web and non-Web resources (non-HTTP) from users or applications.
Usecases and Integration Architecture
The OAM Security Provider is implemented as a Servlet Layer JSR-196 Server Authentication Module (SAM) and can be configured for use with WebApplications hosted on GlassFish. The documentation link mentioned above describes in detail how one can configure the Provider for use with WebApplications hosted on GlassFish. The general documentation on how to configure a SAM with GlassFish is also available in a chapter called Administering Message Security of the Security Guide.
The OAM Security Provider acts as an Authenticator and/or Identity-Asserter depending on the usecase. The Authenticator function is exercised when GlassFish is facing the end-user directly. In the Authenticator function the OAM Security Provider does the following :
- Handles Authentication of the end-user at OAM. It challenges the user using an Authentication scheme (One of FORM, BASIC, CERTIFICATE) configured for the resource at OAM. And upon successful authentication, OAM creates an OBSSOSession and returns it to the Provider.
- Setting a Cookie (ORA_GF_ObSSOCookie) in the response, created from the session identifier of the OBSSOSession.
- Sets the CallerPrincipal (into the Client Subject) in a form that is understood by the GlassFish Container
- Extracts Group Membership information for the authenticated user from the OAM backend for use by the container in its Authorization Decisions.
The Security Provider acts as an Identity Asserter in two cases.
- When GlassFish server is front-ended by a Proxy WebServer and an OAM WebGate configured at the Proxy handles the authentication of the end-user. This case is not supported by the current release of the OAM Security Provider and will be supported in future. In this case the Provider would recieve a Cookie or Authenticated User Principal in a special header agreed upon between the Provider and the WebGate. Since the only way GlassFish server can recieve requests is via the proxy this agreement is secure.
- When GlassFish server is facing the end-user directly but it recieves Cookie (that was probably set by an earlier authentication step).
In the Identity Asserter function, the OAM Security Provider does the following :
- Checks if the Cookie received is still valid and returns an error if not valid
- In case the Cookie represents a valid OBSSOSession of a Logged In User then it does exactly the same steps 3 and 4 as in the Authenticator function.
After successful authentication the authenticated client subject is passed over to the Container's authorization engine to check if the principal is authorized to access the GlassFish hosted resource. The final decision to allow access to the resource is thus dictated by the GlassFish authorization engine based on security-constraints defined for the resource (in web.xml and glassfish-web.xml) which define the allowed roles.
Provisioning the OAM Security Provider involves tasks on both the GlassFish (acting as Client to OAM) and the OAM Server Instance side.
Configuration on the GlassFish side involves the following:
- Configuring the provider on the glassfish side as a httpservlet layer SAM,
- Configuring the properties that control the various aspects of the provider.
- Binding the provider to the web application(s)
- Configuring an AccessGate (OAM 10g Terminology) that can communicate with the OAM Access Server. AccessGate handles all the communications between the Security Provider and the Access Server.
The OAM Security Provider (acting as an AccessGate) uses the Access Server SDK 10g API's to communicate with the Access Server. The level of security for the communication between the GlassFish AccessGate and the OAM Access Server can be configured (from open to secured with mutual SSL), when provisioning the AccessGate.
Configuration on the OAM Server Side varies based on the version of the OAM Server. Specifically both 10g and 11g versions of OAM are supported.
The chapter Integrating Oracle Access Manager drescribes the details of how to provision the OAM and the GlassFish side.
Establishing the Resource(s) which are being Protected
One particular aspect of provisioning that i would like to focus here is establishing the web resource being protected. The resource details need to be configured at OAM, in 10g it would be part of the PolicyDomain that you create under the PolicyManager. The 10g PolicyDomain is called ApplicationDomain in 11g ( and can be created from the PolicyConfiguration tab on the 11g console).
By default the OAM Security Provider would assume that the resource being accessed is a Proxy resource whose value is the following java string.
"//" + <OAMHostIdVariation> + "/"+ glassfish-default
This is sufficient if the intent of using the provider is to perform authentication/identity-assertion and establish SSO for a bunch of applications configured to use the provider, while leaving the final authorization decision to the Containers authorization engine. When using this scheme there is no need to configure any authorization policies at OAM for the resource /glassfish-default. Neither will the authorization policies configured at OAM be checked.
As clarified earlier, final authorization decision to allow the resource access lies with the GlassFish authorization engine and that would be based on the authorization policies specified declaratively (in web.xml and glassfish-web.xml) and/or through annotations on the servlet (refer JavaEE 6 tutorial for details of @ServletSecurity annotation).
However if one desires, it is possible to ask the provider to instead construct the resource being accessed based on the HttpRequest (request.getRequestURI()). This can be done by setting the Provider option oam.check.resource.access to true. Note that using this scheme would mean that the individual resources (URI's) are configured at the PolicyDomain/ApplicationDomain in the OAM Server.
In addition the following two options oam.include.port.in.resource and oam.include.query.params.in.resource can be configured at the provider . As the names suggest the first one would append the port number of request to the <OAMHostIdVariation> and the second one tells the provider to include the query parameters from the request in the resource access check.
Note that when the option oam.check.resource.access is enabled, then any authorization policies configured for the resource at OAM will also be checked. In other words final access to the resource will be allowed only if the authorization policies at both the OAM and the ones specified in the JavaEE WebApplication are satisfied by the authenticated client.
Note that the HTTP Method (GET/POST) and the http url scheme (https/http) are also part of the final resource representation that OAM server uses.
The <OAMHostIdVariation> is the value of the property oam.resource.hostid.variation configured at the SAM. When not specified the OAM provider would use HttpRequest.getServerName() as the value of this property. When configured its value should match one of the Host Identifier(s) configured under the OAM PolicyConfiguration Tab (11g)/Access System Configuration Tab(10g). You use Host identifiers to simplify the identification of a Web/Application server that hosts resources you want to protect with Oracle Access Manager.
Process overview: User authentication
For the usecase of a client attempting to access a GlassFish resource protected at OAM using FORM/BASIC authentication, the following interaction diagram shows the messages that flow between the browser (client), the OAM Security Provider, and the OAM Server.
- A user attempts to access a Oracle Access Manager-protected GlassFish resource.
- 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.
- 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 control returns to Container Authorization mechanism which would check if the user has permission to access the requested resource.
- If authorization is successful, GlassFish Server enables the user to access the requested resource.