com.sap.security.api.umap

Interface IUserMapping

public interface IUserMapping

Provides an entry point to the user mapping functionality.

In order to get user mapping information for a specific principal, call getUserMappingData(ISystemLandscapeObject, IPrincipal).

In order to get the ABAP user ID corresponding to an IUser object, call getR3UserName(IUser, ISystemLandscapeObject, boolean).

In order to make a reverse lookup from a mapped backend user ID to a local user, call getInverseMappingData(String mappedUser, ISystemLandscapeObject).

Please note: The corresponding methods using system alias strings instead of ISystemLandscapeObject objects are deprecated. You can get an ISystemLandscapeObject object like this:

 import java.util.ArrayList;
 import com.sap.security.api.UMFactory;
 import com.sap.security.api.umap.system.ISystemLandscapeWrapper;
 
 ArrayList systemLandscapes = UMFactory.getSystemLandscapeWrappers();
 // Until now, there's only one system landscape implementation available:
 // The system landscape which is part of SAP Enterprise Portal.
 ISystemLandscapeWrapper systemLandscape =
     (ISystemLandscapeWrapper) systemLandscapes.get(0);
 

If you know you only need

• the SAP logon ticket of a user or
• user mapping for the SAP reference system or
• inverse user mapping data for the SAP reference system

you don't need to pass a real ISystemLandscapeObject. Instead, you can simply pass null as system parameter to IUserMapping methods.

For example, if you'd like to simply retrieve a user's logon ticket (if available), you can use the following code:

 IUser user = ...; // This MUST be an authenticated user, e.g. retrieved by
                   // IAuthentication.getLoggedInUser(...)
 IUserMapping userMapping = ...;
 userMapping.getUserMappingData(null, user);
 Properties jcoProperties = new Properties();
 mappingData.enrich(jcoProperties);
 String logonTicket = jcoProperties.getProperty(IUserMappingData.UMAP_JCO_PASSWORD);
 

Field Summary

static String	UMAP_ENCRYPTION_ALGO_ALIAS For internal use.
static String	UMAP_ENCRYPTION_KEYTYPE_ALIAS For internal use.
static String	UMAP_EP6_ALIAS_PREFIX Internal prefix for Enterprise Portal system IDs in user mapping.
static String	UMAP_R3_MASTER For internal use.
static String	UMAP_R3_MASTER_UID_MODE For internal use.
static String[]	UMAP_SYSTEM_FIELDS Deprecated. This array of constants should not be used any more.
static String	UMAP_SYSTEM_TYPE System attribute name for the type of backend system.
static byte	UMAP_SYSTEM_TYPE_EP6_ALIAS Deprecated. This constant is no longer valid and there's no replacement.
static String	UMAP_SYSTEMATTRS_LOGONMETHOD System attribute name for logon method of a backend system.
static String	UMAP_SYSTEMATTRS_R3NAMEREF Deprecated. System attribute name to flag a backend system as SAP reference system for UME. This logic is no longer supported. Instead, the SAP reference system is defined in UME configuration property "ume.r3.mastersystem" (see ILoginConstants.R3_MASTERSYSTEM).
static String	UMAP_SYSTEMATTRS_TICKET_TYPE System attribute for the type of authentication ticket to be used for connections to a backend system.
static String	UMAP_TICKET_TYPE_ASSERTION Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: SAP Authentication Assertion Tickets.
static String	UMAP_TICKET_TYPE_LOGON Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: Use SAP Logon Tickets.
static String	UMAP_USERMAPPING_FIELDS System attribute name for additional user mapping fields that can be defined for a backend system.
static String	UMAP_USERMAPPING_TYPE System attribute name for "user mapping type" of a backend system.

Method Summary

