With the increasing use of distributed systems based on open standards and flexible information sharing with multiple business partners, establishing the identities of the communicating parties has become an important element in protecting your business operations. You need to protect your business sensitive data provided by the business application against unauthorized access, such as protecting the list of your customers from your competitor. This is especially relevant for Web applications that access external resources (e.g., Web container-based applications such as Java servlets or Web services running on Java-based servers called JEE servers). In these situations, the authorization concept applies to the following two factors:

• Is the user authorized to access this resource?
• Can the client load the resource, or is the client prevented from loading it?

The JEE server supports the Java Authentication and Authorization Service (JAAS) standard, which in turn supports authentication of installed applications (e.g., Web applications that are running in a Web container). The JAAS standard allows you to configure policy to determine the mechanism that the system uses to authenticate an application’s users. SAP NetWeaver Application Server (SAP NetWeaver AS) Java is a JEE server and supports JAAS-based authentication of Java applications. The authentication concept is based on the Web application’s authentication, which is integrated with SAP User Management Engine (SAP UME). SAP UME provides a centralized user management for all Java applications running in SAP NetWeaver AS Java (or the SAP JEE server). I will show you the authentication functionality available in the SAP JEE server, including the JAAS standard configuration and SAP-specific extensions that are required to configure the authentication mechanism in Java-based applications. Additionally, I will demonstrate how to develop a JAAS-compliant login module that is integrated with SAP UME and can be used in custom Java applications. You can implement the authentication mechanism in SAP NetWeaver AS ABAP and Java. In this article, I concentrate on authentication functionality available in SAP JEE server. Let’s start with the authentication concept, which involves the declarative and programmatic security concept. I’ll then continue presenting the required security-related configuration in the Java application.

Authentication Concept

You can use several types of client systems — such as UI front ends or client applications — to access SAP NetWeaver systems over different corresponding communication channels, such as Web clients, Web service clients, telnet clients, and Remote Function Call (RFC) clients. Figure 1 presents the internal security architecture of SAP NetWeaver AS Java. The security solution is based on JAAS, which allows authentication of variety of clients.   The client-server communication requires client authentication. This means that the client front end sends the authentication data (e.g., user name, password, and logon ticket) to the back-end SAP NetWeaver AS Java server. The server then checks the data and authenticates the client. You can use the authentication mechanism for clients that communicate with the J2EE server by using following access channels:

• Web clients: Uses the authentication for Web-based access and provides information about the available authentication mechanisms for interactive user logon when using HTTP-based front-end clients (e.g., SAP NetWeaver Portal or Web Dynpro)
• Web service clients: Uses the authentication for Web services and provides information about the available mechanisms for authenticating Web service access to SAP NetWeaver
• Back-end systems and clients: Uses the authentication for communication between systems and provides information about the supported mechanisms for authenticating system-specific (non-dialog) communication to and from SAP NetWeaver

The available J2EE server authentication mechanism allows you a flexible implementation and customization of user authentication policies. You can easily develop and configure custom business applications that use the standard authentication mechanisms. Additionally, SAP NetWeaver AS Java enables you to efficiently integrate your SAP NetWeaver systems in a Single Sign-On (SSO) environment, which helps you provide seamless user access to back-end systems. Now let’s take closer look at the security authentication concepts that are accessible in SAP NetWeaver AS Java.

Security Concept Basics — Declarative and Programmatic Security

The security concept allows user authentication in business applications. It provides the following two authentication approaches:

• Declarative authentication: This is also known as container-based authentication. The container (e.g., a Web container for Web applications) handles authentication. Deployed applications running in the container declare its protected resources (i.e., who is permitted to access Web application or open HTML or JSP pages). The application describes and declares authentication roles in its deployment descriptor. When the protected resource within this component is accessed, the container triggers the authentication.
• Programmatic authentication: This is also known as user management authentication or SAP UME authentication. An application running on the J2EE Engine uses this authentication against SAP UME. The application calls the SAP UME API and triggers the authentication.

