This Wiki describes the features for configuring BasicPasswordLoginModule and ClientCertLoginModule, and for setting a policy configuration that uses a third-party login module.

The features described in that Wiki are valid for the following releases:

• NW 7.3 SP7 or later versions
• NW 7.31 SP3 or later versions

Table of Contents

User Mapping Options for BasicPasswordLoginModule

This login module maps users authenticated with their passwords to users in the User Management Engine (UME).

The system allows the following options for the basic password login module:

Scenario of Using BasicPasswordLoginModule

Denise wants to configure her system to allow her customers to authenticate with logon ID and e-mail. That way the users will be able to log into the system by entering username or e-mail address. For that purpose she configures her authentication stack with two modules with name BasicPasswordLoginModule by the following steps:

1. She chooses Configuration → Authentication and Single Sign-On → Authentication → Components from the SAP NetWeaver Administrator and selects the name of her policy configuration named Denise_Basic_Password_Config.
2. After choosing the Edit button, she adds the two modules named BasicPasswordLoginModule.
3. She adds the value Email for the user mapping mode of the second module.

Denise asks her customer Michael to test her system. When Michael enters username and password, he is successfully authenticated by the first login module. When he tries with e-mail address and password, the first basic password login module fails, but the second one succeeds and logs Michael in.

User Mapping Options for ClientCertLoginModule

This login module maps users authenticated with their certificates to users in the User Management Engine (UME).

The system allows the following options for the client certificate login module:

Scenario of Using ClientCertLoginModule

Donna Moore wants to configure her system to use the subject alternative name from the certificate of each user that logs into the system. She also knows that she has to map that name to the Email user attribute because the e-mail address is the only value that matches between the data in the UME and in the certificate. The users of Donna’s system are the employees of her organization MyCompany. For that purpose she does the following configuration:

1. She chooses Configuration → Authentication and Single Sign-On → Authentication → Components and selects the name of her policy configuration.

2. She adds the ClientCertLoginModule with the following four options:

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

   That way she specifies that the value of the rfc822Name attribute from the certificate maps to the Email user attribute.

3. After she saves her entries she asks her colleague Michael Adams to test the system.

The company has issued Michael a certificate with the following data:

On the other side, Michael’s account in the UME has the following data:

Because the RFC822 Name attribute of the certificate maps to the e-mail user attribute in the UME, Michael is able to log into the system.

User Mapping Properties in the Policy Configuration

You can use any user mapping properties for the policy configuration, but some of these properties are not applicable to all login modules. You configure these properties with the authentication stack properties under the Properties tab. The system supports the following properties:

• User Mapping Mode
  This property takes the name UserMappingMode. The user mapping mode tells the system how to look for the user in the UME. When the user successfully authenticates with the login module, the system obtains a principal set by the login module for that user. If you don not configure the user mapping, then the system uses the default mapping value which is the logon ID. You can configure the following values for the user mapping modes:
  • LogonID
    That is the default mapping mode value. In that case the system searches in the UME for a user with a logon ID that is equal to the principal name set by the login module.
  • LogonAlias
    The system searches in the UME for a user with a logon alias equal to the principal name set by the login module.
  • Email
    The system searches in the UME for a user with an e-mail address that is equal to the principal name set by the login module.
  • UserAttribute
    The system searches in the UME for a user with a user attribute equal to the principal name set by the login module. You have to specify the user attribute name and (optionally) namespace with the options UserMappingAttribute and UserMappingAttributeNamespace.
  • AccountAttribute
    The system searches in the UME for a user with an account attribute equal to the principal name set by the login module. You have to specify the account attribute name and (optionally) namespace with the options UserMappingAttribute and UserMappingAttributeNamespace.
  • VirtualUser
    The system searches in the UME for a user with a logon ID equal to the principal name set by the login module. If the system cannot find such a user, it creates a virtual user that exists temporarily for the current user session. The principal name is set as the logon ID of the virtual user. You can assign default roles and groups to the created virtual user with the policy configuration properties.
