Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD

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.List;
 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.ISystemLandscapeObject;
 import com.sap.security.api.umap.system.ISystemLandscapeWrapper;
 
 ...
 
 IUser user = UMFactory.getAuthenticator().getLoggedInUser();
 
 List landscapes = UMFactory.getSystemLandscapeWrappers();
 if(landscapes.size() < 1) {
     throw new Exception("There is no registered system landscape in the system.");
 }
 // SAP NetWeaver 2004s only supports *one* registered system landscape for user mapping.
 ISystemLandscapeWrapper landscape = (ISystemLandscapeWrapper) landscapes.get(0);
 ISystemLandscapeObject systemObject;
 try {
     systemObject = landscape.getSystemByAlias("TestSAPBackend");
 }
 catch(ExceptionInImplementationException e) {
     throw new Exception("An error occurred while retrieving the test system object." + e.getMessage());
 }
 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.getMessage());
 }

Field Summary
static java.lang.String UMAP_ENCRYPTION_ALGO_ALIAS
          For internal use.
static java.lang.String UMAP_ENCRYPTION_KEYTYPE_ALIAS
          For internal use.
static java.lang.String UMAP_EP6_ALIAS_PREFIX
          Internal prefix for Enterprise Portal system IDs in user mapping.
static java.lang.String UMAP_R3_MASTER
          For internal use.
static java.lang.String UMAP_R3_MASTER_UID_MODE
          For internal use.
static java.lang.String[] UMAP_SYSTEM_FIELDS
          Deprecated. This array of constants should not be used any more.
static java.lang.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 java.lang.String UMAP_SYSTEMATTRS_LOGONMETHOD
          System attribute name for logon method of a backend system.
static java.lang.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 java.lang.String UMAP_SYSTEMATTRS_TICKET_TYPE
          System attribute for the type of authentication ticket to be used for connections to a backend system.
static java.lang.String UMAP_TICKET_TYPE_ASSERTION
          Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: SAP Authentication Assertion Tickets.
static java.lang.String UMAP_TICKET_TYPE_LOGON
          Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: Use SAP Logon Tickets.
static java.lang.String UMAP_USERMAPPING_FIELDS
          System attribute name for additional user mapping fields that can be defined for a backend system.
static java.lang.String UMAP_USERMAPPING_TYPE
          System attribute name for "user mapping type" of a backend system.
static java.lang.String UMAP_USERMAPPING_TYPE_ADMIN
           
static java.lang.String UMAP_USERMAPPING_TYPE_ADMIN_USER
           
static java.lang.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(java.lang.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.
 java.util.Map getInverseMappingData(java.lang.String[] mappedUsers, ISystemLandscapeObject system)
          Optimized batch processing version of getInverseMappingData(String,ISystemLandscapeObject) for a whole set of backend user IDs.
 java.lang.String getInverseMappingData(java.lang.String mappedUser, ISystemLandscapeObject system)
          Search for users which are mapped to the given user ID in the specified backend system.
 java.lang.String getInverseMappingData(java.lang.String sysid, java.lang.String userid, byte system_type)
          Deprecated. Use getInverseMappingData(String, ISystemLandscapeObject) instead.
 java.util.Set getMappedSystemsForPrincipal(IPrincipal principal)
          Deprecated. Call existsMappingData(ISystemLandscapeObject, IPrincipal) for every relevant system.
 java.lang.String getR3UserName(IUser user, ISystemLandscapeObject system, boolean bGenerateId)
          Determine the ABAP user ID of the provided user in the specified backend system.
 java.lang.String getR3UserName(IUser principal, java.lang.String sysid, java.util.Map sysAttrBag, boolean bGenerateId)
          Deprecated. 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(java.lang.String sysid, IPrincipal principal, java.util.Map sysAttrBag)
          Deprecated. Use getUserMappingData(ISystemLandscapeObject,IPrincipal) instead.
 

Field Detail

UMAP_SYSTEMATTRS_LOGONMETHOD

public static final java.lang.String UMAP_SYSTEMATTRS_LOGONMETHOD

System attribute name for logon method of a backend system.

Potential values:

To be used with ISystemLandscapeObject.getAttribute(String).

UMAP_SYSTEMATTRS_TICKET_TYPE

public static final java.lang.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

public static final java.lang.String UMAP_TICKET_TYPE_LOGON
Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: Use SAP Logon Tickets.

UMAP_TICKET_TYPE_ASSERTION

public static final java.lang.String UMAP_TICKET_TYPE_ASSERTION
Potential value for system attribute UMAP_SYSTEMATTRS_TICKET_TYPE: SAP Authentication Assertion Tickets.

UMAP_SYSTEMATTRS_R3NAMEREF

public static final java.lang.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).

