com.sap.security.api.umap

Interface IUserMapping

public interface IUserMapping

Provides an entry point to the user mapping functionality.

Main user mapping methods:

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, ISystemLandscapeObject).

Getting system objects for remote systems:

User mapping data is always associated with a remote system object of type ISystemLandscapeObject:
"These are my credentials for remote system ABC."
The central instance for getting (read) access to system objects is ISystemLandscapeFactory. See the corresponding Javadoc for more information, e.g. about how to retrieve an instance of that interface.

Example:

The following examples shows how to get JCO connection properties for a remote system which is defined in the Enterprise Portal system landscape and has the default alias "TestSAPBackend".

 import java.util.Properties;
 
 import com.sap.security.api.IUser;
 import com.sap.security.api.UMFactory;
 import com.sap.security.api.umap.system.ExceptionInImplementationException;
 import com.sap.security.api.umap.system.ISystemLandscape;
 import com.sap.security.api.umap.system.ISystemLandscapeObject;
 
 ...
 
 IUser user = UMFactory.getAuthenticator().getLoggedInUser();
 
 ISystemLandscape portalLandscape =
     UMFactory.getSystemLandscapeFactory().getLandscape(ISystemLandscape.TYPE_ENTERPRISE_PORTAL);
 if(portalLandscape == null) {
     throw new Exception("It seems like no Enterprise Portal is installed.");
 }
 ISystemLandscapeObject systemObject;
 try {
     systemObject = portalLandscape.getSystemByAlias("TestSAPBackend");
 }
 catch(ExceptionInImplementationException e) {
     throw new Exception("An error occurred while retrieving the test system object.", e);
 }
 if(systemObject == null) {
     throw new Exception("Test system does not exist in Enterprise Portal system landscape.");
 }
 
 IUserMapping userMapping = UMFactory.getUserMapping();
 IUserMappingData mappingData = userMapping.getUserMappingData(systemObject, user);
 Properties jcoProperties = new Properties();
 try {
     mappingData.enrich(jcoProperties);
 }
 catch(NoLogonDataAvailableException e) {
     throw new Exception("No logon data available for test system and the current user.", e);
 }
 

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.
static String	UMAP_USERMAPPING_TYPE_ADMIN
static String	UMAP_USERMAPPING_TYPE_ADMIN_USER
static String	UMAP_USERMAPPING_TYPE_USER

Method Summary

boolean	checkCryptoConfiguration(ISystemLandscapeObject systemObject) Check whether the configuration of cryptography usage in user mapping is valid for the given system.
boolean	checkCryptoConfiguration(String systemId) Deprecated. Use checkCryptoConfiguration(ISystemLandscapeObject) instead.
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. Use getInverseMappingData(String, ISystemLandscapeObject) instead.
Set	getMappedSystemsForPrincipal(IPrincipal principal) Deprecated. Call existsMappingData(ISystemLandscapeObject, IPrincipal) for every relevant system.
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. Use getR3UserName(IUser,ISystemLandscapeObject,boolean) instead.
String	getReferenceSystemID() Get the system ID for the currently configured ABAP reference system.
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. Use getUserMappingData(ISystemLandscapeObject,IPrincipal) instead.

Field Detail

UMAP_SYSTEMATTRS_LOGONMETHOD

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

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

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

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

@Deprecated
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

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

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_USERMAPPING_TYPE_ADMIN

static final String UMAP_USERMAPPING_TYPE_ADMIN

See Also:

Constant Field Values

UMAP_USERMAPPING_TYPE_USER

static final String UMAP_USERMAPPING_TYPE_USER

See Also:

Constant Field Values

UMAP_USERMAPPING_TYPE_ADMIN_USER

static final String UMAP_USERMAPPING_TYPE_ADMIN_USER

See Also:

Constant Field Values

UMAP_SYSTEM_TYPE

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

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

@Deprecated
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

@Deprecated
static final String[] UMAP_SYSTEM_FIELDS

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

UMAP_ENCRYPTION_KEYTYPE_ALIAS

