Class ActorService

java.lang.Object

de.gustavblass.fsu.fmi.roombooking.service.ActorService

All Implemented Interfaces:

org.springframework.security.core.userdetails.UserDetailsService

@Service
public class ActorService
extends Object
implements org.springframework.security.core.userdetails.UserDetailsService

Provides functionality to manage Actors, namely to create, modify and delete them.

Field Summary

Fields

Modifier and Type	Field	Description
private final @NonNull ActorMapper	actorMapper	Creates Actor objects from data-transfer objects representing Actors created by administrators (ActorAuthority.IT_ADMINISTRATION, ActorAuthority.FACULTY_ADMINISTRATION).
private final @NonNull ActorMetadataRepository	actorMetadataRepository	Provides database access to modify the ActorMetadata.
private final @NonNull ActorRepository	actorRepository	Provides database access to actually create, modify and delete Actors.
private @NonNull String	defaultPassword	The Actor.password() of the default administrator.
private @NonNull String	defaultUserName	The Actor.userName of the default administrator.
private final @NonNull List<String>	domainBlacklist	These domains are explicitly not permitted as part of the Actors' e-mail addresses.
private final @NonNull List<String>	domainWhitelist	If this List is not empty, only these domains are permitted in the Actors' e-mail addresses.
private final @NonNull Duration	eMailVerificationTokenValidity	How long new EMailVerificationTokens shall be valid after creation.
private final @NonNull org.springframework.context.ApplicationEventPublisher	eventPublisher	Used to publish certain events like ActorCreatedEvent.
private @Nullable org.springframework.security.ldap.authentication.LdapAuthenticationProvider	ldapAuthenticationProvider	Used to authenticate users against an LDAP server.
private final @Nullable org.springframework.security.ldap.authentication.BindAuthenticator	ldapAuthenticator	Used to authenticate users against an LDAP server.
private final @NonNull org.springframework.security.crypto.password.PasswordEncoder	passwordEncoder	Used to hash Actors' passwords.
private final @NonNull RegistrationMode	registrationMode	Whether and which registrations are configured to be permitted.
private final @NonNull ReservationService	reservationService	Used by deleteActor(String) to find Reservations of the user to be deleted.
private final @NonNull VerificationTokenRepository	verificationTokenRepository	Provides database access to save and retrieve VerificationTokens.
private final @NonNull Duration	verificationTokenValidity	How long new VerificationTokens shall be valid after creation.

Constructor Summary

Constructors

Constructor

Description

ActorService(@NonNull ActorRepository actorRepository, @NonNull ActorMetadataRepository actorMetadataRepository, @NonNull VerificationTokenRepository verificationTokenRepository, @NonNull ActorMapper actorMapper, @NonNull org.springframework.security.crypto.password.PasswordEncoder passwordEncoder, @NonNull ReservationService reservationService, @Nullable org.springframework.security.ldap.authentication.BindAuthenticator bindAuthenticator, @NonNull RegistrationMode registrationMode, @NonNull Duration verificationTokenValidity, @NonNull Duration eMailVerificationTokenValidity, @NonNull List<String> eMailDomainWhitelist, @NonNull List<String> eMailDomainBlacklist, @NonNull org.springframework.context.ApplicationEventPublisher eventPublisher)

Method Summary