UMAP_USERMAPPING_FIELDS

public static final java.lang.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).

UMAP_USERMAPPING_TYPE

public static final java.lang.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).

UMAP_USERMAPPING_TYPE_ADMIN

public static final java.lang.String UMAP_USERMAPPING_TYPE_ADMIN

UMAP_USERMAPPING_TYPE_USER

public static final java.lang.String UMAP_USERMAPPING_TYPE_USER

UMAP_USERMAPPING_TYPE_ADMIN_USER

public static final java.lang.String UMAP_USERMAPPING_TYPE_ADMIN_USER

UMAP_SYSTEM_TYPE

public static final java.lang.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).

UMAP_EP6_ALIAS_PREFIX

public static final java.lang.String UMAP_EP6_ALIAS_PREFIX
Internal prefix for Enterprise Portal system IDs in user mapping.

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.

UMAP_SYSTEM_FIELDS

public static final java.lang.String[] UMAP_SYSTEM_FIELDS
Deprecated. This array of constants should not be used any more.

UMAP_ENCRYPTION_KEYTYPE_ALIAS

public static final java.lang.String UMAP_ENCRYPTION_KEYTYPE_ALIAS
For internal use.

UMAP_ENCRYPTION_ALGO_ALIAS

public static final java.lang.String UMAP_ENCRYPTION_ALGO_ALIAS
For internal use.

UMAP_R3_MASTER

public static final java.lang.String UMAP_R3_MASTER
For internal use.

UMAP_R3_MASTER_UID_MODE

public static final java.lang.String UMAP_R3_MASTER_UID_MODE
For internal use.
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(java.lang.String sysid,
                                           IPrincipal principal,
                                           java.util.Map sysAttrBag)
Deprecated. Use getUserMappingData(ISystemLandscapeObject,IPrincipal) instead.

getR3UserName

public java.lang.String getR3UserName(IUser principal,
                                      java.lang.String sysid,
                                      java.util.Map sysAttrBag,
                                      boolean bGenerateId)
                               throws UMException
Deprecated. Use getR3UserName(IUser,ISystemLandscapeObject,boolean) instead.

getInverseMappingData

public java.lang.String getInverseMappingData(java.lang.String sysid,
                                              java.lang.String userid,
                                              byte system_type)
                                       throws NoLogonDataAvailableException,
                                              UMException
Deprecated. Use getInverseMappingData(String, ISystemLandscapeObject) instead.

getR3UserName

public java.lang.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
See Also:
getInverseMappingData(String, ISystemLandscapeObject)

getInverseMappingData

public java.lang.String getInverseMappingData(java.lang.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:

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

public java.util.Map getInverseMappingData(java.lang.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 java.util.Set getMappedSystemsForPrincipal(IPrincipal principal)
                                           throws UMException
Deprecated. Call existsMappingData(ISystemLandscapeObject, IPrincipal) for every relevant system.

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(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

public boolean checkCryptoConfiguration(java.lang.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).

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.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES
SUMMARY:  INNER | FIELD | CONSTR | METHOD DETAIL:  FIELD | CONSTR | METHOD