Achieving SSO With Sun Java System Access Manager and SAML

Print-friendly Version

Single sign-on (SSO) within an enterprise enables users to sign on only once to access all applications of that enterprise. Implementing SSO requires the following:

• An identity provider (IdP) to authenticate users
  
  
• A service provider (SP) to validate the authentication status with the IdP and verify that the authenticated users are authorized to perform the tasks in question

Exchanges of authentication and authorization data between an IdP and an SP are effected by means of an XML standard called the Security Assertion Markup Language (SAML), a product of the Security Services Technical Committee of the Organization for the Advancement of Structured Information Standards (OASIS).

Sun Java System Access Manager supports all versions of the SAML specification, including the recent version 2.0, for authentication and authorization exchanges. For details on Sun Java System Access Manager, see its documentation.

This article explains the basic SAML concepts and describes the steps for achieving SSO with Sun Java System Access Manager 7.1 (henceforth, Access Manager) and the SAML 1.x Web Browser Artifact Profile (defined below). Here, the IdP is Access Manager; the SP is SAP NetWeaver Enterprise Portal 2004s (henceforth, SAP EP), deployed on SAP NetWeaver Application Server Java—the SAP J2EE Engine.

SAML embodies two key concepts:

• Assertion, which is a declaration of facts that contain information on the authentication, authorization, or attributes of a principal (user).
  
  
• Profile, which is a set of rules that define how to embed and extract assertions. A profile describes how the assertions are combined with other objects by an authority, transported from the authority, and subsequently processed at the trusted partner site.
  
  SAML defines two profiles:
  
  
  • Web Browser Artifact Profile, which includes a pointer to the SAML assertion (called an artifact) in the query string—usually the parameter SAMLart—of an HTTP redirect to the SP. The SP in turn makes a direct SOAP/HTTP request to the IdP along with the artifact and obtains the actual SAML assertion in the response. The SAP J2EE Engine implements this profile.
    
    
  • Web Browser POST Profile, which includes a SAML assertion in the response that is sent to the SP by the IdP as part of an HTML form.
    
    The two profiles vary according to how the assertion is exchanged between the IdP and the SP—Access Manager and the SAP J2EE Engine in this article.

SSO authentication and authorization proceeds like this:

1. Through Access Manager, the user accesses an application (such as SAP EP) that is configured for SAML authentication and deployed on the SAP J2EE Engine.
   
   
2. If not authenticated already, the user is authenticated by Access Manager.
   
   
3. Access Manager creates and stores an authentication assertion for the user.
   
   
4. Access Manager invokes the registered plug-ins, including the Name Identifier Mapper. The Name Identifier Mapper maps the authenticated user to his or her name identifier in the authentication assertion and updates it with the mapped identifier.
   
   
5. Access Manager creates an artifact for the assertion and issues an HTTP redirect for the SAML receiver that is registered for the SAP J2EE Engine.
   
   
6. The browser redirects the user to the SAML receiver service on the SAP J2EE Engine.
   
   
7. The SAML receiver on the SAP J2EE Engine forwards the request and the artifact to SAP EP, which is configured with the SAML login module. Next, that login module evaluates the artifact and then retrieves the host name and port number of the IdP (Access Manager) according to the artifact.
   
   
8. The SAML login module on the SAP J2EE Engine generates an assertion request that contains the artifact and sends the request as a Simple Object Access Protocol (SOAP)/HTTP message to Access Manager's SAML SOAP receiver.
   
   
9. Access Manager obtains the corresponding assertion according to the artifact in the assertion request.
   
   
10. Access Manager returns the assertion to the SAML login module.
    
    
11. The module analyzes the assertion and authenticates the user.
    
    
12. As soon as authenticated, the user accesses SAP EP through SSO.

Figure 1 illustrates the process flow.

Figure 1: Process Flow

This section describes how to configure Access Manager to work with the SAP J2EE Engine.

Creating the Site ID for the SAP J2EE Engine
First, create the site ID for the SAP J2EE Engine:

1. Unzip this ZIP file on a machine that runs Access Manager.
   
   
2. Point AM_HOME in the script amgenSiteId to the correct directory.
   
   Note: Perform this step only if you installed Access Manager in a location other than the default (/opt).
   
   