boolean	checkCryptoConfiguration(String systemId) Check whether the configuration of cryptography usage in user mapping is valid for the given system.
boolean	existsMappingData(ISystemLandscapeObject system, IPrincipal principal) Check whether user mapping data for the specified system and principal exists.
com.sap.security.api.umap.IUserMappingConverter[]	getAvailableConverters() For internal use only.
Map	getInverseMappingData(String[] mappedUsers, ISystemLandscapeObject system) Optimized batch processing version of getInverseMappingData(String,ISystemLandscapeObject) for a whole set of backend user IDs.
String	getInverseMappingData(String mappedUser, ISystemLandscapeObject system) Search for users which are mapped to the given user ID in the specified backend system.
String	getInverseMappingData(String sysid, String userid, byte system_type) Deprecated. Please don't use this method any more, but use getInverseMappingData(String, ISystemLandscapeObject) instead.
Set	getMappedSystemsForPrincipal(IPrincipal principal) Determine all systems for which the specified principal has user mapping data.
String	getR3UserName(IUser user, ISystemLandscapeObject system, boolean bGenerateId) Determine the ABAP user ID of the provided user in the specified backend system.
String	getR3UserName(IUser principal, String sysid, Map sysAttrBag, boolean bGenerateId) Deprecated. Please don't use this method any more, but use getR3UserName(IUser,ISystemLandscapeObject,boolean) instead.
IUserMappingData	getUserMappingData(ISystemLandscapeObject system, IPrincipal principal) Retrieve an IUserMappingData object to perform user mapping activities for the specified principal and backend system.
IUserMappingData	getUserMappingData(String sysid, IPrincipal principal, Map sysAttrBag) Deprecated. Please don't use this method any more, but use getUserMappingData(ISystemLandscapeObject,IPrincipal) instead.

Field Detail

UMAP_SYSTEMATTRS_LOGONMETHOD

public static final String UMAP_SYSTEMATTRS_LOGONMETHOD

System attribute name for logon method of a backend system.

Potential values:

• ILoginConstants.SSO_JCO_LOGON_METHOD_TICKET
• ILoginConstants.SSO_JCO_LOGON_METHOD_UIDPW
• ILoginConstants.SSO_JCO_LOGON_METHOD_X509CERT

To be used with ISystemLandscapeObject.getAttribute(String).

See Also:

Constant Field Values

UMAP_SYSTEMATTRS_TICKET_TYPE

public static final String UMAP_SYSTEMATTRS_TICKET_TYPE

System attribute for the type of authentication ticket to be used for connections to a backend system.

Only relevant if the system's logon method is set to SAPLogonTicket.

Potential values:

• UMAP_TICKET_TYPE_LOGON
• UMAP_TICKET_TYPE_ASSERTION

See Also:

Constant Field Values

UMAP_TICKET_TYPE_LOGON

public static final String UMAP_TICKET_TYPE_LOGON

Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: Use SAP Logon Tickets.

See Also:

Constant Field Values

UMAP_TICKET_TYPE_ASSERTION

public static final String UMAP_TICKET_TYPE_ASSERTION

Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: SAP Authentication Assertion Tickets.

See Also:

Constant Field Values

UMAP_SYSTEMATTRS_R3NAMEREF

public static final String UMAP_SYSTEMATTRS_R3NAMEREF

Deprecated.

System attribute name to flag a backend system as SAP reference system for UME.

This logic is no longer supported. Instead, the SAP reference system is defined in UME configuration property "ume.r3.mastersystem" (see ILoginConstants.R3_MASTERSYSTEM).

See Also:

Constant Field Values

UMAP_USERMAPPING_FIELDS

public static final String UMAP_USERMAPPING_FIELDS

System attribute name for additional user mapping fields that can be defined for a backend system.

To be used with ISystemLandscapeObject.getAttribute(String).

See Also:

Constant Field Values

UMAP_USERMAPPING_TYPE

public static final String UMAP_USERMAPPING_TYPE

System attribute name for "user mapping type" of a backend system.

If the attribute value contains the string "user", user mapping data for the system can be defined by the affected end-user. If the attribute value contains the string "admin", user mapping data for the system can be defined by a user administrator.

To be used with ISystemLandscapeObject.getAttribute(String).

See Also:

Constant Field Values

UMAP_SYSTEM_TYPE

public static final String UMAP_SYSTEM_TYPE

System attribute name for the type of backend system.

This attribute should be filled at least for SAP ABAP systems and may have values like "SAP_R3", "SAP_BW", "SAP_CRM".

To be used with ISystemLandscapeObject.getAttribute(String).

See Also:

Constant Field Values

UMAP_EP6_ALIAS_PREFIX

public static final String UMAP_EP6_ALIAS_PREFIX

Internal prefix for Enterprise Portal system IDs in user mapping.

See Also:

Constant Field Values

UMAP_SYSTEM_TYPE_EP6_ALIAS

public static final byte UMAP_SYSTEM_TYPE_EP6_ALIAS

Deprecated. This constant is no longer valid and there's no replacement.

