com.webmethods.sc.directory

Interface IDirectorySession

All Superinterfaces:

AutoCloseable

public interface IDirectorySession
extends AutoCloseable

Main interface to interact with shared directory management component

Field Summary

Fields

Modifier and Type	Field and Description
static String	CURRENT_USER Identifies currently logged in user to be used in the lookupPrincipalByID(String) method.
static String	ROLE_COOKIE_ID

Method Summary

Modifier and Type	Method and Description
void	addPrincipalToGroup(String principalID, String groupID) Adds a principal to a group.
void	addPrincipalToRole(String principalID, String roleID) Adds a principal to a role.
IDirectoryUser	authenticateUser(String username, String password) Attempts to authenticate the user based on the credentials with any registered directory service in their configured search order.
default IDirectoryUser	authenticateUser(String username, String password, String oneTimePassword) Attempts to authenticate the user based on the credentials with any registered directory service in their configured search order.
default void	beginConversation() Mark the current transient conversation long-running.
void	close() Release any resources
IDirectoryService	createDirectoryService(String name, IDirectoryService.DIRECTORY_XTYPES type, Map<String,Object> properties) Creates an instance of IDirectoryService from the supplied parameters.
IDirectoryPagingCookie	createPagingCookie(String directoryServiceID) Creates instance of directory paging cookie to be used for searchDirectory(String, int, DirectorySearchQuery, IDirectoryPagingCookie) method.
IDirectoryPrincipal	createPrincipal(String directoryServiceID, int principalType, String name, Map<String,? extends Object> properties) Creates a new principal group or user associated with this specified directory service.
IDirectoryRole	createRole(int roleType, String name, Map<String,?> properties) Deprecated. Use createRole(String, String, Map) instead
IDirectoryRole	createRole(String roleType, String name, Map<String,?> properties) Creates new role of the specified type
void	deleteDirectoryService(String directoryServiceID) Deletes a IDirectoryService by its ID.
void	deletePrincipal(String principalID) Deletes a principal by its unique ID
void	destroyPagingCookie(IDirectoryPagingCookie directoryPagingCookie) Destroys directory paging cookie and frees up any associated resources
default void	endConversation() Mark the current long-running conversation transient.
default Object	getAttribute(String principalID, String papID, String attrName)
Map<String,Object>	getAttributeExtendedInfo(String principalID, String principalAttributeProviderID, String attributeName) Returns extended information about attributes of the given provider (only if provider supports this
List<String>	getAttributeNames(String principalID, String principalAttributeProviderID) List defined attribute names for the specified attribute provider
IDirectoryPrincipalAttributeProvider	getAttributeProvider(String attributeProviderID) Gets IDirectoryPrincipalAttributeProvider by its ID
List<String>	getAttributeTitles(String principalID, String principalAttributeProviderID, Locale locale) List defined user friendly attribute titles for the specified attribute provider
ICertificateManager	getCertificateManager() Returns instance of certificate manager
IDirectoryService	getDirectoryService(String directoryServiceID) Returns instance of IDirectoryService by its ID.
IDirectoryService	getDirectoryServiceByName(String directoryServiceID) Returns instance of IDirectoryService by its ID.
Map<String,Object>	getDirectoryServiceDefaultValues(IDirectoryService.DIRECTORY_XTYPES type, String dirSubType) Retruns a Map with the initial directory parameters.
IGdprConfig	getGdprConfig()
List<IDirectoryGroup>	getGroupMembership(String principalID) Retrieve the group membership for this principal
List<IDirectoryPrincipal>	getMembers(String principalID) Returns members of the group or role.
List<IDirectoryRole>	getRoleMembership(String principalID) Retrieve the role membership for this principal
default ITOTPConfiguration	getTotpConfig()
default Map<String,TypedAttribute>	getTypedAttributes(String papID, String principalURI)
int	getUsersCount(IDirectoryService dirSvc) Lists all existing users for a particular dir service, or for all dir services if null provided
default boolean	isConversation() Returns if the conversation is marked transient or long-running
List<IDirectoryService>	listAllDirectoryServices() Retrieves the list of all registeredIDirectoryServices ( regardless of state ) in the search order as defined in MWS directory services administration
List<IDirectoryPrincipalAttributeProvider>	listAttributeProviders(int principalType) Gets all registered principal attribute providers IDirectoryPrincipalAttributeProvider
List<IDirectoryService>	listDirectoryServices() Retrieves the list of all 'enabled and running' registeredIDirectoryServices in the search order as defined in MWS directory services administration
List<IDirectoryRole>	listRoles() Lists all roles defined in the system
IDirectoryPrincipal	lookupPrincipalByAlias(String principalAlias) Attempts to lookup a principal by well known alias
IDirectoryPrincipal	lookupPrincipalByDN(String principalDN, int type) Attempts to lookup a principal by their dn.
IDirectoryPrincipal	lookupPrincipalByDN(String principalDN, int type, String dirServiceName) Attempts to lookup a principal by their dn.
IDirectoryPrincipal	lookupPrincipalByID(String principalID) Attempts to lookup a principal by their unique ID.
IDirectoryPrincipal	lookupPrincipalByName(String principalName, int type) Attempts to lookup a principal by their name.
IDirectoryPrincipal	lookupUserByUUID(String principalUUID, String dirServiceName) Attempts to lookup a user by their unique ID.
void	modifyPrincipal(String principalID, Map<String,? extends Object> attributes) Sets attribute values for the principal.
void	removePrincipalFromGroup(String principalID, String groupID) Removes a principal from a group.
void	removePrincipalFromRole(String principalID, String roleID) Removes a principal from a role.
List<IDirectoryPrincipal>	searchDirectory(String directoryServiceID, int principalType, DirectorySearchQuery query, IDirectoryPagingCookie directoryPagingCookie) Search principals in the given directory service.
List<IDirectoryRole>	searchRoles(IDirectoryPagingCookie pagingCookie, int maxResults) Searches for roles defined in the system based on the pagingCookie and maxResults values
IDirectoryService	updateDirectoryService(String directoryServiceID, Map<String,Object> properties) Creates an instance of IDirectoryService from the supplied parameters.
void	updateDirectoryServicesOrder(List<String> orderedDirServices) Updates the search order of all registeredIDirectoryServices as defined in MWS directory services administration.
void	updateGdprConfig(IGdprConfig config)
default void	updateTotpConfig(ITOTPConfiguration config)

Field Detail

CURRENT_USER

static final String CURRENT_USER

Identifies currently logged in user to be used in the lookupPrincipalByID(String) method. Currently logged it user is only valid inside My webMethods Server

See Also:

Constant Field Values

ROLE_COOKIE_ID

static final String ROLE_COOKIE_ID

See Also:

Constant Field Values

Method Detail

listDirectoryServices

List<IDirectoryService> listDirectoryServices()
                                       throws DirectoryException

Retrieves the list of all 'enabled and running' registeredIDirectoryServices in the search order as defined in MWS directory services administration

Returns:

Throws:

DirectoryException

listAllDirectoryServices

List<IDirectoryService> listAllDirectoryServices()
                                          throws DirectoryException

Retrieves the list of all registeredIDirectoryServices ( regardless of state ) in the search order as defined in MWS directory services administration

Returns:

Throws:

DirectoryException

updateDirectoryServicesOrder

void updateDirectoryServicesOrder(List<String> orderedDirServices)
                           throws DirectoryException

Updates the search order of all registeredIDirectoryServices as defined in MWS directory services administration. All directory services must be supplied for this service. Partial re-ordering is not supported.

Parameters:

directoryServiceID - - the new order for directory services. Supply the URI of each service in the list.

Throws:

DirectoryException

getDirectoryService

IDirectoryService getDirectoryService(String directoryServiceID)
                               throws DirectoryException

Returns instance of IDirectoryService by its ID.

Parameters:

directoryServiceID -

Returns:

Throws:

DirectoryException - if directory service ID is invalid

getDirectoryServiceByName

IDirectoryService getDirectoryServiceByName(String directoryServiceID)
                                     throws DirectoryException

Returns instance of IDirectoryService by its ID.

Parameters:

directoryServiceID -

Returns:

Throws:

DirectoryException - if directory service ID is invalid

deleteDirectoryService

void deleteDirectoryService(String directoryServiceID)
                     throws DirectoryException

Deletes a IDirectoryService by its ID.

Parameters:

directoryServiceID -

Throws:

DirectoryException - if directory service ID is invalid

createDirectoryService

IDirectoryService createDirectoryService(String name,
                                         IDirectoryService.DIRECTORY_XTYPES type,
                                         Map<String,Object> properties)
                                  throws DirectoryException

Creates an instance of IDirectoryService from the supplied parameters.

Parameters:

name - - name of the directory service

type - - type of the directory service

properties - - all attributes of the directory service to be set.

Returns:

- the newly created directory service.

Throws:

DirectoryException - if directory service ID is invalid

updateDirectoryService

IDirectoryService updateDirectoryService(String directoryServiceID,
                                         Map<String,Object> properties)
                                  throws DirectoryException

Creates an instance of IDirectoryService from the supplied parameters.

Parameters:

directoryServiceID - - the id of the directory service

properties - - all attributes of the directory service to be updated.

Returns:

- the updated directory service.

Throws:

DirectoryException - if directory service ID is invalid

getDirectoryServiceDefaultValues

Map<String,Object> getDirectoryServiceDefaultValues(IDirectoryService.DIRECTORY_XTYPES type,
                                                    String dirSubType)
                                             throws DirectoryException

Retruns a Map with the initial directory parameters.

Parameters:

directoryServiceID - - the id of the directory service

properties - - all attributes of the directory service to be updated.

Returns:

- the updated directory service.

Throws:

DirectoryException - if directory service ID is invalid

lookupPrincipalByName

IDirectoryPrincipal lookupPrincipalByName(String principalName,
                                          int type)
                                   throws DirectoryException

Attempts to lookup a principal by their name. Delegates to all the directory services in their configured search order if type is IDirectoryPrincipal.TYPE_GROUP or IDirectoryPrincipal.TYPE_USER Lookup a role by its name if type is IDirectoryPrincipal.TYPE_ROLE

Parameters:

principalName -

type - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP IDirectoryPrincipal.TYPE_ROLE

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByDN

IDirectoryPrincipal lookupPrincipalByDN(String principalDN,
                                        int type)
                                 throws DirectoryException

Attempts to lookup a principal by their dn. Delegates to all the directory services in their configured search order if type is IDirectoryPrincipal.TYPE_GROUP or IDirectoryPrincipal.TYPE_USER Lookup a role by its DN if type is IDirectoryPrincipal.TYPE_ROLE

Parameters:

principalDN -

type - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP IDirectoryPrincipal.TYPE_ROLE

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByDN

IDirectoryPrincipal lookupPrincipalByDN(String principalDN,
                                        int type,
                                        String dirServiceName)
                                 throws DirectoryException

Attempts to lookup a principal by their dn. Delegates to all the directory services in their configured search order if type is IDirectoryPrincipal.TYPE_GROUP or IDirectoryPrincipal.TYPE_USER Lookup a role by its DN if type is IDirectoryPrincipal.TYPE_ROLE

Parameters:

principalDN -

type - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByID

IDirectoryPrincipal lookupPrincipalByID(String principalID)
                                 throws DirectoryException

Attempts to lookup a principal by their unique ID.

Parameters:

principalID - unique principal ID

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupUserByUUID

IDirectoryPrincipal lookupUserByUUID(String principalUUID,
                                     String dirServiceName)
                              throws DirectoryException

Attempts to lookup a user by their unique ID.

Parameters:

principalUUID - - unique principal UUID

dirServiceName - - directory service within which to look for

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

lookupPrincipalByAlias

IDirectoryPrincipal lookupPrincipalByAlias(String principalAlias)
                                    throws DirectoryException

Attempts to lookup a principal by well known alias

Parameters:

principalAlias - MWS defined principal alias

Returns:

the found IDirectoryPrincipal or null if not found

Throws:

DirectoryException

createPagingCookie

IDirectoryPagingCookie createPagingCookie(String directoryServiceID)
                                   throws DirectoryException

Creates instance of directory paging cookie to be used for searchDirectory(String, int, DirectorySearchQuery, IDirectoryPagingCookie) method. All cookies created by this method will be destroyed when close() is invoked. If ROLE_COOKIE_ID is provided as directoryServiceID, a role cookie will be created

Parameters:

directoryServiceID - - directoryID(URI) or ROLE_COOKIE_ID

Returns:

IDirectoryPagingCookie

Throws:

DirectoryException

destroyPagingCookie

void destroyPagingCookie(IDirectoryPagingCookie directoryPagingCookie)

Destroys directory paging cookie and frees up any associated resources

Parameters:

directoryPagingCookie -

searchDirectory

List<IDirectoryPrincipal> searchDirectory(String directoryServiceID,
                                          int principalType,
                                          DirectorySearchQuery query,
                                          IDirectoryPagingCookie directoryPagingCookie)
                                   throws DirectoryException

Search principals in the given directory service. This API works only for users and groups, but not for roles. To list all roles use listRoles() API instead

Parameters:

directoryServiceID - ID of the directory service to search.

principalType - principal type one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP

query - directory query. If null all principals will be returned

directoryPagingCookie - directory paging cookie used for paging/sorting of directory search results.

Returns:

list of found principals. May return empty list

Throws:

DirectoryException

listRoles

List<IDirectoryRole> listRoles()
                        throws DirectoryException

Lists all roles defined in the system

Returns:

list of roles. May return empty list.

Throws:

DirectoryException

getUsersCount

int getUsersCount(IDirectoryService dirSvc)
           throws DirectoryException

Lists all existing users for a particular dir service, or for all dir services if null provided

Parameters:

dirSvc - - the directory service for which to count existing(created in MWS) users, or ALL users if null provided.

Returns:

user count for the specified dir service or all user count

Throws:

DirectoryException

searchRoles

List<IDirectoryRole> searchRoles(IDirectoryPagingCookie pagingCookie,
                                 int maxResults)
                          throws DirectoryException

Searches for roles defined in the system based on the pagingCookie and maxResults values

Parameters:

pagingCookie - directory paging cookie used for paging/sorting of directory search results. To create such a cookie, invoke createPagingCookie(java.lang.String) with parameter ROLE_COOKIE_ID,

maxResults - limits the result list to the maxResults value

Returns:

list of roles. May return empty list.

Throws:

DirectoryException

authenticateUser

IDirectoryUser authenticateUser(String username,
                                String password)
                         throws DirectoryException

Attempts to authenticate the user based on the credentials with any registered directory service in their configured search order.

Parameters:

username -

password -

Returns:

valid authenticated user

Throws:

DirectoryException - if there was a problem authenticating this user

authenticateUser

default IDirectoryUser authenticateUser(String username,
                                        String password,
                                        String oneTimePassword)
                                 throws DirectoryException

Attempts to authenticate the user based on the credentials with any registered directory service in their configured search order.

Parameters:

username -

password -

time-based - one-time password for two-factor identification

Returns:

valid authenticated user

Throws:

DirectoryException - if there was a problem authenticating this user

listAttributeProviders

List<IDirectoryPrincipalAttributeProvider> listAttributeProviders(int principalType)
                                                           throws DirectoryException

Gets all registered principal attribute providers IDirectoryPrincipalAttributeProvider

Parameters:

principalType - one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP IDirectoryPrincipal.TYPE_ROLE

Returns:

list of principal attribute providers for specified principal type

Throws:

DirectoryException

getAttributeProvider

IDirectoryPrincipalAttributeProvider getAttributeProvider(String attributeProviderID)
                                                   throws DirectoryException

Gets IDirectoryPrincipalAttributeProvider by its ID

Throws:

DirectoryException

getAttributeNames

List<String> getAttributeNames(String principalID,
                               String principalAttributeProviderID)
                        throws DirectoryException

List defined attribute names for the specified attribute provider

Parameters:

principalID - ID of the principal

principalAttributeProviderID - ID of the principal attribute provider

Returns:

list of attribute names defined for specified attribute provider

Throws:

DirectoryException

getAttributeTitles

List<String> getAttributeTitles(String principalID,
                                String principalAttributeProviderID,
                                Locale locale)
                         throws DirectoryException

List defined user friendly attribute titles for the specified attribute provider

Parameters:

principalID - ID of the principal

principalAttributeProviderID - ID of the principal attribute provider

locale - desired locale for attribute titles

Returns:

list of attribute titles for the specified attribute provider

Throws:

DirectoryException

getAttributeExtendedInfo

Map<String,Object> getAttributeExtendedInfo(String principalID,
                                            String principalAttributeProviderID,
                                            String attributeName)
                                     throws DirectoryException

Returns extended information about attributes of the given provider (only if provider supports this

Parameters:

principalID - ID of the principal

principalAttributeProviderID - ID of the principal attribute provider

attributeName - attribute name

Returns:

Map containing extended information about this attribute

Throws:

DirectoryException

createPrincipal

IDirectoryPrincipal createPrincipal(String directoryServiceID,
                                    int principalType,
                                    String name,
                                    Map<String,? extends Object> properties)
                             throws DirectoryException

Creates a new principal group or user associated with this specified directory service. It may throw exception if directory service does not support creation of principals. Not accounting for custom implementations only MWS System Directory supports creation of principals

Parameters:

directoryServiceID - ID of the directory service to create principal ID.

type - of the principal to create one of the IDirectoryPrincipal.TYPE_USER, IDirectoryPrincipal.TYPE_GROUP

name - of the principal (UID)

properties - name-value pairs

Returns:

a newly created IDirectoryPrincipal

Throws:

DirectoryException

createRole

@Deprecated
IDirectoryRole createRole(int roleType,
                                      String name,
                                      Map<String,?> properties)
                               throws DirectoryException

Deprecated. Use createRole(String, String, Map) instead

Creates new role of the specified type

Parameters:

roleType - type of the role to create IDirectoryRole

name - of the role (UID)

properties - name-value pairs of properties assigned to the new role

Returns:

a newly created IDirectoryRole

Throws:

DirectoryException

createRole

IDirectoryRole createRole(String roleType,
                          String name,
                          Map<String,?> properties)
                   throws DirectoryException

Creates new role of the specified type

Parameters:

roleType - type of the role to create IDirectoryRole

nameof - the role (UID)

properties - name-value pairs of properties assigned to the new role

Returns:

a newly created IDirectoryRole

Throws:

DirectoryException

deletePrincipal

void deletePrincipal(String principalID)
              throws DirectoryException

Deletes a principal by its unique ID

Parameters:

principalID -

Throws:

DirectoryException

addPrincipalToGroup

void addPrincipalToGroup(String principalID,
                         String groupID)
                  throws DirectoryException

Adds a principal to a group. Note, both the principal and the group must belong to the same IDirectoryService

Parameters:

principalID - ID of the principal to be added to the group

groupID - ID of the group to add principal to

Throws:

DirectoryException

addPrincipalToRole

void addPrincipalToRole(String principalID,
                        String roleID)
                 throws DirectoryException

Adds a principal to a role. Not all role type support modification of membership. Not accounting for custom implementations only static IDirectoryRole.ROLE_TYPE_STATIC role supports this operation

Parameters:

principalID - ID of the principal to be added to the role

roleID - ID of the role to add principal to

Throws:

DirectoryException

removePrincipalFromGroup

void removePrincipalFromGroup(String principalID,
                              String groupID)
                       throws DirectoryException

Removes a principal from a group. Note, both the principal and the group must belong to the same IDirectoryService

Parameters:

principalID - ID of the principal to be removed from the group

groupID - ID of the group to remove principal from

Throws:

DirectoryException

removePrincipalFromRole

void removePrincipalFromRole(String principalID,
                             String roleID)
                      throws DirectoryException

Removes a principal from a role. Not all role type support modification of membership. Not accounting for custom implementations only static IDirectoryRole.ROLE_TYPE_STATIC role supports this operation

Parameters:

principalID - ID of the principal to be removed from the role

roleID - ID of the role to remove principal from

Throws:

DirectoryException

getGroupMembership

List<IDirectoryGroup> getGroupMembership(String principalID)
                                  throws DirectoryException

Retrieve the group membership for this principal

Parameters:

principalID - ID of the principal to get group membership for

Returns:

list of IDirectoryGroup principal is member of

Throws:

DirectoryException

getRoleMembership

List<IDirectoryRole> getRoleMembership(String principalID)
                                throws DirectoryException

Retrieve the role membership for this principal

Parameters:

principalID - IF of the principal to get role membership for

Returns:

list of IDirectoryRole principal is member of

Throws:

DirectoryException

getMembers

List<IDirectoryPrincipal> getMembers(String principalID)
                              throws DirectoryException

Returns members of the group or role. Not all roles types support querying for its members. Not accounting for custom implementations only static IDirectoryRole.ROLE_TYPE_STATIC role supports this operation

Parameters:

principalID - role or group ID

Returns:

a list of members of this role or group

Throws:

DirectoryException

modifyPrincipal

void modifyPrincipal(String principalID,
                     Map<String,? extends Object> attributes)
              throws DirectoryException

Sets attribute values for the principal. Attributes map passed in may contain attributes from different principal attribute providers.

Parameters:

principalID - ID of the principal to be updated

attributes - attribute values to be set

Throws:

DirectoryException

getCertificateManager

ICertificateManager getCertificateManager()

Returns instance of certificate manager

close

void close()

Release any resources

Specified by:

close in interface AutoCloseable

beginConversation

default void beginConversation()

Mark the current transient conversation long-running. Starting with the next exchanged message, all further communication will be handled by the same cluster node until the #end() is invoked.

endConversation

default void endConversation()

Mark the current long-running conversation transient. The next exchanged message will not be sent to a specific cluster node rather the next available one

isConversation

default boolean isConversation()

Returns if the conversation is marked transient or long-running

Returns:

true if a converation is in progress, false otherwise

updateGdprConfig

void updateGdprConfig(IGdprConfig config)

getGdprConfig

IGdprConfig getGdprConfig()

updateTotpConfig

default void updateTotpConfig(ITOTPConfiguration config)

getTotpConfig

default ITOTPConfiguration getTotpConfig()

getTypedAttributes

default Map<String,TypedAttribute> getTypedAttributes(String papID,
                                                      String principalURI)
                                               throws DirectoryException

Throws:

DirectoryException

getAttribute

default Object getAttribute(String principalID,
                            String papID,
                            String attrName)
                     throws DirectoryException

Throws:

DirectoryException