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 J2EE Engine).

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 J2EE Engine, 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.util.IUMParameters
        UME/unsharable/com.sap.security.api.ticket.TicketVerifier
        

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 J2EE Engine 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) NOTE: Released for internal use only.
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() NOTE: 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 com.sap.security.api.srvUser.IServiceUserFactory	getServiceUserFactory() NOTE: Released for internal use only.
static ArrayList	getSystemLandscapeWrappers() Retrieve the list of all ISystemLandscapeWrapper implementations that are currently registered.
TicketVerifier	getTicketVerifier() getTicketVerifier provides access to an object which can be used for verifing Tickets
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(Properties prop, HashMap files, com.sap.security.api.util.IUMFileIO fileio) Deprecated. Use InternalUMFactory.initializeUME(IUMFileIO, IPlatformTools) instead! NOTE: Released for internal use only. Initialize the UMFactory manually for scenarios which don't support multiple clients ("Mandanten"). Called from Portal UserMangementService or WebAS 6.30 (or any other application that does all the initialization by itself (e.g. read properties and configuration files)
static void	initialize(String umeCfgPath) FOR INTERNAL USE ONLY: Initialize UME For standalone issues.
static void	initialize(String[] clients, Properties[] props, HashMap[] files, com.sap.security.api.util.IUMFileIO[] fileio) Deprecated. Use InternalUMFactory.initializeUME(IUMFileIO, IPlatformTools) instead! NOTE: Released for internal use only. Initialize the UMFactory manually for a specific client ("Mandant"). Called from JTS UME service (or any other application that supports multiple clients ("Mandanten") and does all the initialization by itself (e.g. read properties and configuration files)
static boolean	isInitialized() isInitialized provides information about the state of UMFactory.
static void	removeSystemLandscapeWrapper(ISystemLandscapeWrapper slw) NOTE: Released for internal use only.
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
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

initialize

public static void initialize(Properties prop,
                              HashMap files,
                              com.sap.security.api.util.IUMFileIO fileio)

Deprecated. Use InternalUMFactory.initializeUME(IUMFileIO, IPlatformTools) instead! NOTE: Released for internal use only.

Initialize the UMFactory manually for scenarios which don't support multiple clients ("Mandanten"). Called from Portal UserMangementService or WebAS 6.30 (or any other application that does all the initialization by itself (e.g. read properties and configuration files)

Parameters:

prop - Property object that contains all sapum.properties (it should consider the search path that is defined). Must not be null.

files - This is a HashMap containing name/byte[] pairs of files which can be read with IUMParameters.getInputStream(String). name should be plain names without path. Can be empty, should not be null.

fileio - Implements IUMFileIO for reading/writing files

initialize

public static void initialize(String[] clients,
                              Properties[] props,
                              HashMap[] files,
                              com.sap.security.api.util.IUMFileIO[] fileio)

Deprecated. Use InternalUMFactory.initializeUME(IUMFileIO, IPlatformTools) instead! NOTE: Released for internal use only.

Initialize the UMFactory manually for a specific client ("Mandant"). Called from JTS UME service (or any other application that supports multiple clients ("Mandanten") and does all the initialization by itself (e.g. read properties and configuration files)

Parameters:

clients - Array of identifiers for all clients ("Mandanten")

props - Array of Properties objects for all clients. Each Properties object contains all sapum.properties for the respective client (it should consider the search path that is defined). Must not be null.

files - Array of HashMap objects for all clients. Each contains name/byte[] pairs of UME configuration files which can be read via IUMParameters.getInputStream(String). name should be plain names without path. An array element can be empty, should not be null.

fileio - Array of implementations of IUMFileIO for reading/writing configuration files for each client

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 J2EE Engine 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

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.

Throws:

NoLogonDataAvailableException - if user mapping has not been initialized yet

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

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 com.sap.security.api.srvUser.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

public static void addSystemLandscapeWrapper(ISystemLandscapeWrapper slw)

NOTE: Released for internal use only.

getSystemLandscapeWrappers

public static ArrayList getSystemLandscapeWrappers()

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

removeSystemLandscapeWrapper

public static void removeSystemLandscapeWrapper(ISystemLandscapeWrapper slw)

NOTE: Released for internal use only.

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

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

public TicketVerifier getTicketVerifier()

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