Package org.odpi.openmetadata.accessservices.securitymanager.client

Class SecurityManagerClient

java.lang.Object

org.odpi.openmetadata.accessservices.securitymanager.client.SecurityManagerClient

All Implemented Interfaces:

SecurityManagerInterface

public class SecurityManagerClient
extends Object
implements SecurityManagerInterface

SecurityManagerClient is the client for explicitly managing the user identity entities and associating them with profiles. It is typically used when the relationship between user identities and profiles are many to one.

Constructor Summary

Constructors

Constructor	Description
SecurityManagerClient(String serverName, String serverPlatformURLRoot)	Create a new client with no authentication embedded in the HTTP request.
SecurityManagerClient(String serverName, String serverPlatformURLRoot, String userId, String password)	Create a new client that passes userId and password in each HTTP request.
SecurityManagerClient(String serverName, String serverPlatformURLRoot, String userId, String password, AuditLog auditLog)	Create a new client that passes userId and password in each HTTP request.
SecurityManagerClient(String serverName, String serverPlatformURLRoot, SecurityManagerRESTClient restClient, int maxPageSize)	Create a new client that passes userId and password in each HTTP request.
SecurityManagerClient(String serverName, String serverPlatformURLRoot, AuditLog auditLog)	Create a new client with no authentication embedded in the HTTP request.

Method Summary