See Also:

Constant Field Values

UMAP_SYSTEM_FIELDS

public static final String[] UMAP_SYSTEM_FIELDS

Deprecated. This array of constants should not be used any more.

UMAP_ENCRYPTION_KEYTYPE_ALIAS

public static final String UMAP_ENCRYPTION_KEYTYPE_ALIAS

For internal use.

See Also:

Constant Field Values

UMAP_ENCRYPTION_ALGO_ALIAS

public static final String UMAP_ENCRYPTION_ALGO_ALIAS

For internal use.

See Also:

Constant Field Values

UMAP_R3_MASTER

public static final String UMAP_R3_MASTER

For internal use.

See Also:

Constant Field Values

UMAP_R3_MASTER_UID_MODE

public static final String UMAP_R3_MASTER_UID_MODE

For internal use.

See Also:

Constant Field Values

Method Detail

getUserMappingData

public IUserMappingData getUserMappingData(ISystemLandscapeObject system,
                                           IPrincipal principal)

Retrieve an IUserMappingData object to perform user mapping activities for the specified principal and backend system.

Parameters:

system - The system object for the backend system.
May be null if you only need an authentication ticket (e.g. SAP logon ticket) for the principal. If there is a valid SAP reference system defined in UME configuration, null will be internally substituted by the reference system. Providing null as backend system is NOT valid if there is no SAP reference system and you use IUserMappingData.enrich(Map) or IUserMappingData.saveLogonData(Map).

principal - The principal for which user mapping data is requested. In most cases, this will be an IUser object.

Returns:

The user mapping data object that provides access to the actual mapped logon data.

getUserMappingData

public IUserMappingData getUserMappingData(String sysid,
                                           IPrincipal principal,
                                           Map sysAttrBag)

Deprecated. Please don't use this method any more, but use getUserMappingData(ISystemLandscapeObject,IPrincipal) instead.

getR3UserName

public String getR3UserName(IUser principal,
                            String sysid,
                            Map sysAttrBag,
                            boolean bGenerateId)
                     throws UMException

Deprecated. Please don't use this method any more, but use getR3UserName(IUser,ISystemLandscapeObject,boolean) instead.

Throws:

UMException

getInverseMappingData

public String getInverseMappingData(String sysid,
                                    String userid,
                                    byte system_type)
                             throws NoLogonDataAvailableException,
                                    UMException

Deprecated. Please don't use this method any more, but use getInverseMappingData(String, ISystemLandscapeObject) instead.

Throws:

NoLogonDataAvailableException

UMException

getR3UserName

public String getR3UserName(IUser user,
                            ISystemLandscapeObject system,
                            boolean bGenerateId)
                     throws UMException

Determine the ABAP user ID of the provided user in the specified backend system.

The return value is as follows:

Logon method

Return value

SAPLogonTicket

Value of ume.r3.mastersystem.uid.mode	Return value
0	the backend user ID if one is maintained, otherwise null
1	the backend user ID if one is maintained, otherwise the local logon ID
2	the backend user ID if one is maintained, otherwise one is generated and stored in the user mapping (unless bGenerateId is false, in which case null is returned). Please note that this is currently not implemented and throws a RuntimeException.

UIDPW

the backend user ID if one is maintained, otherwise null

X509CERT

null (since, in this case, there is no logon ID passed to the ABAP system as part of the authentication credentials; instead, the ABAP system has its own mapping from the X.509 certificate to the local ABAP logon ID)

Parameters:

user - The local user for which the mapped user ID is requested

system - The backend system for which the mapped user ID is requested. May be null to express that you need the mapped user ID for the SAP reference system (i.e. the mapped user ID that is contained in SAP logon tickets).

bGenerateId - Flag that controls the generation of ABAP user IDs (currently not implemented, please see explanation above - please always set to false.).

Returns:

mapped user ID in the backend system

Throws:

UMException

getInverseMappingData

public String getInverseMappingData(String mappedUser,
                                    ISystemLandscapeObject system)
                             throws NoLogonDataAvailableException,
                                    MultipleHitException,
                                    UMException

Search for users which are mapped to the given user ID in the specified backend system.

Even if no mapping is maintained, a non-null value is returned if the following conditions apply:

• The logon method of the backend system is SAPLogonTicket
• The value of the parameter ume.r3.mastersystem.uid.mode is 1
• A user with the specified mapped backend user ID exists in UME