static final String UMAP_ENCRYPTION_KEYTYPE_ALIAS

For internal use.

See Also:

Constant Field Values

UMAP_ENCRYPTION_ALGO_ALIAS

static final String UMAP_ENCRYPTION_ALGO_ALIAS

For internal use.

See Also:

Constant Field Values

UMAP_R3_MASTER

static final String UMAP_R3_MASTER

For internal use.

See Also:

Constant Field Values

UMAP_R3_MASTER_UID_MODE

static final String UMAP_R3_MASTER_UID_MODE

For internal use.

See Also:

Constant Field Values

Method Detail

getUserMappingData

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

@Deprecated
IUserMappingData getUserMappingData(String sysid,
                                               IPrincipal principal,
                                               Map sysAttrBag)

Deprecated. Use getUserMappingData(ISystemLandscapeObject,IPrincipal) instead.

Note: This method can only handle user mapping data for systems in the Enterprise Portal system landscape (Portal system) or the UME integrated dummy system landscape (Duet system).

Parameters:

sysid -

principal -

sysAttrBag -

Returns:

the user mapping data

getR3UserName

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

Deprecated. Use getR3UserName(IUser,ISystemLandscapeObject,boolean) instead.

Note: This method can only handle user mapping data for systems in the Enterprise Portal system landscape (Portal system) or the UME integrated dummy system landscape (Duet system).

Parameters:

principal -

sysid -

sysAttrBag -

bGenerateId -

Returns:

the user mapping data

Throws:

UMException

getInverseMappingData

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

Deprecated. Use getInverseMappingData(String, ISystemLandscapeObject) instead.

Note: This method can only handle user mapping data for systems in the Enterprise Portal system landscape (Portal system) or the UME integrated dummy system landscape (Duet system).

Parameters:

sysid -

userid -

system_type -

Returns:

the user mapping data

Throws:

NoLogonDataAvailableException

UMException

getR3UserName

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)

Note: The return value of this method is filtered against a black list of some values that could cause security issues. "SAP*" is not allowed and will result in null being returned. User IDs longer than 12 characters are not allowed on ABAP systems, that's why such mapped IDs will result in null, too.

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

See Also:

getInverseMappingData(String, ISystemLandscapeObject)

getInverseMappingData

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 as unique name 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 setting 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.

See Also:

getR3UserName(IUser, ISystemLandscapeObject, boolean)

getInverseMappingData

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

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

@Deprecated
Set getMappedSystemsForPrincipal(IPrincipal principal)
                                 throws UMException

Deprecated. Call existsMappingData(ISystemLandscapeObject, IPrincipal) for every relevant system.

Note: This method can only handle user mapping data for systems in the Enterprise Portal system landscape (Portal system) or the UME integrated dummy system landscape (Duet system).

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

boolean checkCryptoConfiguration(ISystemLandscapeObject systemObject)

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:

systemObject - 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.

checkCryptoConfiguration

@Deprecated
boolean checkCryptoConfiguration(String systemId)

Deprecated. Use checkCryptoConfiguration(ISystemLandscapeObject) instead.

Note: This method can only handle user mapping data for systems in the Enterprise Portal system landscape (Portal system) or the UME integrated dummy system landscape (Duet system).

Returns:

whether the configuration related to cryptography usage in user mapping functionality is OK

getAvailableConverters

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.

getReferenceSystemID

String getReferenceSystemID()

Get the system ID for the currently configured ABAP reference system.

The system ID consists of the system landscape type (see ISystemLandscape.getType()) followed by the separator character ':' followed by the system alias (see ISystemLandscapeObject.getAlias().

Returns:

The reference system ID or null if the reference system is not configured.

Access Rights

This class can be accessed from:

SC	DC
[sap.com] ENGINEAPI	[sap.com] com.sap.security.api.sda
[sap.com] ENGFACADE	[sap.com] tc/je/usermanagement/api
[sap.com] CORE-TOOLS	[sap.com] com.sap.engine.client.lib