Modifier and Type	Method	Description
void	changeEMailAddress(@NonNull String newEMailAddress)	Stores a new EMailVerificationToken with the given EMailVerificationToken.eMailAddress in the database, in order to allow an Actor to change their Actor.eMailAddress by opening a confirmation link that will be sent by e-mail.
void	changeName(@NonNull String newName)	Updates the Actor.name of the current user.
void	changePassword(@NonNull ChangePasswordDTO changePasswordDTO)	Sets the Actor.password() of the CurrentAuthorityService.getActor() (who must be a LocalActor) to hash of the given ChangePasswordDTO.newPassword.
void	changeUserName(@NonNull String newUserName)	Updates the Actor.userName of the current user.
@NonNull Actor	confirmNewEMail(@NonNull String verificationToken)	Changes the Actor.eMailAddress of the VerificationToken.actor to the new EMailVerificationToken.eMailAddress.
@NonNull Actor	createActor(@NonNull LocalActorCreatedByAdminDTO dto)	Saves a new Actor to the database.
void	deleteActor(@NonNull String userName)	Removes the Actor with the given Actor.userName from the database.
@NonNull Actor	enableAccount(@NonNull String verificationToken)	Sets Actor.enabled to true for the VerificationToken.actor belonging to the given VerificationToken.token.
@NonNull org.springframework.data.domain.Page<Actor>	findAll(@NonNull org.springframework.data.domain.Pageable pageable)	A subset of all Actors in the database table according to the given Pageable.
@NonNull Actor	findUserByUserName(@NonNull String userName)	Fetches the Actor with the specified user name.
private @NonNull VerificationToken	generateVerificationToken(@NonNull Actor actor)	Generates a new VerificationToken with the verificationTokenValidity for the given Actor and saves the former to the database.
void	initialise()	Creates an administrator Actor from the defaultUserName and defaultPassword and saves the new administrator to the database, after the application has started.
void	initialiseLdap()	If the ldapAuthenticator has been set up, initialises the ldapAuthenticationProvider with it.
private boolean	isValidAndAllowedEmail(@NonNull String eMailAddress)	Verifies that the given e-mail address is syntactically valid and that simultaneously
@NonNull org.springframework.security.core.userdetails.UserDetails	loadUserByUsername(@NonNull String username)	Do not use this method! It is meant only for the Spring framework!
void	onLogin(@NonNull org.springframework.security.authentication.event.AuthenticationSuccessEvent success)	Updates the ActorMetadata.lastLogin of the Actor of the given AuthenticationSuccessEvent.
void	onRegistration(@NonNull ActorCreatedEvent createdEvent)	Saves the registration date of the given ActorCreatedEvent to the ActorMetadata belonging to the ActorCreatedEvent.actor.
void	register(@NonNull LdapRegistrationActorDTO ldapRegistrationActorDTO)	Creates a new Actor in the database, according to the given LdapRegistrationActorDTO.
void	register(@NonNull LocalRegistrationActorDTO localRegistrationActorDTO)	Creates a new Actor in the database, according to the given LocalRegistrationActorDTO.

Methods inherited from class Object

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

Field Details

defaultUserName

@Value("${spring.security.user.name}")
@NonNull
private @NonNull String defaultUserName

The Actor.userName of the default administrator.

defaultPassword

@Value("${spring.security.user.password}")
@NonNull
private @NonNull String defaultPassword

The Actor.password() of the default administrator.

actorRepository

@NonNull
private final @NonNull ActorRepository actorRepository

Provides database access to actually create, modify and delete Actors.

actorMetadataRepository

@NonNull
private final @NonNull ActorMetadataRepository actorMetadataRepository

Provides database access to modify the ActorMetadata.

verificationTokenRepository

@NonNull
private final @NonNull VerificationTokenRepository verificationTokenRepository

Provides database access to save and retrieve VerificationTokens.

reservationService

@NonNull
private final @NonNull ReservationService reservationService

Used by deleteActor(String) to find Reservations of the user to be deleted.

passwordEncoder

@NonNull
private final @NonNull org.springframework.security.crypto.password.PasswordEncoder passwordEncoder

Used to hash Actors' passwords.

actorMapper

@NonNull
private final @NonNull ActorMapper actorMapper

Creates Actor objects from data-transfer objects representing Actors created by administrators (ActorAuthority.IT_ADMINISTRATION, ActorAuthority.FACULTY_ADMINISTRATION).

ldapAuthenticator

@Nullable
private final @Nullable org.springframework.security.ldap.authentication.BindAuthenticator ldapAuthenticator

Used to authenticate users against an LDAP server.

ldapAuthenticationProvider

@Nullable
private @Nullable org.springframework.security.ldap.authentication.LdapAuthenticationProvider ldapAuthenticationProvider

Used to authenticate users against an LDAP server.

registrationMode

@NonNull
private final @NonNull RegistrationMode registrationMode

Whether and which registrations are configured to be permitted.

verificationTokenValidity

