Authentifizierungs-Plugin 'Netweaver'
-------------------------------------
Version: 1.0 (core 2.8.1.3)

Projectile untersttzt die Athentifizierung via SAP NetWeaver(tm) Single Sign-On (SSO).
Das bietet die Mglichkeit, den Anmeldevorgang in Projectile zu vereinfachen.
Ein authentifizierter Mitarbeiter erhlt auf dem Login-Bildschirm einen Link,
mit dem er sich Anmelden kann, ohne Kennung und Passwort einzugeben.

Um dieses Feature zu benutzen sind folgende Schritte bzw. Voraussetzungen zu treffen.

1. Einrichtung des Netweaver J2EE-Servers, so dass ein Cookie mit einem
   SAP-Security-Ticket bermittelt wird.
2. Einrichtung des Netweaver-Authentifizierungs-Plugin im Projectile-Server.


1. Einrichtung des Netweaver J2EE-Servers
-----------------------------------------

Hierzu verweisen wir auf die Dokumentation bzw. Dienstleistungen
des J2EE-Server-Herstellers.


2. Einrichtung des Netweaver-Authentifizierungs-Plugin im Projectile-Server
---------------------------------------------------------------------------

Zunchst mu das Authentifizierungs-Plugin aktiviert werden. Im Verzeichnis
config auf dem Projectile-Server befinden sich die beiden Dateien:

AuthenticationPluginConfig_Default.xml
AuthenticationPluginConfig_Netweaver.xml

Die erste Datei konfiguriert die Standard-Authentifizierung via Login/Passwort.
Die zweite konfiguriert die SAP Netweaver-Authentifzierung. Beide Plugins
mssen aktiviert werden. Die Konfigurationsdateien sollten etwa folgenden
Inhalt haben:

AuthenticationPluginConfig_Default.xml:
-------------------------------------------------------------------------------
<?xml version="1.0" encoding="UTF-8"?>

<AuthenticationPluginConfig>
        <Name Type="STRING" Size="50" IsKey="1">Default</Name>
        <Active Type="BOOLEAN" IsKey="0">1</Active>
        <Method Type="STRING" Size="50" IsKey="0">LoginPassword</Method>
        <ExecutionOrder Type="INTEGER" IsKey="0">5</ExecutionOrder>
</AuthenticationPluginConfig>
-------------------------------------------------------------------------------

AuthenticationPluginConfig_Netweaver.xml:
-------------------------------------------------------------------------------
<?xml version="1.0" encoding="UTF-8"?>

<AuthenticationPluginConfig>
        <Name Type="STRING" Size="50" IsKey="1">Netweaver</Name>
        <Active Type="BOOLEAN" IsKey="0">1</Active>
        <Method Type="STRING" Size="50" IsKey="0">Netweaver</Method>
        <ExecutionOrder Type="INTEGER" IsKey="0">0</ExecutionOrder>
        <CookieName Type="STRING" Size="250" IsKey="0">MYSAPSSO2</CookieName>
        <Keystore Type="STRING" Size="250" IsKey="0">config/keystore</Keystore>
        <KeystorePassword Type="STRING" Size="250" IsKey="0">C02:vCm/Pj++ue+iDQ7LLDOonQ==</KeystorePassword>
</AuthenticationPluginConfig>
-------------------------------------------------------------------------------

Die Konfigurationsfelder haben folgende Bedeutung:

Name: Name des Plugins (bitte nicht ndern)
Active: Plugin ist aktiv (sollte in beiden Plugins auf 1 stehen)
Method: Authentifizierungsmethode (bitte nicht ndern)
ExecutionOrder: Reihenfolge der Ausfhrung der Plugins (kleinerer alphabetischer 
                Wert wird zuerst ausgefhrt)
CookieName: Name des Cookie, welches das SAP-Netweaver-Ticket enthlt
Keystore: Dateiname des J2EE-Keystore, welcher die Zertifikate des J2EE-Servers enthlt
KeystorePassword: Passwort fr den Zugriff zum Keystore (das Passwort kann, wie
                  in diesem Beispiel verschlsselt eingegeben werden - siehe dazu
                  Administrationsleitfaden: Verschlsselung von Datenbank-Kennwrtern)

Das Zertifikat des SAP-Servers mu vorher in den Keystore importiert werden.
Siehe hierzu den beigefgten Ausschnitt aus der SAP-Originaldokumentation.


3. Logging
----------

Das Standard-Log fr SSO ist logs/sso.log. Log-Level und Logging-Konfiguration
kann in der log4j-Konfiguration: config/bsm.log4j.properties abgendert werden.


4. Libraries
------------

Das Netweaver-Authentifizierungs-Plugin bentigt folgende jar-Dateien:

com.sap.security.api.jar 
com.sap.security.core.jar  
iaik_jce.jar  
sap.logging.jar

Diese Dateien sollten unter thirdparty/tomcat/webapps/projectile/WEB-INF/lib
abgelegt werden.


5. Ausschnitt aus der Original-Dokumentation von SAP
----------------------------------------------------

Enabling Single Sign-On from SAP J2EE Engine/EP to Non-SAP Java Applications

Summary 