A standard or custom application running on SAP NetWeaver AS Java can use both authentication approaches. Both authentication types rely on the same underlying technology: login modules and login module stacks. In declarative authentication, you can set up security settings (e.g., permissions for users, groups, and roles) using application descriptors that determine whether or not the system gains access to the resource. Programmatic authentication allows the developer to define the authentication mechanism and functionality in the given application’s code. Therefore, programmatic authentication can be more detailed than declarative authentication because the application’s developer can use programmatic authentication to allow or deny a user access to a particular component inside the application. For most applications, you should use the declarative authentication instead of programmatic authentication because the authentication modification and adoption do not require development effort. An experienced application expert can adopt security settings without code modifications. This promotes code reuse to make the application more maintainable. Additionally, the declarative authentication puts the responsibility of security in the hands of people who specialize in application security, such as the application developer, who concentrates on application functionality, and the security expert, who concentrates on security policies. Table 1 presents you with which authentication type can be used by particular Web application types. Note that this article concentrates on the security and authentication functionality used in the Web client communication channel. The Web service clients and back-end system and client communication is out of the scope of this article.     The J2EE Web applications and J2EE EJB applications can use declarative or programmatic authentication — the developer decides which to use. However, both declarative and programmatic authentication in the J2EE server use login modules and login module stacks as their underlying technology. When using declarative authentication, the application defines in the deployment descriptor which login module stack it uses. The use of programmatic authentication is associated with an authentication scheme, which in turn references a login module stack. Let’s start with authentication schemas that are delivered within SAP NetWeaver AS Java. I’ll show you how to configure and use them in Web applications.

Declarative Authentication in Enterprise Applications

You can create and configure enterprise applications by using SAP NetWeaver Developer Studio. In Figure 2, you can see the types of projects SAP NetWeaver Developer Studio supports. The two groups of projects are:

• Projects that contain application sources, such as Web module or EJB module projects. In this type of project, you create and edit Web resources such as JSP pages, Java servlets, and EJB. The projects build the Web application (for the Web archive) or the EJB application (for the EJB archive). Both applications contain standardized deployment descriptors that describe authentication policies.
• Projects that encapsulate a source project into enterprise application projects that generate complete and deployable J2EE applications

As you can see, an enterprise application project may contain several EJB module and Web module projects.    

Authentication Configuration in the Web Module

The Web module contains web.xml and web-j2ee-engine.xml deployment descriptors, which provide information that the system uses during application deployment and at runtime. SAP NetWeaver Developer Studio generates these deployment descriptors automatically. Web.xml is a standard J2EE deployment descriptor and provides configuration specified in J2EE (configuration valid for all J2EE servers, such as IBM WebSphere server or BEA WebLogic server), and the web-j2ee-engine.xml provides configuration that is specific for SAP JEE server. Let’s take a closer look at the security and authentication-relevant elements in the web.xml and web-j2ee-engine.xml deployment descriptors.

Configuration of web.xml

Web.xml contains the following main configuration topics:

• Definition of Web application display information
• Configuration of welcome and error response pages
• Configuration of servlet context parameters
• Declaration of configuring Web components, such as specifying servlet initialization parameters, configuring display information, and determining load order

• Definition of mapping servlets and JSP pages and mapping filters
• Configuration of resources, resource environment entries, and resource references
• Definition of Web application security roles and specification of security constraints

Figure 3 shows an example of the Web application web.xml descriptor. Note that you can download the text for this code and all the other code in the article at the bottom of the page. You can also read more about the web.xml and web-j2ee-engine.xml deployment descriptors in the sidebar “Authentication Schemas in SAP NetWeaver Application Server Java.”     From an authentication point of view, the example web.xml deployment descriptor contains the following elements:

• Login configuration: <login-config>
• Security role definition: <security-role>
• Security constraint definition: <security-constraint>

Use the login configuration element to configure the authentication method for authenticating application users. The authentication method element (<auth-method>) contains the name of the authentication method for the Web application. The legal values for the authentication method are BASIC, DIGEST, FORM, CLIENT-CERT, or a vendor-specific authentication scheme (when using a custom login module). In my example, the application uses the BASIC authentication method. The respective login modules are configured in the web-j2ee-engine.xml deployment description file. In addition, the realm name element (<realm-name>) specifies the realm of the authentication. The user enters the realm in the Realm field that the browser displays on the logon screen using HTTP basic authentication. If you choose the FORM-based authentication, you can define your own login page and login error page (Figure 4). You use the form-login-page element (<form-login-page>) to configure the login page and the form-error-page element (<form-error-page>) to configure the login error page. The login page and login error page can be HTML pages, Java servlets, or JSP pages. In the elements, you specify the location and the page name. For example, the login page configuration /MyApplLoginPage.html means the page is located in the root folder of the application and the page is called MyApplLoginPage.html.     The web.xml descriptor security contains the definition of the security role element (<security-role>) allowing you to group users and roles in your application. You use the security role element to specify the J2EE application security role that is required to grant access to a particular application or part of the application. The role assignment to the application (or a part of it) is defined in security constraint definition (<security-constraint>). In the next step, you map these J2EE application security roles to existing server security roles that are defined in SAP UME. You carry out the mapping in the web-j2ee-engine.xml descriptor in the security role map element (<security-role-map>). The security constraint element allows you to assign a set of application resources (<web-resource-collection>) to the previously defined J2EE application security role (<auth-constraint>). Only authorized users can call resources (<web-resource-name>) that are defined by specifying a URL pattern (<url-pattern>) or HTTP method names (<http-method>). Otherwise, the authentication mechanism denies the access. If you specified URL patterns or HTTP method names to define the Web resources, each HTTP client request that contains one of these patterns is subject to the security constraint you defined.

