Using Rules for User Mapping in Client Certificate Login Module

Context

ClientCertLoginModule can use different rules to map users authenticated with their certificate to users that exist in the User Management Engine (UME), or to virtual users. It can take different certificate attributes and map them to the specified user or account attribute. For example, it can map the RFC822 Name certificate attribute, which usually contains the subject e-mail address, to the Email user attribute in the UME. For virtual users, you can also specify the default roles of groups the virtual users will have on AS Java.

You define the rules for user mapping by creating sets of login module options.

The following table summarizes the login module options for user mapping.

Name	Possible Values	Description
Rule<n>.UserMappingMode	(case insensitive values)	Required for user mapping. Specifies the user mapping mode. AS Java retrieves users using the value of the specified property.
	LogonID	The mapping property is the logon ID. This is the default value.
	LogonAlias	The mapping property is the logon alias. For users from the ABAP data source, the logon alias may be different from their logon ID. For AS Java users, the logon alias is the same as the logon ID.
	Email	The mapping property is the user's e-mail address (as defined in the corresponding user attribute).
	UserAttribute	The mapping property is a user attribute in the UME. It can be a predefined property or a custom property. For custom properties, you also need to specify Rule<n>.UserMappingAttributeNamespace .
	AccountAttribute	The mapping property is an account attribute (realm, principal, and so on).
	VirtualUser	The authenticated user is mapped to a virtual user. This means that no such user exists in the UME database. Instead, the user is temporarily created for the current session.
Rule<n>.UserMappingAttribute	<attribute name>	If Rule<n>.UserMappingMode is set to `UserAttribute` , this option specifies the name of the user attribute for the mapping.
Rule<n>.UserMappingAttributeNamespace	<attribute namespace>	For custom user attributes, specifies the attribute namespace in the UME.
Rule<n>.VirtualUserDefaultGroups	<comma-separated list of groups (display names)>	Optional. This property is used when the user mapping mode is `VirtualUser` . In this case, AS Java creates a virtual user (which exists only for the current user session) for the user logged with a client certificate by this login module. This property specifies the default groups assigned to the virtual user when it is created.
Rule<n>.VirtualUserDefaultRoles	<comma-separated list of roles (display names)>	Optional. This property is used when the user mapping mode is `VirtualUser` . In this case, AS Java creates a virtual user (which exists only for the current user session) for the user logged with a client certificate by this login module. This property specifies the default roles assigned to the virtual user when it is created.

Note

To create a complete rule for user mapping, you may need to combine these options with other login module options (see the examples below). For more information about the other login module options, see:

Procedure

Using the SAP NetWeaver Administrator, go to the configuration options for the ClientCertLoginModule . For more information, see Managing Login Modules .
Construct the required mapping rules by adding the corresponding sets of login module options (see the examples below).
Save the changes to the login module.

Results

After you have configured ClientCertLoginModule 's options for user mapping, when a user tries to log on, AS Java attempts to map the specified attribute from the user's client certificate to the specified user or account attribute in the UME database. In other words, AS Java will recognize this user as the user whose specific attribute has the same value as the specified certificate attribute.

Example

Example 1: User Mapping by E-Mail

Donna Moore is an employee at the MyCompany corporation. The corporation has issued her a certificate with the following data:

Subject
	CN = d.moore O = MyCompany C = DE
Subject Alternative Name
	RFC822 Name=donna.moore@mycompany.com

In AS Java's UME database, Donna's user account looks like this:

Logon ID	dmoore
Last Name	Moore
First Name	Donna
E-mail Address	donna.moore@mycompany.com

Obviously, the only certificate attribute that matches a user attribute in Donna's account is her e-mail address . The best choice for user mapping in Donna's corporation is therefore to map the value of the RFC822 Name attribute, which contains the e-mail address, to the Email user attribute.

To do this, you need to define the following set of options to the ClientCertLoginModule :

Option	Value
Rule5.AttributeName	rfc822Name
Rule5.getUserFrom	expertmode
Rule5.OID	2.5.29.17
Rule5.UserMappingMode	Email

Example 2: User Mapping for Virtual Users

XYZShop is a company that offers an e-shop for its customers. It also has a contract with MyCompany that MyCompany employees are allowed to order items from that e-shop. MyCompany employees already exist in MyCompany's corporate database, and it is not necessary for XYZShop to have their accounts duplicated in its system as well. When an employee from MyCompany wants to order items from XYZShop, he or she is authenticated on XYZShop with a certificate issued by MyCompany. A virtual user is then created for the current user session. It has the rights to order as a shop visitor.

This user mapping can be done with the following set of ClientCertLoginModule :

Option	Value
Rule1.AttributeName	CN
Rule1.getUserFrom	subjectName
Rule1.UserMappingMode	VirtualUser
Rule1.filterIssuer	MyCompany
Rule1.VirtualUserDefaultRoles	Purchaser
Rule1.VirtualUserDefaultGroups	Shop_Visitors