In this case the unique ID of the UME user with logon uid mappedUser is returned. In other words: Like with getR3UserName(IUser,ISystemLandscapeObject,boolean), identity mapping between equal user IDs in the backend system and the local system should always work (in this case in the opposite direction) without manual maintenance of user mapping data. If this behaviour is not convenient, it can be switched off by settting UME property ume.r3.mastersystem.uid.mode=0.

Parameters:

mappedUser - The mapped backend user ID the user searched for has maintained.

system - The backend system to which the mapped user ID applies. If null, the system identified by UME configuration property ume.r3.mastersystem is used. If no system landscape is available (usually if there is no SAP Enterprise Portal installed), the call behaves as if no user mapping was available for a system with logon method SAPLogonTicket.

Returns:

unique ID of the (single) user that has maintained the specified backend user ID for the provided system. To retrieve the corresponding IUser object, call IUserFactory.getUser(String)

Throws:

NoLogonDataAvailableException - If no user with the provided backend user ID could be found

MultipleHitException - If more than one user are mapped to the specified user ID in the backend system. In order to get the unique IDs of all matching users, you can use MultipleHitException.getUserNames().

UMException - If some internal operation fails unexpectedly.

getInverseMappingData

public Map getInverseMappingData(String[] mappedUsers,
                                 ISystemLandscapeObject system)
                          throws UMException

Optimized batch processing version of getInverseMappingData(String,ISystemLandscapeObject) for a whole set of backend user IDs.

The logic is identical except that exceptions thrown while processing a single (inverse) user mapping - i.e. which don't affect the whole call - are not rethrown, but only logged. The intention is to provide robustness of this mass call against problems that only affect single users / single user mapping entries.

Parameters:

mappedUsers - Array of the mapped backend user IDs

system - The backend system for which to search for matching users. May be null, see getInverseMappingData(String,ISystemLandscapeObject).

Returns:

Result map. Each entry contains the mapped user ID (i.e. a single entry of mappedUsers[]) as key and the corresponding IUser object (or null if no such mapping exists) as value.

Throws:

UMException - If an unexpected problem occurs

existsMappingData

public boolean existsMappingData(ISystemLandscapeObject system,
                                 IPrincipal principal)
                          throws UMException

Check whether user mapping data for the specified system and principal exists.

Parameters:

system - The system for which to search for user mapping data. Must not be null.

principal - The principal for which to search for user mapping data.

Returns:

true if a mapping for the specified system and principal was found, false if no mapping was found.

Throws:

UMException - If some unexpected problem occurs

getMappedSystemsForPrincipal

public Set getMappedSystemsForPrincipal(IPrincipal principal)
                                 throws UMException

Determine all systems for which the specified principal has user mapping data.

Parameters:

principal - The principal for which to check for user mapping data

Returns:

Set containing IDs (as Strings) of the systems for which user mapping data has been found.

Throws:

UMException - If an unexpected problem occurs

checkCryptoConfiguration

public boolean checkCryptoConfiguration(String systemId)

Check whether the configuration of cryptography usage in user mapping is valid for the given system.

Background: The strongly encrypted storage method for user mapping data requires the availability of some extra software packages (SAP Java Crypto Toolkit and JDK specific JCE policy files for unlimited strength encryption). When user mapping is configured to use strong encryption, but at least one of these additional packages are missing, most user mapping operations will fail.

Please note that it's possible to configure user mapping in a way to store the special mapping data for the SAP reference system in an LDAP directory (i.e. without encryption, see IUserMappingData.USER_MAPPING_REFSYS_ATTRIBUTE). As encryption configuration is irrelevant for that kind of user mapping data, you need to provide the backend system as argument to allow distinction between systems which rely on correct encryption configuration and systems that don't.

Parameters:

systemId - The ID of the system for which you would like to read or write user mapping data.

Returns:

true if user mapping data for the passed system can be handled.
false if the user mapping configuration does not match the (non-)existence of the additional encryption software, but user mapping operations for the passed system would require them and fail.

getAvailableConverters

public com.sap.security.api.umap.IUserMappingConverter[] getAvailableConverters()

For internal use only.

Retrieve an array of all user mapping converters (no matter whether they could be applied or not, so check IUserMappingConverter#isConversionPossible before trying to start any conversion).

Returns:

Array of available user mapping converters.