com.sap.security.api

Class UMFactory

java.lang.Object
  com.sap.security.api.UMFactory

public class UMFactory
extends Object

Main factory providing access to all UME functionality.

How to access UME functionality

Applications can access UME functionality via a set of public UME factories like IUserFactory, IAuthentication and IUserMapping.

UME factories can be distinguished by their behaviour regarding database transactions. There are factories that simply account for UME internal transactions, which is the default behaviour. And there may also be factories that participate in container wide shared transactions (if supported by the current runtime environment, e.g. SAP Application Server Java).

There are two ways to get access to UME factories:

1. The UMFactory class provides functionality to get access to UME factory objects. Applications access all the functionality through this class and its (mostly static) factory getter methods like getUserFactory(), getAuthenticator() and getUserMapping().
   Note: UMFactory's getter methods always return UME factories that don't participate in shared transactions.

2. In scenarios where a JNDI naming system exists inside of the server, UME factories can also be retrieved by a JNDI lookup. This is the only way to get access to UME factories that participate in shared transactions.

   Looking up UME factories from JNDI requires declaration of all necessary factories in the application's deployment descriptor. In SAP Application Server Java, this requires adding a server-component-ref node to the web-j2ee-engine.xml / ejb-j2ee-engine.xml / appclient-j2ee-engine.xml like this (see Documentation of web-j2ee-engine.dtd):

        <server-component-ref>
          <name>
            ume/userfactory
          </name>
          <type>
            interface
          </type>
          <jndi-name>
            UME/unsharable/com.sap.security.api.IUserFactory
          </jndi-name>
        </server-component-ref>
        

   In this example, the application would call lookup("java:comp/env/ume/userfactory") to retrieve an instance of IUserFactory (which does not participate in shared transactions, see below).

   Some UME factories are available in two different subcontexts of the main UME context "UME":

   • Factories in context "sharable" participate in shared database transactions (if the container supports shared transactions and the actual factory is subject to transactions at all).
   • Factories in context "unsharable" ignore shared transactions or are not subject to transactions at all.

   Each factory object is bound into the UME subcontexts by the fully qualified name of the corresponding UME interface:

        UME/sharable/com.sap.security.api.IGroupFactory
        UME/sharable/com.sap.security.api.IPrincipalFactory
        UME/sharable/com.sap.security.api.IRoleFactory
        UME/sharable/com.sap.security.api.IUserAccountFactory
        UME/sharable/com.sap.security.api.IUserFactory
        UME/sharable/com.sap.security.api.acl.IAclManagerFactory
        UME/sharable/com.sap.security.api.srvUser.IServiceUserFactory
        
        UME/unsharable/com.sap.security.api.IGroupFactory
        UME/unsharable/com.sap.security.api.IPrincipalFactory
        UME/unsharable/com.sap.security.api.IRoleFactory
        UME/unsharable/com.sap.security.api.IUserAccountFactory
        UME/unsharable/com.sap.security.api.IUserFactory
        UME/unsharable/com.sap.security.api.acl.IAclManagerFactory
        UME/unsharable/com.sap.security.api.logon.IAnonymousUserFactory
        UME/unsharable/com.sap.security.api.logon.IAuthentication
        UME/unsharable/com.sap.security.api.logon.ILogonAuthentication
        UME/unsharable/com.sap.security.api.logon.ISecurityPolicyFactory
        UME/unsharable/com.sap.security.api.srvUser.IServiceUserFactory
        UME/unsharable/com.sap.security.api.umap.IUserMapping
        UME/unsharable/com.sap.security.api.umap.system.ISystemLandscapeFactory
        

Internal: How to initialize UME functionality

There are several ways to initialize UME UMFactory