3. Grant the execute permission to amgenSiteId.
   
   
4. Generate the site ID for the SAP J2EE Engine with the command amgenSiteId. For example, type:
   
   % amgenSiteId http://ephost.companyxyz.com:50100
   
   Note: Ensure that the URL does not contain a trailing slash (/).

Important: Keep a record of the ID for later use.

Configuring the Java Virtual Machine's Classpath
Next, add the sap_saml_sso.jar file to the Java virtual machine's classpath of the Web container in which Access Manager is deployed. Typically, you perform this task in the Administration Console of the Web container. For details, see the related documentation.

Be sure to restart the Web container for the change to take effect.

Obtaining Access Manager's Site ID
Now obtain the unique site ID for Access Manager:

1. Log in to Access Manager as amAdmin.
   
   
2. Click the Federation tab and then the SAML tab.
   
   
3. Under Site Identifiers, click the link for the first entry under Instance ID.
   
   The Edit Site Identifier page with the site ID and other related information is displayed. See Figure 2.
   
   
4. Save the site ID (highlighted in Figure 2) in a temporary file for later use.

Figure 2: Edit Site Identifier Page

Registering the SAP J2EE Engine as a Trusted Partner
Next, register the SAP J2EE Engine as a trusted partner in Access Manager:

1. Click Back to SAML on the Edit Site Identifier page.
   
   The home page for configuring SAML in Access Manager is displayed.
   
   
2. Click New under Trusted Partners.
   
   The "Select trusted partner type and profile" wizard is displayed.
   
   
3. Select Artifact under Destination and leave all the other options unchecked. Click Next.
   
   The Add New Trusted Partner page is displayed.
   
   
4. Specify the values as follows and then click Finish.
   
   

   Source ID	The site ID for the SAP J2EE Engine.
   Host List	The IP address of the machine that runs the SAP J2EE Engine.
   Target	The fully qualified name of the machine that runs the SAP J2EE Engine.
   SAML URL	The URL of the SAML receiver on the SAP J2EE Engine—one that's typically in the form of http://SAP_J2EE_host.domainname:portnumber/saml/receiver. In some cases, http might be https.
   Name Identifier Mapper	com.sun.identity.saml.plugins.UidMapper

    
   
5. Click Save.
   
   Access Manager confirms the settings. See Figure 3.
   
   

   Figure 3: SAP J2EE Engineer as a Trusted Partner in Access Manager

    
   
6. Verify that the entry for the SAP J2EE Engine is now displayed under Trusted Partners in the home page for configuring SAML in Access Manager.

Here is the behind-the-scenes logic: The Java class UidMapper implements the NameIdentifierMapper interface, whose method getNameIdentifier returns the value for the NameIdentifier component in the SAML assertion. In effect, UidMapper retrieves the authenticated user data from the Access Manager token and maps it to the user's login ID. That way, that ID matches the NameIdentifier component in the SAML assertion that Access Manager sends to the SAP J2EE Engine.

Creating Users in the SAP J2EE Engine
For simplicity, the example in this article employs simple user mapping, whereby every user in the SAP J2EE Engine has a user entry with the same login ID in Access Manager. However, simple user mapping is not a requirement for SSO. You can achieve a different mapping by customizing the account mapping, name-identifier mapping, and attribute mapping. For details, see Chapter 10 of the Sun Java System Access Manager 7.1 Federation and SAML Administration Guide.

Sun Java System Identity Manager allows centralized, automated, and bulk provisioning of users, roles, and other information to applications from multiple vendors, including SAP EP, SAP R/3, and SAP HR. For details, see the Sun Java System Identity Manager documentation.

As a test, create users in Access Manager by following the procedures in Chapter 6 of the Sun Java System Access Manager 7.1 Administration Guide.

This section describes how to configure SAP NetWeaver Application Server for SAML authentication.

Changing the Startup Mode of the SAML Service
First, ensure that the SAML service always starts when you launch the SAP J2EE Engine:

1. Start SAP J2EE Visual Administrator.
   
   
2. Log in to SAP Visual Administrator.
   
   
3. In the tree view in the left pane, expand Server 0 > Services > Configuration Adapter.
   
   
4. In the tree view in the right pane, expand Configurations > cluster_data > server > cfg > services.
   
   
5. Switch to edit mode by clicking the button with the pencil icon. Click Yes when SAP Visual Administrator prompts you to confirm.
   
   
6. In the right pane, scroll down and double-click "Propertysheet tc~sec~saml~service-runtime."
   
   The Change Configuration dialog box is displayed.
   
   