@NonNull
private final @NonNull Duration verificationTokenValidity

How long new VerificationTokens shall be valid after creation.

eMailVerificationTokenValidity

@NonNull
private final @NonNull Duration eMailVerificationTokenValidity

How long new EMailVerificationTokens shall be valid after creation.

domainWhitelist

@NonNull
private final @NonNull List<String> domainWhitelist

If this List is not empty, only these domains are permitted in the Actors' e-mail addresses. Overrides the domainBlacklist.

domainBlacklist

@NonNull
private final @NonNull List<String> domainBlacklist

These domains are explicitly not permitted as part of the Actors' e-mail addresses. Less important than the domainWhitelist.

eventPublisher

@NonNull
private final @NonNull org.springframework.context.ApplicationEventPublisher eventPublisher

Used to publish certain events like ActorCreatedEvent.

Constructor Details

ActorService

public ActorService(@NonNull
 @NonNull ActorRepository actorRepository,
 @NonNull
 @NonNull ActorMetadataRepository actorMetadataRepository,
 @NonNull
 @NonNull VerificationTokenRepository verificationTokenRepository,
 @NonNull
 @NonNull ActorMapper actorMapper,
 @NonNull
 @NonNull org.springframework.security.crypto.password.PasswordEncoder passwordEncoder,
 @NonNull
 @NonNull ReservationService reservationService,
 @Nullable
 @Nullable org.springframework.security.ldap.authentication.BindAuthenticator bindAuthenticator,
 @NonNull
 @NonNull RegistrationMode registrationMode,
 @NonNull
 @NonNull Duration verificationTokenValidity,
 @NonNull
 @NonNull Duration eMailVerificationTokenValidity,
 @NonNull
 @NonNull List<String> eMailDomainWhitelist,
 @NonNull
 @NonNull List<String> eMailDomainBlacklist,
 @NonNull
 @NonNull org.springframework.context.ApplicationEventPublisher eventPublisher)

Parameters:

actorRepository - The actorRepository to use for database access.

actorMetadataRepository - The actorMetadataRepository.

verificationTokenRepository - The verificationTokenRepository.

actorMapper - The actorMapper used to convert data-transfer objects to Actor objects.

passwordEncoder - The passwordEncoder used to hash Actors' passwords.

reservationService - The reservationService.

bindAuthenticator - The ldapAuthenticator.

registrationMode - The registrationMode.

verificationTokenValidity - The verificationTokenValidity.

eMailVerificationTokenValidity - The eMailVerificationTokenValidity.

eMailDomainWhitelist - The domainWhitelist.

eMailDomainBlacklist - The domainBlacklist.

eventPublisher - The eventPublisher.

Method Details

initialise

@PostConstruct
public void initialise()

Creates an administrator Actor from the defaultUserName and defaultPassword and saves the new administrator to the database, after the application has started.

initialiseLdap

@PostConstruct
public void initialiseLdap()

If the ldapAuthenticator has been set up, initialises the ldapAuthenticationProvider with it.

generateVerificationToken

@NonNull
private @NonNull VerificationToken generateVerificationToken(@NonNull
 @NonNull Actor actor)

Generates a new VerificationToken with the verificationTokenValidity for the given Actor and saves the former to the database.

Does not check whether the Actor.isEnabled().

Parameters:

actor - The VerificationToken.actor.

Returns:

The VerificationToken that was generated.

isValidAndAllowedEmail

private boolean isValidAndAllowedEmail(@NonNull
 @NonNull String eMailAddress)

Verifies that the given e-mail address is syntactically valid and that simultaneously

• it is listed in the domainWhitelist or
• the domainWhitelist is empty and the e-mail address is not listed in the domainBlacklist.

Parameters:

eMailAddress - The e-mail address that shall be checked.

Returns:

True if the e-mail is valid and allowed, false if it is invalid or banned.

findAll

@PreAuthorize("hasRole('FACULTY_ADMINISTRATION')")
@NonNull
public @NonNull org.springframework.data.domain.Page<Actor> findAll(@NonNull
 @NonNull org.springframework.data.domain.Pageable pageable)

A subset of all Actors in the database table according to the given Pageable.

Parameters:

pageable - The pagination information specifying which page of Actors shall be returned.

Returns:

All actors, but only the specified subset.

See Also:

• ActorRepository.findAll(Pageable)

findUserByUserName

@NonNull
public @NonNull Actor findUserByUserName(@NonNull
 @NonNull String userName)
                                  throws NotFoundException

Fetches the Actor with the specified user name.

Parameters:

userName - The user name whose corresponding Actor shall be returned.

Returns:

The Actor associated with the given user name.

Throws:

NotFoundException - If no Actor with the given user name exists.

Implementation Note:

There is no @PreAuthorize here because it would impair the LDAP login process, because it needs to tell the LDAP library who the authenticated user is. Since the user is not authenticated at that point yet, this method would fail. (We trust the LDAP server not to allow people to impersonate other users.)

loadUserByUsername

@NonNull
public @NonNull org.springframework.security.core.userdetails.UserDetails loadUserByUsername(@NonNull
 @NonNull String username)
                                                                                      throws org.springframework.security.core.userdetails.UsernameNotFoundException,
NoSuchLocalUserException

Do not use this method! It is meant only for the Spring framework!

Specified by:

loadUserByUsername in interface org.springframework.security.core.userdetails.UserDetailsService

Throws:

org.springframework.security.core.userdetails.UsernameNotFoundException - An Actor with the given Actor.userName does exist, but they do not have set an Actor.password(), so that the Actor cannot be used for authentication by the DaoAuthenticationProvider.

NoSuchLocalUserException - No Actor with the given user name exists, so that no AuthenticationProvider can authenticate the current request. (ProviderManager will stop attempting authentication if an AccountStatusException is thrown by an AuthenticationProvider.)

createActor

@NonNull
public @NonNull Actor createActor(@NonNull
 @NonNull LocalActorCreatedByAdminDTO dto)
                           throws UnauthorisedException,
PasswordNotConfirmedException,
AlreadyExistsException,
de.gustavblass.commons.exceptions.IllegalArgumentException

Saves a new Actor to the database.

The Actor on whose behalf this method is called must have sufficient privilege to create Actors with the ActorRole that the given data-transfer object has.

Generates a new VerificationToken for the Actor and publishes a new ActorCreatedEvent. Will be an UnconfirmedRegistrationEvent if the account is not enabled.

Warning!

This method clears the given data-transfer object in case of success! Then, it will be stripped of all data for security reasons and become useless!

The password will, of course, be hashed before saving it to the database.

Parameters:

dto - The data-transfer object sent to the server by a client, based on which a new Actor shall be stored in the database. No Actor must exist with the DTO's user name in the database. If the create operation succeeds, this DTO will be cleared of all data!

Returns:

The Actor that was newly created based on the given DTO.

Throws:

PasswordNotConfirmedException - If the LocalActorCreatedByAdminDTO.repeatedPassword does not match the LocalActorCreatedByAdminDTO.password.

UnauthorisedException - If end user making the request is not permitted to create Actors with the ActorRole that the given DTO has. (Includes the case that the end user is not permitted to create end users at all.)

AlreadyExistsException - If an Actor with the DTO's user name is already present in the database.

de.gustavblass.commons.exceptions.IllegalArgumentException - If no LocalActorCreatedByAdminDTO.password is set.

deleteActor

@PreAuthorize("hasRole('FACULTY_ADMINISTRATION')")
public void deleteActor(@NonNull
 @NonNull String userName)
                 throws NotFoundException,
ActorStillHasReservationsException,
UnauthorisedException

Removes the Actor with the given Actor.userName from the database.

The Actor on whose behalf this method is called must have sufficient privilege to delete Actors with the ActorRole that the Actor concerned has.

The Actor to be deleted must not still have active Reservations that begin or end after the current time.

Parameters:

userName - The user name of the user that shall no longer be present in the system.

Throws:

NotFoundException - If there is no Actor with the given user name.

UnauthorisedException - If end user making the request is not permitted to delete Actors with the ActorRole that the Actor concerned has.

ActorStillHasReservationsException - If the Actor still has Reservations.

register

