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, ISystemLandscapeObject)
.
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.
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); }
Modifier and Type | Field and Description |
---|---|
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
|
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 |
static String |
UMAP_X509_MAPPING_ATTRIBUTE
System attribute name for the user attribute which contains the user attribute name.
|
Modifier and Type | Method and Description |
---|---|
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.
|
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.
|
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)
.
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:
static final String UMAP_TICKET_TYPE_LOGON
UMAP_SYSTEMATTRS_TICKET_TYPE
: Use SAP Logon
Tickets.static final String UMAP_TICKET_TYPE_ASSERTION
UMAP_SYSTEMATTRS_TICKET_TYPE
: SAP
Authentication Assertion Tickets.@Deprecated static final String UMAP_SYSTEMATTRS_R3NAMEREF
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 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)
.
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)
.
static final String UMAP_USERMAPPING_TYPE_ADMIN
static final String UMAP_USERMAPPING_TYPE_USER
static final String UMAP_USERMAPPING_TYPE_ADMIN_USER
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)
.
static final String UMAP_X509_MAPPING_ATTRIBUTE
System attribute name for the user attribute which contains the user attribute name.
This attribute may be filled for systems which use X.509 authentication and may have values
like "uniquename"
, "r3name"
.
To be used with
ISystemLandscapeObject.getAttribute(String)
.
static final String UMAP_EP6_ALIAS_PREFIX
@Deprecated static final byte UMAP_SYSTEM_TYPE_EP6_ALIAS
@Deprecated static final String[] UMAP_SYSTEM_FIELDS
static final String UMAP_ENCRYPTION_KEYTYPE_ALIAS
static final String UMAP_ENCRYPTION_ALGO_ALIAS
static final String UMAP_R3_MASTER
static final String UMAP_R3_MASTER_UID_MODE
IUserMappingData getUserMappingData(ISystemLandscapeObject system, IPrincipal principal)
IUserMappingData
object to perform user mapping activities for the
specified principal and backend system.system
- The system object for the backend system. 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.@Deprecated IUserMappingData getUserMappingData(String sysid, IPrincipal principal, Map sysAttrBag)
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).
sysid
- the system ID.principal
- The principal for which user mapping data is requested. In most cases, this will be an IUser
object.sysAttrBag
- a Map with system attributes.@Deprecated String getR3UserName(IUser principal, String sysid, Map sysAttrBag, boolean bGenerateId) throws UMException
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).
principal
- The principal for which user mapping data is requested.sysid
- The backend system ID.sysAttrBag
- a Map with system attributes.bGenerateId
- Flag that controls the generation of ABAP user IDs (currently not implemented,
please always set to false
).UMException
- If some internal operation fails unexpectedly.@Deprecated String getInverseMappingData(String sysid, String userid, byte system_type) throws NoLogonDataAvailableException, UMException
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).
sysid
- The backend system ID.userid
- The mapped backend user ID the user searched for has maintained.system_type
- system typeNoLogonDataAvailableException
- If no user with the provided backend user ID could be found.UMException
- If some internal operation fails unexpectedly.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 |
|
||||||||
UIDPW |
the backend user ID if one is maintained, otherwise null |
||||||||
X509CERT |
|
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.user
- The local user for which the mapped user ID is requestedsystem
- 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
.).UMException
- If some internal operation fails unexpectedly.getInverseMappingData(String, ISystemLandscapeObject)
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:
SAPLogonTicket
ume.r3.mastersystem.uid.mode
is 1ume.usermapping.x509_mapping.attribute
is
maintained to a valid user attribute and the logon method of the system is X509CERT.
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
.
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
.IUserFactory.getUser(String)
NoLogonDataAvailableException
- If no user with the provided backend user ID could be foundMultipleHitException
- 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.getR3UserName(IUser, ISystemLandscapeObject, boolean)
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.
mappedUsers
- Array of the mapped backend user IDssystem
- The backend system for which to search for matching users. May be
null
, see
getInverseMappingData(String,ISystemLandscapeObject)
.IUser
object
(or null
if no such mapping exists) as value.UMException
- If an unexpected problem occursboolean existsMappingData(ISystemLandscapeObject system, IPrincipal principal) throws UMException
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.true
if a mapping for the specified system and principal was found,
false
if no mapping was found.UMException
- If some unexpected problem occurs@Deprecated Set getMappedSystemsForPrincipal(IPrincipal principal) throws UMException
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).
principal
- The principal for which to check for user mapping dataString
s) of the systems for which user mapping
data has been found.UMException
- If an unexpected problem occursboolean 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.
systemObject
- The system for which you would like to read or write user mapping data.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.@Deprecated boolean checkCryptoConfiguration(String systemId)
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).
systemId
- The system ID for which you would like to read or write user mapping data.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).
String getReferenceSystemID()
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()
.
null
if the reference system is not
configured.Access Rights |
---|
SC | DC | Public Part | ACH |
---|---|---|---|
[sap.com] CORE-TOOLS
|
[sap.com]
|
default
|
BC-JAS
|
[sap.com] ENGFACADE
|
[sap.com] tc/je/usermanagement/api
|
api
|
BC-JAS-SEC
|
[sap.com] ENGINEAPI
|
[sap.com]
|
-
|
BC-JAS-SEC-UME
|
[sap.com] ENGINEAPI
|
[sap.com]
|
default
|
BC-JAS-SEC-UME
|
Copyright 2018 SAP AG Complete Copyright Notice