com.sap.security.api.umap

Interface IUserMappingData

public interface IUserMappingData

Main interface for a user mapping entry (= a mapping from a specific local principal to a specific user in a specific backend system).

Using this interface, components can retrieve logon credentials for their backend connections in two ways:

• add logon credentials to a JCo properties object (enrich(Properties)), a SOAP message (enrich(SOAPMessage)) or an HTTP request (enrich(HttpURLConnection)). The actual type of credentials (e.g. user ID and password, SAP logon ticket, ...) depends on the logon method that is configured for the backend system.
• retrieve all logon data that has been saved for the selected principal and backend system (as cleartext, i.e. as it has been saved). This may be relevant if, for some reason, you don't want to retrieve logon method specific credentials. See enrich(Map).

If you're interested in the SAP logon ticket of a user and the backend system is either null, the SAP reference system or another system configured to use logon method "SAPLogonTicket", you can use the following code:

 IUserMappingData mappingData = ...;
 Properties jcoProperties = new Properties();
 mappingData.enrich(jcoProperties);
 String logonTicket = jcoProperties.getProperty(IUserMappingData.UMAP_JCO_PASSWORD);
 

Besides the different flavours of enrich(), this interface provides some additional methods for maintenance of user mapping data.

Field Summary

static String	UMAP_JCO_PASSWORD Key for the mapped backend password (or equivalent) in the Properties object enriched by enrich(Properties).
static String	UMAP_JCO_USER Key for the mapped backend user ID in the Properties object enriched by enrich(Properties).
static String	UMAP_PASSWORD Key for the mapped backend user password in the Map object enriched by enrich(Map).
static String	UMAP_USER Key for the mapped backend user ID in the Map object enriched by enrich(Map).
static String	USER_MAPPING_INVERSE_NAMESPACE Namespace used to store inverse user mapping data in UME tables.
static String	USER_MAPPING_NAMESPACE Namespace used to store user mapping data in UME tables.
static String	USER_MAPPING_REFSYS_ATTRIBUTE Logical attribute name used to store a user mapping for a SAP reference system for a user as plaintext.

Method Summary

void	enrich(HttpURLConnection conn) Enriches an HttpURLConnection with logon credentials.
void	enrich(Map logonData) Enrich a Map with logon credentials.
void	enrich(Properties jcoProps) Enriches a JCo Properties object (containing information used to open an RFC connection to an ABAP backend system) with logon credentials.
void	enrich(SOAPMessage message) Enriches a SOAP message with logon credentials.
IPrincipal	getPrincipal() Returns the principal (usually an IUser) this object was created for.
IPrincipal	getSourceOfIndirectMapping() In case of an indirect mapping (isMappingDirect() returns true): Determine the principal from which the mapping is "inherited".
String	getSystemId() Returns the system ID this object was created for (in an Enterprise Portal environment: the system alias).
boolean	isMappingDirect() Indicates whether the mapping found has been maintained for the principal itself or for one of its parent principals, e.g. groups or roles.
boolean	isReadOnly() Determines whether the user mapping data represented by this object can be altered (store new data, delete existing data).
void	saveLogonData(Map logonData) Store logon data for a specific user and backend system.
void	storeLogonData(Map logonData) Deprecated. Please use saveLogonData(Map) instead which supports more differentiated exception handling. Store logon data for a specific user and backend system. Please consider calling isReadOnly() before to make sure this user mapping entry can be (over)written.

Field Detail

USER_MAPPING_NAMESPACE

static final String USER_MAPPING_NAMESPACE

Namespace used to store user mapping data in UME tables.

See Also:

Constant Field Values

USER_MAPPING_INVERSE_NAMESPACE

static final String USER_MAPPING_INVERSE_NAMESPACE

Namespace used to store inverse user mapping data in UME tables.

See Also:

Constant Field Values

USER_MAPPING_REFSYS_ATTRIBUTE

static final String USER_MAPPING_REFSYS_ATTRIBUTE

Logical attribute name used to store a user mapping for a SAP reference system for a user as plaintext.

Use case: UME persistence and ABAP LDAP sync use the same LDAP server. One attribute contains the ABAP user ID which is different from the UME logon ID. By assigning the physical LDAP attribute to this logical attribute in UME datasource configuration, UME retrieves the mapped ABAP user ID for SAP logon tickets from this attribute. This way, there is no need to manually maintain user mapping data for all users that exist in both technology stacks.

See Also:

Constant Field Values

UMAP_JCO_USER

static final String UMAP_JCO_USER

Key for the mapped backend user ID in the Properties object enriched by enrich(Properties).

See Also:

Constant Field Values

UMAP_JCO_PASSWORD

static final String UMAP_JCO_PASSWORD

Key for the mapped backend password (or equivalent) in the Properties object enriched by enrich(Properties).

See Also:

Constant Field Values

UMAP_USER

static final String UMAP_USER

Key for the mapped backend user ID in the Map object enriched by enrich(Map).

See Also:

Constant Field Values