7. Click the second row, startup-mode.
   
   The "Change property entry" dialog box is displayed. See Figure 4.
   
   

   Figure 4: Change of Startup Mode for SAML Service

    
   
8. In the Custom field, type always and click "Apply custom."
   
   The settings are shown in the "Display configuration" dialog box that is then displayed.
   
   
9. Click OK.

Creating a Destination for the SAML SOAP Receiver
Next, create an HTTP destination for the SAML SOAP receiver in Access Manager:

1. In the left pane of SAP Visual Administrator, click the Cluster tab and expand Server 0 > Services > Destinations.
   
   
2. Click the Runtime tab in the right pane and expand Destinations > HTTP.
   
   
3. Click the New button and type a name for the new destination in the text field, for example, SunAM. Click OK.
   
   
4. Under Connection Settings, type in the URL text field the URL of Access Manager's SAML SOAP receiver, for example, http://ephost.companyxyz.com:8080/amserver/SAMLSOAPReceiver.
   
   As a test here, use an insecure channel with no client authentication, that is, the None setting under Authentication. In a production environment, specify a secure channel with client authentications, such as BASIC, SSL, and the like.
   
   
5. Click Save. See Figure 5.
   
   

   Figure 5: Destination for Access Manager's SAML SOAP Receiver

    
   

Configuring the SAML Service
Now configure the SAML service on the SAP J2EE Engine:

1. In the left pane of SAP Visual Administrator, click the Cluster tab and expand Server 0 > Services > Configuration Adapter.
   
   
2. In the right pane, click the Runtime tab and scroll down. Expand SAML > Configuration > PartnersInbound.
   
   
3. Switch to edit mode by clicking the button with the pencil icon. Click Yes when SAP Visual Administrator prompts you to confirm.
   
   
4. Right-click the PartnersInbound node and choose Create Sub Node from the context menu.
   
   
5. Type a name for the partner in the text field, for example, SunAM. Click Create.
   
   
6. Expand the newly created node and specify the values as follows:
   
   
   • Destination Name: Type the name of the destination you created in the preceding section.
     
     
   • SourceID: Type the site ID of Access Manager you obtained in a previous section. That ID starts with B64, for example, B64:Gz5Ie6oAgITQsmjxfsDyru/jtiM=.
   
   
7. As a test, set the PermitInsecureConnections parameter under Configurations > saml > Configuration > Settings to true. See Figure 6.
   
   

   Figure 6: SAML Service Parameters

    
   
Note: In a production environment, set PermitInsecureConnections to false.

Adding the SAML Login Module to the Application's Login Module Stack
Next, add the SAML login module to the application's login module stack, as follows. In this example, you modify the ticket template used by SAP EP.

1. In the left pane of SAP Visual Administrator, click the Cluster tab and expand Server 0 > Services > Security Provider.
   
   
2. Click the Policy Configuration tab and select ticket in the Components pane.
   
   
3. Switch to edit mode by clicking the button with the pencil icon. Click Yes when SAP Visual Administrator prompts you to confirm.
   
   
4. Click Modify on the right pane and adjust the login module stack so that it appears as shown in Figure 7. Afterward, close SAP Visual Administrator.
   
   

   Figure 7: Addition of SAML Login Module to Login Module Stack

    
   
5. Restart the SAP J2EE Engine.

Finally, test the SSO mode in SAP EP with SAML assertions:

1. Go to the SSO trigger for SAP EP, for example, http://ephost.companyxyz.com:8080/amserver/SAMLAwareServlet?TA RGET=http://ephost.companyxyz.com:50100/irj/portal.
   
   SAP EP prompts you to authenticate to Access manager.
   
   
2. Log in as one of the users—for example, Administrator—you created in a previous section.
   
   SAP EP displays the welcome page. See Figure 8.
   
   

   Figure 8: Welcome Page of SAP EP

    
   

• Sun Java System Access Manager
  • Main page
  • Developer home
  • Developer Forum
  • Documentation
  • Federation and SAML Administration Guide
  
  
• Related publications
  • Sun Java System Identity Manager 7 documentation
  • Article: Using SAML Assertions for Single Sign-On
  
  
• Sun developer services
  • Support
  • Training and certification