Configuration of web-j2ee-engine.xml

The web-j2ee-engine.xml is an SAP deployment descriptor that contains the configuration of following Web application functionality:

• Configuration of security and authentication (e.g., definition of Web application security roles and configuration of that authentication)
• Definition of J2EE server component references and configuring resource references, resource environment entries, and EJB references
• Definition of application response elements (e.g., definition of custom HTTP response status, number of HTTP sessions, configuration of failover alerts, and session tracking)
• Configuration of SAP J2EE Engine cookies

Figure 5 presents an example Web application web-j2ee-engine.xml descriptor.     From the security and authentication point of view, the example web-j2ee-engine.xml deployment descriptor contains two elements: the security-role-map element and the log-module-configuration element. The security-role-map element (<security-role-map>) describes the mapping between the Web application’s security roles (J2EE standard role) and the SAP JEE server security roles defined in SAP UME. The role-name element (<role-name>) specifies the name of the J2EE security role (e.g., MyApplUserSecurityRole) and the server-role-name element (< server-role-name>) specifies the name of the SAP UME role name (e.g., administrators and MY_APPL_USER_ROLE). All users assigned to the SAP UME role administrators or MY_APPL_USER_ROLE are granted access to the Web application. The login-module-configuration element (<login-module-configuration>) defines the authentication login modules that are used in a particular J2EE application and its order. The module order (top-to-button order in the descriptor) is defined by the login-module-stack element (<login-module-stack>). The particular login modules are defined by the login-module element (<login-module>), which defines the authentication method (<login-module-name>) and its priority (<flag>). The configuration of the login module in the web-j2ee-engine.xml deployment descriptor allows you to define the automatic inheritance of the login module configuration from the user store. You can do this by using the login-module name element (the login module’s display name) such as ClientCertLoginModule or BasicPasswordLoginModule as in Figure 5. From the other side, you can also configure specific login module options in the Web application. Enter the class name of the login module (Figure 6) and the SAP J2EE server ignores the options defined in user store. Instead it uses the options defined in the web-j2ee-engine.xml deployment descriptor.     Figure 6 shows the login-module-name element configuration, which specifies the class name for the login module element, such as: com.sap.engine.services.security.server.jaas.ClientCertLoginModule or com.sap.engine.services.security.server.jaas.BasicPasswordLoginModule. Table 2 provides a list of the common SAP login modules that you can use to determine user authentication.     You can combine the SAP and custom login modules in the login module stacks. The container calls the modules defined in the login module stack in top-button order (i.e., the container calls the first module declared in the login module stack element, then the second, and then the rest in numerical order). Regarding the JAAS specification, the system processes each module according to login module flags. Table 3 provides an overview of possible flag values.     The login module definition (<login-module>) may also define an option element (not shown in my example) that contains a key-value pair that you can use to parameterize specific features. For example, the debugging option may report additional information about the login process (Figure 7).     In addition, the web-j2ee-engine.xml descriptor may contain the <password-change-config> element (not in my example) that you can use to define the password change and error password change pages. The container then calls these pages the first time the user logs on to the J2EE server or when the system administrator changes the user password. Finally, the authentication configuration allows you to define the J2EE session tracking mechanism. Session information is sent to the client using cookies or encoding directly in the URL using a URL rewriting mechanism. The <url-session-tracking> element handles this configuration. If this element is not set, cookies are used as the default J2EE session tracking mechanism. Now that I’ve shown you how to configure standard login modules, I’ll explain how to create and configure custom login modules.

Create and Configure of Custom Login Modules