UMAP_PASSWORD

static final String UMAP_PASSWORD

Key for the mapped backend user password in the Map object enriched by enrich(Map).

See Also:

Constant Field Values

Method Detail

enrich

void enrich(Map logonData)
            throws NoLogonDataAvailableException

Enrich a Map with logon credentials.

Adds the following keys and the respective values (if available) to the Map: UMAP_USER and UMAP_PASSWORD. There may be additional key/value pairs in the Map, depending on the availability of additional user mapping data fields defined in the system definition (system attribute IUserMapping.UMAP_USERMAPPING_FIELDS) and the availability of respective values in the user mapping entry.

Parameters:

logonData - A Map that may already contain some logon data. enrich() will add the available user mapping data for the system.

Throws:

NoLogonDataAvailableException - If there is no logon data available that matches the system's logon method

enrich

void enrich(HttpURLConnection conn)
            throws NoLogonDataAvailableException

Enriches an HttpURLConnection with logon credentials.

Depending on the logon method this either adds the SAP logon ticket of the (authenticated!) user or basic authentication data based on the contents of this user mapping entry to the request.

Parameters:

conn - The connection object to be enriched.

Throws:

NoLogonDataAvailableException - If there is no logon data available that matches the system's logon method

enrich

void enrich(Properties jcoProps)
            throws NoLogonDataAvailableException

Enriches a JCo Properties object (containing information used to open an RFC connection to an ABAP backend system) with logon credentials.

Depending on the supported logon method of the backend system, this method adds authentication credentials of the required type to the Properties object. The object is meant to be passed to JCo without modification.

The Properties object may be enriched e.g. with user ID/password, SAP logon ticket or client certificate. Usual keys used in the Properties object are UMAP_JCO_USER and UMAP_JCO_PASSWORD. Please note that these are only potential keys: They don't necessarily exist after enrich(), and there may be other keys that can be interpreted by JCo/RFC resp. the backend system.

Parameters:

jcoProps - A JCo Properties object to be enriched with authentication credentials

Throws:

NoLogonDataAvailableException - If there is no logon data available that matches the system's logon method

enrich

void enrich(SOAPMessage message)
            throws NoLogonDataAvailableException

Enriches a SOAP message with logon credentials.

This is achieved by adding either a SAP logon ticket or a basic authentication header (for logon method UIDPW; only supported in conjunction with SAP Enterprise Portal) to the HTTP headers of the underlying HTTP connection assigned to the SOAP message.

Parameters:

message - The SOAP message object to be enriched

Throws:

NoLogonDataAvailableException - If there is no logon data available that matches the system's logon method

getPrincipal

IPrincipal getPrincipal()

Returns the principal (usually an IUser) this object was created for.

getSystemId

String getSystemId()

Returns the system ID this object was created for (in an Enterprise Portal environment: the system alias).

storeLogonData

@Deprecated
void storeLogonData(Map logonData)
                    throws IOException

Deprecated. Please use saveLogonData(Map) instead which supports more differentiated exception handling.

Store logon data for a specific user and backend system.

Please consider calling isReadOnly() before to make sure this user mapping entry can be (over)written.

Parameters:

logonData - The logon data to store. Should contain at least values for keys UMAP_USER and UMAP_PASSWORD.

Throws:

IOException - If an error occurs while storing the logon data.

saveLogonData

void saveLogonData(Map logonData)
                   throws UMException

Store logon data for a specific user and backend system.

Please consider calling isReadOnly() before to make sure this user mapping entry can be (over)written.

Parameters:

logonData - The logon data to store. Should contain at least values for keys UMAP_USER and UMAP_PASSWORD.

Throws:

UMException - If an error occurs while storing the logon data.
If the exception has the subtype AuthenticationFailedException, the error did not occur while actually saving, but when verifying the logon data against the backend system. Usually that is the result of incorrect logon data or errors in the system connection data which prevent opening a connection to the system.

isMappingDirect

boolean isMappingDirect()

Indicates whether the mapping found has been maintained for the principal itself or for one of its parent principals, e.g. groups or roles. To determine the principal from which the mapping is "inherited", you can use getSourceOfIndirectMapping().

Returns:

true if the mapping found has been maintained for the principal itself. false if the mapping has been "inherited" from a parent principal.

isReadOnly

boolean isReadOnly()

Determines whether the user mapping data represented by this object can be altered (store new data, delete existing data).

If you want to call saveLogonData(Map), you can call this method first to check whether storing will be able to succeed.

Background: Depending on the datasource where user mapping data is stored, changing mapping data will not be possible (read-only datasource).

Returns:

true if this user mapping data can only be read; false if it can be altered, too.

getSourceOfIndirectMapping

IPrincipal getSourceOfIndirectMapping()

In case of an indirect mapping (isMappingDirect() returns true): Determine the principal from which the mapping is "inherited".

Returns:

The principal from which the mapping is "inherited" or null if

1. this is a direct mapping
2. there is no mapping at all for this principal, neither a direct nor an indirect one

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