• User Mapping Attribute
  It takes the name UserMappingAttribute. This option is used only for user mapping modes UserAttribute and AccountAttribute. It specifies the name of the user or the account attribute for the mapping.
• User Mapping Attribute Namespace
  It takes the name UserMappingAttributeNamespace. This option is used only for user mapping modes UserAttribute and AccountAttribute. It is optional and specifies the attribute namespace in the UME. If it is not specified, the system uses the default UME namespace, which is com.sap.security.core.usermanagement.
• Virtual User Default Groups
  It takes the name VirtualUserDefaultGroups. This option is not mandatory. It is used only for a user mapping mode value VirtualUser. It specifies the groups to be assigned to the virtual user when it is created. It can contain a comma separated list of group names.
• Virtual User Default Roles
  It takes the name VirtualUserDefaultRoles. This option is not mandatory. It is also used only for a user mapping mode value VirtualUser. It specifies the roles to be assigned to the virtual user when it is created. It can contain a comma separated list of role names.
• User Mapping Regular Expression
  This property is optional and takes the name UserMappingRegex. You can use a regular expression to extract a substring from the principal name used afterwards for user mapping. The regular expression must have a group that shows what part of the principal is extracted for the mapping. The regular expression option is not applicable to most of the login modules, but you can use it for third-party login modules.
• Property for Creating Logon Tickets
  This property takes the name create_ticket. If its value is assigned to true, the system creates logon tickets that allow the user to log into the system multiple times during the current session after the first login. That way this property represents the single sign-on feature.

Scenario of Integrating a Third-Party Login Module in the Policy Configuration

Donna Moore has a company named MyCompany with a system that contains a portal, an active directory that identifies users from a domain, and an AS ABAP server. The portal system is configured with AS ABAP user store and reads the user from that store. Furthermore, the credentials that the user provides are checked in the active directory and after authentication on the portal, the system creates a ticket for accessing the AS ABAP system.
Donna wants her system to identify the user by his or her logon alias. She also wants to use only part of the principal name for further authentication at the AS ABAP system. For that purpose she sets a filter as a regular expression.
For her system’s configuration, she does the following settings:

1. She creates a third-party login module KRB5LoginModule by choosing Configuration → Authentication and Single Sign-On → Authentication → Login Modules and the Create button.
2. She creates a login policy Donna_Policy_Config of type Custom by choosing the Components tab.
3. After choosing the Edit button, she adds the third-party login module to the authentication stack.

4. She creates three properties by choosing the Properties tab.

   User Mapping Property	Value
   UserMappingMode	LogonAlias
   UserMappingRegex	(.+)\Q@company.de\E
   create_ticket	true

   
   

5. After she saves her entries, she tests her system with one of her users Michael Adams.

 The authentication process follows these five steps:

1. Provide credentials.
   When Michael tries to log into the portal, the system asks him to enter username and password.
2. Check user credentials.
   After Michael enters his credentials, KRB5LoginModule checks the user credentials with the active directory. The module finds such a user in the active directory and creates a third-party principal with name michaeladams@company.de.
3. Authenticate user.
   That principal is further evaluated through the user mapping properties. The regular expression property checks if the principal matches the regular expression pattern <name>@company.de. Because the principal matches such a pattern, the regular expression filter evaluates the principal and returns the value michaeladams, which is the first group in this regular expression.  The user mapping mode property LogonAlias instructs the login module to look for a logon alias with the name michaeladams on the AS ABAP server. The system finds such an alias and authenticates Michael on the portal.
4. Create ticket.
   Because the property create_ticket is set to true, the system issues a logon ticket as a cookie in the browser with user ID michael. This ticket allows Michael to log into the AS ABAP system.
5. Access AS ABAP resources.
   Because the system has issued Michael a logon ticket and he is authenticated on the portal, he can access the resources of the AS ABAP system.