public void register(@NonNull
 @NonNull LocalRegistrationActorDTO localRegistrationActorDTO)
              throws AlreadyExistsException,
PasswordNotConfirmedException,
IllegalStateException,
InvalidOrBannedEMailAddressException

Creates a new Actor in the database, according to the given LocalRegistrationActorDTO. Generates a new VerificationToken for the Actor and publishes a new UnconfirmedRegistrationEvent.

Parameters:

localRegistrationActorDTO - The new user.

Throws:

PasswordNotConfirmedException - If the LocalActorCreatedByAdminDTO.repeatedPassword does not match the LocalActorCreatedByAdminDTO.password.

AlreadyExistsException - If the ActorCreatedByAdminDTO.userName already exists in the database.

InvalidOrBannedEMailAddressException - If the ActorCreatedByAdminDTO.eMailAddress is invalid or banned.

IllegalStateException - If local registrations are disabled.

Implementation Note:

This method takes a DTO and not a proper object, because this is the easiest way to validate that the two passwords entered match each other.

register

public void register(@NonNull
 @NonNull LdapRegistrationActorDTO ldapRegistrationActorDTO)
              throws IllegalStateException,
AlreadyExistsException,
de.gustavblass.commons.exceptions.IllegalArgumentException

Creates a new Actor in the database, according to the given LdapRegistrationActorDTO. The LdapRegistrationActorDTO.password is not stored in the database; it will be verified against an LDAP server during every login process.

Parameters:

ldapRegistrationActorDTO - The new Actor. Must exist at the LDAP server configured in the ldapAuthenticationProvider. The Actor.userName must not be taken already.

Throws:

IllegalStateException - If LDAP is not configured. See initialiseLdap().

AlreadyExistsException - If the user name is already taken.

de.gustavblass.commons.exceptions.IllegalArgumentException - If the login credentials are invalid.

enableAccount

@NonNull
public @NonNull Actor enableAccount(@NonNull
 @NonNull String verificationToken)
                             throws NotFoundException,
ExpiredException,
AccountIsLockedException

Sets Actor.enabled to true for the VerificationToken.actor belonging to the given VerificationToken.token. Deletes the VerificationToken from the database in case of success.

Parameters:

verificationToken - The token through which the Actor confirms their registration.

Returns:

The Actor whose VerificationToken was used.

Throws:

NotFoundException - If the given verification token is not present in the database.

ExpiredException - If the verification token exists in the database but has expired.

AccountIsLockedException -

If the

invalid reference

Actor#isLocked()

.

changePassword

@PreAuthorize("isAuthenticated()")
public void changePassword(@NonNull
 @NonNull ChangePasswordDTO changePasswordDTO)
                    throws NotLoggedInException,
WrongPasswordException,
PasswordNotConfirmedException,
NotALocalUserException

Sets the Actor.password() of the CurrentAuthorityService.getActor() (who must be a LocalActor) to hash of the given ChangePasswordDTO.newPassword.

Parameters:

changePasswordDTO - The current and new password. ChangePasswordDTO.currentPassword must match the one stored in the database before the change operation. ChangePasswordDTO.newPassword() and ChangePasswordDTO.repeatedNewPassword must match.

Throws:

NotLoggedInException - If the current end user is not authenticated. Should never happen, thanks to the @PreAuthorize annotation.

WrongPasswordException - If the current password is incorrect.

PasswordNotConfirmedException - If the new password was not repeated correctly.

NotALocalUserException - If the Actor is not a LocalActor.

changeUserName

@PreAuthorize("isFullyAuthenticated()")
public void changeUserName(@NonNull
 @NonNull String newUserName)
                    throws de.gustavblass.commons.exceptions.IllegalArgumentException,
NotLoggedInException,
NotALocalUserException,
NoDifferenceException,
AlreadyExistsException

Updates the Actor.userName of the current user.

Parameters:

newUserName - The new user name that shall replace the old one. Must not be already taken. Must not be blank. Must not match the current one.

Throws:

NotLoggedInException - If the user is not authenticated.

NotALocalUserException - If the user is not a LocalActor.

NoDifferenceException - If the new user name matches the old one.

AlreadyExistsException - If a different Actor already occupies the given new user name.