• A platform specific service calls com.sap.security.core.InternalUMFactory.initializeUME(IUMFileIO, IPlatformTools) which in turn calls initialize(Map) to initialize UMFactory. This is the standard way which is already used in SAP Application Server Java and SAP JTS.
• If UME runs standalone (i.e. not as part of an SAP server system, but in a custom Java application, the application may either call initialize(String) with a directory in the file system which contains all required UME configuration data.
• If only UME functionality for verifying SAP logon tickets (but no other UME functionality) is required in a standalone scenario, see the documentation of class TicketVerifier.

Field Summary

static String

VERSIONSTRING

Method Summary

static void	addSystemLandscapeWrapper(ISystemLandscapeWrapper slw) Deprecated. Use getSystemLandscapeFactory() and ISystemLandscapeFactory.registerLandscape(ISystemLandscape) instead.
static IAclManager	getAclManager() Gets the default Access Control List (ACL) Manager.
static IAclManager	getAclManager(String applicationId) Gets an application specific Access Control List (ACL) Manager.
static String[]	getAllAclManagers() Returns an array of all used Access Control List (ACL) Managers.
static IAnonymousUserFactory	getAnonymousUserFactory() Gets the anonymous user factory for retrieving anonymous user.
static IAuthentication	getAuthenticator() Provide access to an implementation of IAuthentication
static IUserFactory	getDefaultFactory() Deprecated. : use getUserFactory() instead
static IGroupFactory	getGroupFactory() Returns an implementation of IGroupFactory.
static UMFactory	getInstance() Returns the instance of UMFactory.
static ILogonAuthentication	getLogonAuthenticator() Provide access to an implementation of ILogonAuthentication
static IPrincipalFactory	getPrincipalFactory() Returns an implementation of IPrincipalFactory.
static com.sap.security.api.util.IUMParameters	getProperties() Deprecated. Released for internal use only
static IRoleFactory	getRoleFactory() Returns an implementation of IRoleFactory.
static SecurityManager	getSecurityManager() A method in the usermanagement that wants to check whether the caller is allowed to call it should call this method instead of System.getSecurityManager() to get a security manager to perfom the checkPermission call.
static ISecurityPolicy	getSecurityPolicy() getSecurityPolicy provides access to the security policy object
static ISecurityPolicy	getSecurityPolicyByLogonID(String logonID) getSecurityPolicyByLogon provides retrieving security policy object from the associated user account
static IServiceUserFactory	getServiceUserFactory() NOTE: Released for internal use only.
static ISystemLandscapeFactory	getSystemLandscapeFactory()
static ArrayList	getSystemLandscapeWrappers() Deprecated. Use getSystemLandscapeFactory() and ISystemLandscapeFactory.getAllLandscapes() resp. ISystemLandscapeFactory.getLandscape(String) instead.
TicketVerifier	getTicketVerifier() Deprecated. Please use the native library "SAPSSOEXT" and the corresponding Java wrapper. For further information, including where to download the "SAPSSOEXT" package, please refer to the online documentation.
static com.sap.security.api.util.IUMFileIO	getUMFileIO() NOTE: Released for internal use only.
static IUserAccountFactory	getUserAccountFactory() Returns an implementation of IUserAccountFactory.
static IUserFactory	getUserFactory() Returns an implementation of IUserFactory.
static IUserMapping	getUserMapping() Gets the global user mapping object which provides access to all user mapping data.
static void	initialize(Map factories) FOR INTERNAL USE ONLY: Initialize UME.
static void	initialize(String umeCfgPath) FOR INTERNAL USE ONLY: Initialize UME For standalone issues.
static boolean	isInitialized() isInitialized provides information about the state of UMFactory.
static void	removeSystemLandscapeWrapper(ISystemLandscapeWrapper slw) Deprecated. Use getSystemLandscapeFactory() and ISystemLandscapeFactory.unregisterLandscape(ISystemLandscape) instead.
static void	setSecurityManager(SecurityManager securitymanager) Set the security manager that is used to protect the API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VERSIONSTRING

public static final String VERSIONSTRING

See Also:

Constant Field Values

Method Detail

initialize

public static void initialize(Map factories)

FOR INTERNAL USE ONLY: Initialize UME. This method may be called once with all required factories or several times with one or more factories (if initialization can't be performed in one single step). isInitialized() will not return true until the key "InitializationComplete" is contained in the argument Map (see the table of keys and values below).

Parameters:

factories - Map of UME factory objects. The following key / value pairs are currently required:

Key	Value
IAclManager.class	Class object of the IAclManager implementation class
IAnonymousUserFactory.class	Instance of IAnonymousUserFactory
IAuthentication.class	Instance of IAuthentication
IGroupFactory.class	Instance of IGroupFactory
ILogonAuthentication.class	Instance of ILogonAuthentication
IPrincipalFactory.class	Instance of IPrincipalFactory
IRoleFactory.class	Instance of IRoleFactory
ISecurityPolicyFactory.class	Instance of ISecurityPolicyFactory
IServiceUserFactory.class	Instance of IServiceUserFactory
ISystemLandscapeFactory.class	Instance of ISystemLandscapeFactory
IUMFileIO.class	Instance of IUMFileIO
IUMParameters.class	Instance of IUMParameters
IUserAccountFactory.class	Instance of IUserAccountFactory
IUserFactory.class	Instance of IUserFactory
IUserMapping.class	Instance of IUserMapping
TicketVerifier.class	Class object of the TicketVerifier implementation class
"InitializationComplete" (String)	Boolean with value true.

initialize

public static void initialize(String umeCfgPath)

FOR INTERNAL USE ONLY: Initialize UME For standalone issues. The current classloader MUST be able to load classes that are part of UME Core, especially com.sap.security.core.InternalUMFactory!

Parameters:

umeCfgPath - String object that contains the path to the sapum.properties file and the additional xml files

getInstance

public static UMFactory getInstance()
                             throws UMRuntimeException

Returns the instance of UMFactory. If the UMFactory is not already initialized this function throws an IllegalStateException. Note: UMFactory will be initialized by EP6 Portal or SAP Application Server Java 630. If UMFactory should be used standalone, it has to be initialized explicitly with the method initialize(String umeCfgPath)

Returns:

Instance of UMFactory

Throws:

IllegalStateException - If the UMFactory is not already initialized.

UMRuntimeException - If UME is running with client ("Mandant") concept enabled and the current client can not be determined.

getAuthenticator

public static IAuthentication getAuthenticator()

Provide access to an implementation of IAuthentication

Returns:

IAuthentication object used for authentication handling. For more details see IAuthentication

getDefaultFactory

@Deprecated
public static IUserFactory getDefaultFactory()

Deprecated. : use getUserFactory() instead

Returns an implementation of IUserFactory. This method should be called to get the user factory for all user related operations.

Returns:

UserFactory object

getGroupFactory

public static IGroupFactory getGroupFactory()

Returns an implementation of IGroupFactory. This method should be called to get the group factory for all group related operations.

Returns:

IGroupFactory object used for handling group operations

getLogonAuthenticator

public static ILogonAuthentication getLogonAuthenticator()

Provide access to an implementation of ILogonAuthentication

Returns:

ILogonAuthentication object used for extended authentication handling. For more details see ILogonAuthentication

getSecurityManager

public static SecurityManager getSecurityManager()

A method in the usermanagement that wants to check whether the caller is allowed to call it should call this method instead of System.getSecurityManager() to get a security manager to perfom the checkPermission call.

Returns:

SecurityManager object, if a security manager was set using method setSecurityManager or if s system security manager exists.
null otherwise.

getUserMapping

public static IUserMapping getUserMapping()

Gets the global user mapping object which provides access to all user mapping data.

Returns:

IUserMapping object used for handling user mapping operations.

getUMFileIO

public static com.sap.security.api.util.IUMFileIO getUMFileIO()

NOTE: Released for internal use only.

getProperties

public static com.sap.security.api.util.IUMParameters getProperties()

Deprecated. Released for internal use only

NOTE: Released for internal use only.

Get access to IUMParameters interface

Returns:

API for accessing IUMParameters

getRoleFactory

public static IRoleFactory getRoleFactory()

Returns an implementation of IRoleFactory. This method should be called to get the role factory for all role related operations.

Returns:

IRoleFactory object used for handling role operations

getUserAccountFactory

public static IUserAccountFactory getUserAccountFactory()

Returns an implementation of IUserAccountFactory. This method should be called to get the user account factory for all user account related operations.

Returns:

IUserAccountFactory object used for handling user account operations

getPrincipalFactory

public static IPrincipalFactory getPrincipalFactory()

Returns an implementation of IPrincipalFactory. This method should be called to get the principal factory for all principal related operations.

Returns:

IPrincipalFactory object used for handling principal operations

getUserFactory

public static IUserFactory getUserFactory()

Returns an implementation of IUserFactory. This method should be called to get the user factory for all user related operations.

Returns:

IUserFactory object used for handling user operations

getServiceUserFactory

public static IServiceUserFactory getServiceUserFactory()

NOTE: Released for internal use only.

Returns an implementation of IServiceUserFactory. This method should be called to get the service user factory for all service user related operations.

Returns:

IServiceUserFactory object used for handling user operations

getAclManager

public static IAclManager getAclManager()

Gets the default Access Control List (ACL) Manager.

Returns:

IAclManager object used for handling Access Control Lists For further details check com.sap.security.api.acl.IAclManager

getAclManager

public static IAclManager getAclManager(String applicationId)

Gets an application specific Access Control List (ACL) Manager.

Returns:

IAclManager object used for handling Access Control Lists For further details check com.sap.security.api.acl.IAclManager

getAllAclManagers

public static String[] getAllAclManagers()

Returns an array of all used Access Control List (ACL) Managers.

Returns:

String[] applicationIDs of used ACL managers

setSecurityManager

public static void setSecurityManager(SecurityManager securitymanager)

Set the security manager that is used to protect the API. The security manager can only be set once. More attempts to set a security manager result in an IllegalStateException. An IllegalStateException is also thrown if there is a system security manager and this method is called. If the SecurityManagerFactory is visible for the UMFactory, this this method must be called before the UMFactory is initialized, because in this case during intialization a security manager is set if there is neither a system security manager nor this method was called.

Parameters:

securitymanager - security manager to be used

Throws:

IllegalStateException - in case this method has already been called before or there is a system security manager

addSystemLandscapeWrapper

@Deprecated
public static void addSystemLandscapeWrapper(ISystemLandscapeWrapper slw)

Deprecated. Use getSystemLandscapeFactory() and ISystemLandscapeFactory.registerLandscape(ISystemLandscape) instead.

NOTE: Released for internal use only.

getSystemLandscapeWrappers

@Deprecated
public static ArrayList getSystemLandscapeWrappers()

Deprecated. Use getSystemLandscapeFactory() and ISystemLandscapeFactory.getAllLandscapes() resp. ISystemLandscapeFactory.getLandscape(String) instead.

Retrieve the list of all ISystemLandscapeWrapper implementations that are currently registered.

removeSystemLandscapeWrapper

@Deprecated
public static void removeSystemLandscapeWrapper(ISystemLandscapeWrapper slw)

Deprecated. Use getSystemLandscapeFactory() and ISystemLandscapeFactory.unregisterLandscape(ISystemLandscape) instead.

NOTE: Released for internal use only.

getSystemLandscapeFactory

public static ISystemLandscapeFactory getSystemLandscapeFactory()

getAnonymousUserFactory

public static IAnonymousUserFactory getAnonymousUserFactory()

Gets the anonymous user factory for retrieving anonymous user.

Returns:

IAnonymousUserFactory factory handling anonymous user objects. For further details refer to {com.sap.security.api.logon.IAnonymousUserFactory}

getSecurityPolicy

public static ISecurityPolicy getSecurityPolicy()

getSecurityPolicy provides access to the security policy object

Returns:

ISecurityPolicy object used for security policy handling. For more details see ISecurityPolicy

getSecurityPolicyByLogonID

public static ISecurityPolicy getSecurityPolicyByLogonID(String logonID)
                                                  throws UMException

getSecurityPolicyByLogon provides retrieving security policy object from the associated user account

Parameters:

logonID - the logon ID of the associated account's For more details see ISecurityPolicy

Returns:

ISecurityPolicy object used for security policy handling.

Throws:

UMException

isInitialized

public static boolean isInitialized()

isInitialized provides information about the state of UMFactory.

Returns:

true if UMFactory is already initialized and configured, false otherwise

getTicketVerifier

@Deprecated
public TicketVerifier getTicketVerifier()

Deprecated. Please use the native library "SAPSSOEXT" and the corresponding Java wrapper. For further information, including where to download the "SAPSSOEXT" package, please refer to the online documentation.

getTicketVerifier provides access to an object which can be used for verifing Tickets

Returns:

TicketVerifier object used for ticket handling. For more details see TicketVerifier

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