The JAAS standard enables you to create custom login modules. The login module uses the JAAS standard role of authentication components, which is the class (program) that implements authentication functionality. The following steps explain how to create, configure, and deploy a custom login module in SAP NetWeaver AS Java: Step 1. Create a Java project and implement the login module class Step 2. Define the login module configuration file Step 3. Create and deploy the login module in an enterprise application You carry out these steps using SAP NetWeaver Developer Studio.

Step 1. Create a Java Project and Implement the Login Module Class

In SAP NetWeaver Developer Studio, create a new Java project by following File > New > Java Project. This starts the project creation wizard. Enter the project name (e.g. MyApplLoginModule) and select the project location. After the project is created you should add to the project classpath the required J2EE server security libraries. Select the project, right-click, and select the project properties. In the Properties window select the Java Build Path view and then in the Libraries tab-strip add the reference to sap.com~tc~je~security_api~impl.jar and sap.com~tc~je~security~impl.jar. In the next wizard step, create the login module implementation class. Select the project, right-click, and follow menu path Project > New > Class. This starts the Java class creation wizard (Figure 8). In my example, the login module class is myAppl.security.jaas.MyApplPasswordLoginModule. In the SAP J2EE server, all login modules must extend the superclass com.sap.engine.interfaces.security.auth.AbstractLoginModule.     In the login module, implement the following methods that are defined as abstract methods in AbstractLoginModule (see com.sap.engine.interface.security.auth.AbstractLoginModule). SAP NetWeaver Developer Studio creates them automatically (as empty methods) in your login modules:

• initialize(): Contains the login module initialization. The container calls this method each time the user authentication process starts.
• login(): Implements the user login process
• commit(): Commits the user login
• abort(): Aborts the user login
• logout(): Implements the user logout process

The myAppl-security-jaas code (available to download at the end of the article) provides an example of the implementation of the login module class myAppl.security.jaas.MyApplPasswordLoginModule. The implementation of the login module is pretty simple. In the initialize() method, the environment variables are set to the security context and the user context is obtained. The most interesting method is the login() method in which the user name and password are checked. If a problem is detected, the system sends a response message with an appropriate problem description to the client (setCallbackStatus() method).

Step 2. Define the Login Module Configuration File

After you create the login module, you need to define the login module configuration file (LoginModuleConfiguration.xml) using the code in Figure 9. The system uses this file to register the login module when deploying the login module enterprise application.     The login module configuration file contains a collection of login modules that are delivered in a particular enterprise application. The login module is defined using the login-module element. This element contains the name of the login module (<display-name element>), the full name of the login module implementation class (package and name), and its short description. In addition, the login module configuration may contain options — such as <name> and <value> — that allow you to define login module parameters.

Create and Deploy the Login Module in an Enterprise Application

To deploy your custom login module, you need to create a new enterprise application project in SAP NetWeaver Developer Studio. Follow menu path File > New > Other > J2EE > Enterprise Application Project, which starts the enterprise application project creation wizard. Similar to the process for the login module project, enter the project name (e.g., MyApplLoginModule-ear) and its location. When the project is created, select it, right-click, and set the reference to the login module project (Figure 10).     Now you can create the enterprise application file (EAR file). In SAP NetWeaver Developer Studio, select the enterprise application project (e.g. MyApplLoginModule-ear project). Right-click and select Export > SAP EAR file options. Enter the name of the EAR file and select its location. The system creates a deployable enterprise application file that you can deploy in the SAP J2EE server. After you create the enterprise application file, use the Deploy View in SAP NetWeaver Developer Studio to deploy the application in SAP J2EE server. Follow menu path Window > Show View > Other… > Deploy View > Deploy View. Select the External Deployable Archives entry, right-click, and select the Add option to add the application archive into the Deploy View pane. To start deployment, select the created application’s archive file, then right-click and select the Deploy option. SAP NetWeaver Developer Studio connects to the configured SAP J2EE server and deploys the enterprise application that contains the newly developed login module. After this login module is deployed successfully in the SAP J2EE server, you can deploy your custom application that uses the login module to authenticate application users.

Use the Custom Login Module in an Application

To use your custom login module, you must reference it in the login-module-configuration element. Figure 11 shows the code for configuring of login-module-configuration element.     As you can see, the configuration uses two login modules: the newly deployed myAppl.security.jaas.MyApplPasswordLoginModule and the BasicPasswordLoginModule login module. The container first calls the methods in MyApplPasswordLoginModule (initialize, login, and commit). If the login fails, the container calls the second module (BasicPasswordLoginModule). If the authentication within the first login module is successful, the second module is never called.