de.gustavblass.commons.exceptions.IllegalArgumentException - If the given new user name is blank.

changeName

@PreAuthorize("isFullyAuthenticated()")
public void changeName(@NonNull
 @NonNull String newName)
                throws de.gustavblass.commons.exceptions.IllegalArgumentException,
NotLoggedInException,
NotALocalUserException,
NoDifferenceException

Updates the Actor.name of the current user.

Parameters:

newName - The new name that shall replace the old one. Must not be blank. Must not match the current one.

Throws:

NotLoggedInException - If the user is not authenticated.

NotALocalUserException - If the user is not a LocalActor.

NoDifferenceException - If the new name matches the old one.

de.gustavblass.commons.exceptions.IllegalArgumentException - If the given new name is blank.

changeEMailAddress

@PreAuthorize("isFullyAuthenticated()")
public void changeEMailAddress(@NonNull
 @NonNull String newEMailAddress)
                        throws InvalidOrBannedEMailAddressException,
NotLoggedInException,
NotALocalUserException,
NoDifferenceException,
AlreadyExistsException

Stores a new EMailVerificationToken with the given EMailVerificationToken.eMailAddress in the database, in order to allow an Actor to change their Actor.eMailAddress by opening a confirmation link that will be sent by e-mail.

Publishes a new EMailChangeEvent with the current actor as the EMailChangeEvent.EMailChange.actor, the given e-mail address as the EMailChangeEvent.EMailChange.newEmail and the newly created EMailVerificationToken as the [EMailChangeEvent.EMailChange.verificationToken].

Parameters:

newEMailAddress - The user wants to change their e-mail address to this value. Must be valid and allowed.

Throws:

NotLoggedInException - If the user is not authenticated.

NotALocalUserException - If the Actor is not a LocalActor.

NoDifferenceException - If the given new address matches the current one.

AlreadyExistsException - If there already is an EMailVerificationToken for the Actor in the database. Can be any token for any new e-mail address value.

InvalidOrBannedEMailAddressException - If the given new address is invalid or disallowed.

confirmNewEMail

@PreAuthorize("isFullyAuthenticated()")
@NonNull
public @NonNull Actor confirmNewEMail(@NonNull
 @NonNull String verificationToken)
                               throws NotFoundException,
ExpiredException,
AccountIsLockedException,
IllegalStateException,
NotLoggedInException

Changes the Actor.eMailAddress of the VerificationToken.actor to the new EMailVerificationToken.eMailAddress.

Parameters:

verificationToken - The VerificationToken.token. The EMailVerificationToken must belong to the current user.

Returns:

The VerificationToken.actor.

Throws:

NotLoggedInException - If the current user not authenticated.

NotFoundException - If there is no EMailVerificationToken in the database where the token matches the given one and where the VerificationToken.actor matches the currently logged-in Actor.

ExpiredException - If the token is no longer valid.

AccountIsLockedException -

If the

invalid reference

Actor#isLocked()

.

IllegalStateException - If the new e-mail address is not stored in the database.

onRegistration

@EventListener
public void onRegistration(@NonNull
 @NonNull ActorCreatedEvent createdEvent)

Saves the registration date of the given ActorCreatedEvent to the ActorMetadata belonging to the ActorCreatedEvent.actor.

Parameters:

createdEvent - The registration event indicating the user that was newly created.

onLogin

@EventListener
public void onLogin(@NonNull
 @NonNull org.springframework.security.authentication.event.AuthenticationSuccessEvent success)
             throws de.gustavblass.commons.exceptions.IllegalArgumentException

Updates the ActorMetadata.lastLogin of the Actor of the given AuthenticationSuccessEvent.

Parameters:

success - The login success event.

Throws:

de.gustavblass.commons.exceptions.IllegalArgumentException - If the Authentication.getPrincipal() of the given success event is not an Actor.

Implementation Note:

Uses the actorMetadataRepository and not ActorRepository.save(Actor), because the authentication principal stored in the success event lacks the Actor.password() and possibly other attributes as well. Saving the Actor would therefore delete possibly relevant data. It is far easier and less risky to just store the metadata itself.