Modifier and Type	Method	Description
String	createSecurityGroup(String userId, SecurityGroupProperties properties)	Create a new security group.
String	createUserIdentity(String userId, String externalSourceGUID, String externalSourceName, UserIdentityProperties newIdentity)	Create a UserIdentity.
void	deleteSecurityGroup(String userId, String securityGroupGUID)	Delete a specific security group.
void	deleteUserIdentity(String userId, String externalSourceGUID, String externalSourceName, String userIdentityGUID)	Remove a user identity object.
List<ActorProfileElement>	findActorProfile(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of matching profiles for the search string.
List<PersonRoleElement>	findPersonRole(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of matching roles for the search string.
List<SecurityGroupElement>	findSecurityGroups(String userId, String searchString, int startFrom, int pageSize)	Return the list of security groups that match the search string - this can be a regular expression.
List<UserIdentityElement>	findUserIdentities(String userId, String searchString, int startFrom, int pageSize)	Retrieve the list of user identity metadata elements that contain the search string.
ActorProfileElement	getActorProfileByGUID(String userId, String actorProfileGUID)	Return information about a specific actor profile.
List<ActorProfileElement>	getActorProfileByName(String userId, String name, int startFrom, int pageSize)	Return information about a named actor profile.
ActorProfileElement	getActorProfileByUserId(String userId, String actorProfileUserId)	Return information about a specific actor profile.
List<PersonRoleAppointee>	getAppointees(String userId, String personRoleGUID, Date effectiveTime, int startFrom, int pageSize)	Return the list of people appointed to a particular role.
List<ElementStub>	getElementsGovernedBySecurityGroup(String userId, String securityGroupGUID, int startFrom, int pageSize)	Return the elements that are governed by the supplied security group.
PersonRoleElement	getPersonRoleByGUID(String userId, String personRoleGUID)	Return information about a specific person role.
List<PersonRoleElement>	getPersonRoleByName(String userId, String name, int startFrom, int pageSize)	Return information about a named person role.
SecurityGroupElement	getSecurityGroupByGUID(String userId, String securityGroupGUID)	Retrieve the security group metadata element with the supplied unique identifier.
List<SecurityGroupElement>	getSecurityGroupsForDistinguishedName(String userId, String distinguishedName, int startFrom, int pageSize)	Return the list of security groups associated with a unique distinguishedName.
List<UserIdentityElement>	getUserIdentitiesByName(String userId, String name, int startFrom, int pageSize)	Retrieve the list of user identity metadata elements with a matching qualified name.
UserIdentityElement	getUserIdentityByGUID(String userId, String userIdentityGUID)	Retrieve the userIdentity metadata element with the supplied unique identifier.
void	updateSecurityGroup(String userId, String securityGroupGUID, boolean isMergeUpdate, SecurityGroupProperties properties)	Update an existing security group.
void	updateUserIdentity(String userId, String externalSourceGUID, String externalSourceName, String userIdentityGUID, boolean isMergeUpdate, UserIdentityProperties properties)	Update a UserIdentity.

Methods inherited from class java.lang.Object

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

Constructor Details

SecurityManagerClient

public SecurityManagerClient(String serverName,
 String serverPlatformURLRoot)
                      throws InvalidParameterException

Create a new client with no authentication embedded in the HTTP request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

Throws:

InvalidParameterException - bad input parameters

SecurityManagerClient

public SecurityManagerClient(String serverName,
 String serverPlatformURLRoot,
 AuditLog auditLog)
                      throws InvalidParameterException

Create a new client with no authentication embedded in the HTTP request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

auditLog - logging destination

Throws:

InvalidParameterException - there is a problem creating the client-side components to issue any REST API calls.

SecurityManagerClient

public SecurityManagerClient(String serverName,
 String serverPlatformURLRoot,
 String userId,
 String password)
                      throws InvalidParameterException

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

userId - caller's userId embedded in all HTTP requests

password - caller's userId embedded in all HTTP requests

Throws:

InvalidParameterException - bad input parameters

SecurityManagerClient

public SecurityManagerClient(String serverName,
 String serverPlatformURLRoot,
 String userId,
 String password,
 AuditLog auditLog)
                      throws InvalidParameterException

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

userId - caller's userId embedded in all HTTP requests

password - caller's userId embedded in all HTTP requests

auditLog - logging destination

Throws:

InvalidParameterException - bad input parameters

SecurityManagerClient

public SecurityManagerClient(String serverName,
 String serverPlatformURLRoot,
 SecurityManagerRESTClient restClient,
 int maxPageSize)
                      throws InvalidParameterException

Create a new client that passes userId and password in each HTTP request. This is the userId/password of the calling server. The end user's userId is sent on each request.

Parameters:

serverName - name of the server to connect to

serverPlatformURLRoot - the network address of the server running the OMAS REST services

restClient - pre-initialized REST client

maxPageSize - pre-initialized parameter limit

Throws:

InvalidParameterException - there is a problem with the information about the remote OMAS

Method Details

createSecurityGroup

public String createSecurityGroup(String userId,
 SecurityGroupProperties properties)
                           throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Create a new security group. The type of the definition is located in the properties.

Specified by:

createSecurityGroup in interface SecurityManagerInterface

Parameters:

userId - calling user

properties - properties of the definition

Returns:

unique identifier of the definition

Throws:

InvalidParameterException - typeName, documentIdentifier or userId is null; documentIdentifier is not unique; typeName is not valid

PropertyServerException - problem accessing the metadata service

UserNotAuthorizedException - security access problem

updateSecurityGroup

public void updateSecurityGroup(String userId,
 String securityGroupGUID,
 boolean isMergeUpdate,
 SecurityGroupProperties properties)
                         throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Update an existing security group.

Specified by:

updateSecurityGroup in interface SecurityManagerInterface

Parameters:

userId - calling user

securityGroupGUID - unique identifier of the definition to update

isMergeUpdate - are unspecified properties unchanged (true) or removed?

properties - properties to update

Throws:

InvalidParameterException - guid, documentIdentifier or userId is null; documentIdentifier is not unique; guid is not known

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

deleteSecurityGroup

public void deleteSecurityGroup(String userId,
 String securityGroupGUID)
                         throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Delete a specific security group.

Specified by:

deleteSecurityGroup in interface SecurityManagerInterface

Parameters:

userId - calling user

securityGroupGUID - unique identifier of the definition to remove

Throws:

InvalidParameterException - guid is null or not known

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getSecurityGroupsForDistinguishedName

public List<SecurityGroupElement> getSecurityGroupsForDistinguishedName(String userId,
 String distinguishedName,
 int startFrom,
 int pageSize)
                                                                 throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return the list of security groups associated with a unique distinguishedName. In an ideal world, the should be only one.

Specified by:

getSecurityGroupsForDistinguishedName in interface SecurityManagerInterface

Parameters:

userId - calling user

distinguishedName - unique name of the security group

startFrom - where to start from in the list of definitions

pageSize - max number of results to return in one call

Returns:

list of security groups

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the caller is not authorized to issue the request

PropertyServerException - the metadata service has problems

getElementsGovernedBySecurityGroup

public List<ElementStub> getElementsGovernedBySecurityGroup(String userId,
 String securityGroupGUID,
 int startFrom,
 int pageSize)
                                                     throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return the elements that are governed by the supplied security group.

Specified by:

getElementsGovernedBySecurityGroup in interface SecurityManagerInterface

Parameters:

userId - calling user

securityGroupGUID - unique name of the security group

startFrom - where to start from in the list of definitions

pageSize - max number of results to return in one call

Returns:

list of headers for the associated elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the caller is not authorized to issue the request

PropertyServerException - the metadata service has problems

findSecurityGroups

public List<SecurityGroupElement> findSecurityGroups(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                                              throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return the list of security groups that match the search string - this can be a regular expression.

Specified by:

findSecurityGroups in interface SecurityManagerInterface

Parameters:

userId - calling user

searchString - value to search for

startFrom - where to start from in the list of definition results

pageSize - max number of results to return in one call

Returns:

list of security groups

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the caller is not authorized to issue the request

PropertyServerException - the metadata service has problems

getSecurityGroupByGUID

public SecurityGroupElement getSecurityGroupByGUID(String userId,
 String securityGroupGUID)
                                            throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the security group metadata element with the supplied unique identifier.

Specified by:

getSecurityGroupByGUID in interface SecurityManagerInterface

Parameters:

userId - calling user

securityGroupGUID - unique identifier of the requested metadata element

Returns:

matching metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

createUserIdentity

public String createUserIdentity(String userId,
 String externalSourceGUID,
 String externalSourceName,
 UserIdentityProperties newIdentity)
                          throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Create a UserIdentity.

Specified by:

createUserIdentity in interface SecurityManagerInterface

Parameters:

userId - the name of the calling user.

externalSourceGUID - unique identifier of software server capability representing the caller

externalSourceName - unique name of software server capability representing the caller

newIdentity - properties for the new userIdentity.

Returns:

unique identifier of the UserIdentity

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

updateUserIdentity

public void updateUserIdentity(String userId,
 String externalSourceGUID,
 String externalSourceName,
 String userIdentityGUID,
 boolean isMergeUpdate,
 UserIdentityProperties properties)
                        throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Update a UserIdentity.

Specified by:

updateUserIdentity in interface SecurityManagerInterface

Parameters:

userId - the name of the calling user

externalSourceGUID - unique identifier of software server capability representing the caller

externalSourceName - unique name of software server capability representing the caller

userIdentityGUID - unique identifier of the UserIdentity

isMergeUpdate - should the supplied properties be overlaid on the existing properties (true) or replace them (false

properties - updated properties for the new userIdentity

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

deleteUserIdentity

public void deleteUserIdentity(String userId,
 String externalSourceGUID,
 String externalSourceName,
 String userIdentityGUID)
                        throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Remove a user identity object. This will fail if the profile would be left without an associated user identity.

Specified by:

deleteUserIdentity in interface SecurityManagerInterface

Parameters:

userId - the name of the calling user

externalSourceGUID - unique identifier of software server capability representing the caller

externalSourceName - unique name of software server capability representing the caller

userIdentityGUID - unique identifier of the UserIdentity

Throws:

InvalidParameterException - one of the parameters is invalid.

PropertyServerException - there is a problem retrieving information from the property server(s).

UserNotAuthorizedException - the requesting user is not authorized to issue this request.

findUserIdentities

public List<UserIdentityElement> findUserIdentities(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                                             throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of user identity metadata elements that contain the search string. The search string is treated as a regular expression.

Specified by:

findUserIdentities in interface SecurityManagerInterface

Parameters:

userId - calling user

searchString - string to find in the properties

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getUserIdentitiesByName

public List<UserIdentityElement> getUserIdentitiesByName(String userId,
 String name,
 int startFrom,
 int pageSize)
                                                  throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the list of user identity metadata elements with a matching qualified name. There are no wildcards supported on this request.

Specified by:

getUserIdentitiesByName in interface SecurityManagerInterface

Parameters:

userId - calling user

name - name to search for

startFrom - paging start point

pageSize - maximum results that can be returned

Returns:

list of matching metadata elements

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getUserIdentityByGUID

public UserIdentityElement getUserIdentityByGUID(String userId,
 String userIdentityGUID)
                                          throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Retrieve the userIdentity metadata element with the supplied unique identifier.

Specified by:

getUserIdentityByGUID in interface SecurityManagerInterface

Parameters:

userId - calling user

userIdentityGUID - unique identifier of the requested metadata element

Returns:

matching metadata element

Throws:

InvalidParameterException - one of the parameters is invalid

UserNotAuthorizedException - the user is not authorized to issue this request

PropertyServerException - there is a problem reported in the open metadata server(s)

getActorProfileByGUID

public ActorProfileElement getActorProfileByGUID(String userId,
 String actorProfileGUID)
                                          throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return information about a specific actor profile.

Specified by:

getActorProfileByGUID in interface SecurityManagerInterface

Parameters:

userId - calling user

actorProfileGUID - unique identifier for the actor profile

Returns:

properties of the actor profile

Throws:

InvalidParameterException - actorProfileGUID or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getActorProfileByUserId

public ActorProfileElement getActorProfileByUserId(String userId,
 String actorProfileUserId)
                                            throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return information about a specific actor profile.

Specified by:

getActorProfileByUserId in interface SecurityManagerInterface

Parameters:

userId - calling user

actorProfileUserId - unique identifier for the actor profile

Returns:

properties of the actor profile

Throws:

InvalidParameterException - actorProfileUserId or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getActorProfileByName

public List<ActorProfileElement> getActorProfileByName(String userId,
 String name,
 int startFrom,
 int pageSize)
                                                throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return information about a named actor profile.

Specified by:

getActorProfileByName in interface SecurityManagerInterface

Parameters:

userId - calling user

name - unique name for the actor profile

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

list of matching actor profiles (hopefully only one)

Throws:

InvalidParameterException - name or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

findActorProfile

public List<ActorProfileElement> findActorProfile(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                                           throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Retrieve the list of matching profiles for the search string.

Specified by:

findActorProfile in interface SecurityManagerInterface

Parameters:

userId - the name of the calling user.

searchString - RegEx string to search for

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

list of matching actor profiles

Throws:

InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.

getAppointees

public List<PersonRoleAppointee> getAppointees(String userId,
 String personRoleGUID,
 Date effectiveTime,
 int startFrom,
 int pageSize)
                                        throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return the list of people appointed to a particular role.

Specified by:

getAppointees in interface SecurityManagerInterface

Parameters:

userId - calling user

personRoleGUID - unique identifier of the person role

effectiveTime - time for appointments, null for full appointment history

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return

Returns:

list of appointees

Throws:

InvalidParameterException - one of the guids is null or not known

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getPersonRoleByGUID

public PersonRoleElement getPersonRoleByGUID(String userId,
 String personRoleGUID)
                                      throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return information about a specific person role.

Specified by:

getPersonRoleByGUID in interface SecurityManagerInterface

Parameters:

userId - calling user

personRoleGUID - unique identifier for the person role

Returns:

properties of the person role

Throws:

InvalidParameterException - personRoleGUID or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

getPersonRoleByName

public List<PersonRoleElement> getPersonRoleByName(String userId,
 String name,
 int startFrom,
 int pageSize)
                                            throws InvalidParameterException,
UserNotAuthorizedException,
PropertyServerException

Return information about a named person role.

Specified by:

getPersonRoleByName in interface SecurityManagerInterface

Parameters:

userId - calling user

name - unique name for the actor profile

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

list of matching actor profiles (hopefully only one)

Throws:

InvalidParameterException - name or userId is null

PropertyServerException - problem accessing property server

UserNotAuthorizedException - security access problem

findPersonRole

public List<PersonRoleElement> findPersonRole(String userId,
 String searchString,
 int startFrom,
 int pageSize)
                                       throws InvalidParameterException,
PropertyServerException,
UserNotAuthorizedException

Retrieve the list of matching roles for the search string.

Specified by:

findPersonRole in interface SecurityManagerInterface

Parameters:

userId - the name of the calling user.

searchString - RegEx string to search for

startFrom - index of the list to start from (0 for start)

pageSize - maximum number of elements to return.

Returns:

list of matching actor profiles

Throws:

InvalidParameterException - guid invalid or the external references are not correctly specified, or are null.

PropertyServerException - the server is not available.

UserNotAuthorizedException - the calling user is not authorized to issue the call.