SAP NetWeaver(tm) enables Single Sign-On (SSO) as the standard secure 
authentication mechanism for Web-based applications in an SAP NetWeaver 
based landscape. In this scenario one central component (SAP J2EE engine either 
standalone or with a deployed SAP Enterprise Portal) is issuing a cookie-based 
logon ticket accepted by all other systems in the landscape. This mechanism is 
currently supported by all major SAP components. For non-SAP based applications 
similar approaches have already been described to extend to .Net applications 
(Enabling Single Sign-On for ASP.NET Applications). The focus of this article 
is a detailed step-by-step guide on how to extend SSO to a Java-based Web 
application NOT running on the SAP J2EE Engine. We will walk you through an 
example of creating a servlet which will receive an SAP logon cookie, validate 
it, and extract the name of the logged-on user. In the attachments you will 
find the source code and a complete .war file ready for deployment.
By Tim Mull, Stephan Boecker

31 Aug 2004
 
Scenario
The user logs on to a J2EE or portal environment and receives a logon ticket in the 
form of a cookie. If he now calls the URL of your Java application (like our servlet 
example) via his browser the cookie wil be validated. In order to do so the receiving 
application needs to have access to the certificate of the issuing J2EE/portal in 
order to verify a digital signature and the identity of the issuing party. The 
certificate has to be exported from the J2EE Engine and imported in a key store 
located on the receiving side. After checking the digital signature, the information 
in the ticket will be extracted and the user will be considered authenticated by the 
receiving application.

Preparations

1. Get the Java Libraries from the J2EE Engine

In order to verify a Single Sign-On ticket sent with a browser request to your 
web application you need the following SAP libraries which you can extract from 
the file system of any J2EE Engine 6.30 or higher (or from your Enterprise Portal 
EP60 SP2 or higher) by searching through the SDA files containing the libraries. 

* com.sap.security.core.jar
* com.sap.security.api.jar
* sap.iaik_jce.jar
* sap.logging.jar 

In case you use the export version of the IAIK libraries you can as well use the 
sap.iaik_jce_export.jar library. Make sure these libraries are included in your .war 
file holding your web application. They are also included in our example .war file.

2. Create a Key Store on Your File System to Hold the Portal Certificate

Create a directory on your Web server's file system to hold the key store data. 
Change to that directory and execute the keytool.exe program to create the key 
store, e.g. enter:

    %JAVA_HOME%/bin/keytool -genkey -keystore portal.store
    
This will create a key store in a file called portal.store. The program will prompt 
you for further information: 

* A password for the key store: enter a password. 

* Your personal information to create your own key pair: enter first and last name, 
organizational unit, organization, city, state and country. Since we do not need 
this information within the new created keypair we used 'Dummy' for the name, 'US' 
for the country and left all other entries blank. When asked if entries are correct, 
enter 'Y(es)'.

* A password for the key; press 'Enter' to use the same password already specified 
for the key store. 

3. Export the J2EE Engine .CRT File or Portal .Der File Containing the Certificat

In case of a J2EE engine > 6.30 you can extract the certificate using the J2EE admin 
tool (under ...j2ee/admin/go.bat). Log onto your J2EE engine as a member with 
administrative rights and navigate in the left pane to Server -> Services -> KeyStorage. 
The TicketKey store view contains the certificate which you can download by selecting 
the SAPLogonTicketKeypair-cert Entry and choosing Export in the area on the right 
called Entry. In the popup choose the X.509 certificate format for the download. 

Figure 1.
In case of an Enterprise Portal, log onto your Enterprise Portal as a member of 
the system administration group. Navigate to System Administration -> 
System Configuration. In the detailed Navigation choose Keystore Administration. 
On the Content tab the Portals certificate is displayed.

Figure 2.

Choose the Download verify.der file button to download a .zip file containing 
the portals .der file to the file system. Extract the .der file. 

4. Import Certificate into the Key Store

Execute the Java keytool.exe program again to import the certificate into your 
key store. Enter:

    %JAVA_HOME%/bin/keytool -import -keystore portal.store -alias Portal -file verify.der
    
This imports the certificate in file verify.der into the key store assigning the alias 
'Portal' to this certificate entry. You will be prompted for the password to access 
the key store. If the password is correct the certificate fingerprint will be presented 
to you and you will be prompted to enter Y(es) to ensure you want to import this 
certificate. 

5. Check Domains

Make sure that the J2EE Engine and your Web server are running in the same DNS domain. 
Otherwise cookies issued by the J2EE engine will not be transferred to your web server 
by the user's browser. 

Source Code

Servlet Initialization 

In the init method of the servlet, two parameters are read: one defining the full 
path to the key store file and the second holding the password to this key store. 
Note that for productive use you should come up with a more secure place to store 
the password for the key store access. After those parameters are read, the key store 
is opened and the containing certificates are read into a singleton instance of 
SAPTicketverifier. The following code snippet shows the details:

Figure 3.

Request Processing

In the doPost method the incoming request is processed and the user's name is printed 
with the help of the method getUserFromRequest. 

Figure 4.

This method extracts the SSO cookie, converts it to base64 and feeds the result 
into the SAPTicketVerifier instance for verification. For further technical details 
look at the class SAPTicketverifier itself, whose source code is available. 

Attachments

These files contain: 

* The source code of our example servlet

* A .war file ready for deployment. We checked this .war file against a Tomcat 
5.0.27 server instance. In order to run it as is, you need to provide a file 
named portal.store containing the J2EE Engine certificate in a directory named 
C:\keystore. If you need other settings, change the corresponding init parameters 
in the file web.xml. 

Authors

Tim Mull is with Lighthammer, www.lighthammer.com and Stephan Boecker is with SAP. 





