com.atlassian.crowd.emailchange

Interface EmailChangeManager

public interface EmailChangeManager

Used to change e-mail of a user in a way that they need to prove that they have access to the e-mail they're trying to change to. This is achieved by sending an e-mail message containing a secret. Only and only if a user is able to bring the secret back to Crowd their e-mail is being changed.

Since:

4.4.0

Method Summary

Modifier and Type	Method and Description
void	abort(String username, long directoryId) Aborts a pending e-mail validation for a given user in crowd app.
void	changeEmail(String token, String username) Changes e-mail for a user in crowd app.
String	getPendingNewEmailByToken(String token) Returns new e-mail address for a e-mail change token.
String	getPendingNewEmailByUser(String username, long directoryId) Returns new e-mail address for a user in crowd app for whom there's a pending e-mail verification.
boolean	hasUserEmailChangePending(String username, long directoryId) Returns true if there is a pending e-mail verification for a user in crowd app, false otherwise.
boolean	isAvailableForDirectory(long dirId) Returns true if e-mail change by end-user feature is available for a given directory.
boolean	isTokenValid(String token) Returns true if a given token is a valid e-mail change verification token.
void	resendEmail(String username, long directoryId) Resends an e-mail with a new token for a user in crowd app that has a pending e-mail verification.
void	sendEmailAuthorization(String username, String password, long directoryId, String newEmail) Starts e-mail change flow for a user in crowd app, by sending two e-mails.

Method Detail

sendEmailAuthorization

void sendEmailAuthorization(String username,
                            String password,
                            long directoryId,
                            String newEmail)
                     throws com.atlassian.crowd.exception.InvalidAuthenticationException,
                            com.atlassian.crowd.exception.InvalidEmailAddressException,
                            MailSendException,
                            com.atlassian.crowd.exception.OperationNotPermittedException,
                            com.atlassian.crowd.exception.ApplicationNotFoundException,
                            SameEmailAddressException

Starts e-mail change flow for a user in crowd app, by sending two e-mails. First one to the current user's e-mail and the second one to the newEmail. The first one contains info for an ongoing e-mail change. The second one contains a link with a token which is required to change an e-mail. In order to do change an e-mail, changeEmail(java.lang.String, java.lang.String) needs to be called with the aforementioned token passed as an argument.

Parameters:

username - username of the user for whom we're changing an e-mail

password - password of the user for whom we're changing an e-mail

directoryId - directory ID of the user for whom we're changing an e-mail

newEmail - e-mail to which we'll replace an old email of the user

Throws:

com.atlassian.crowd.exception.InvalidAuthenticationException - if authentication fails for given username and password

com.atlassian.crowd.exception.InvalidEmailAddressException - if passed newEmail is not a valid e-mail address

SameEmailAddressException - if passed newEmail is the same as the one currently used by a user

MailSendException - if Crowd failed to send e-mail with a token

com.atlassian.crowd.exception.OperationNotPermittedException - if feature is not available

com.atlassian.crowd.exception.ApplicationNotFoundException - if 'crowd' app has not been found

changeEmail

void changeEmail(String token,
                 String username)
          throws InvalidChangeEmailTokenException,
                 com.atlassian.crowd.exception.InvalidAuthenticationException,
                 com.atlassian.crowd.exception.UserNotFoundException,
                 com.atlassian.crowd.exception.OperationFailedException,
                 com.atlassian.crowd.exception.ApplicationNotFoundException,
                 com.atlassian.crowd.exception.OperationNotPermittedException

Changes e-mail for a user in crowd app.

This method SHALL only be called after calling sendEmailAuthorization(java.lang.String, java.lang.String, long, java.lang.String).

Parameters:

token - token sent in email by sendEmailAuthorization(java.lang.String, java.lang.String, long, java.lang.String)

username - username of the user for whom we're changing an e-mail

Throws:

InvalidChangeEmailTokenException - if provide token is not valid

com.atlassian.crowd.exception.InvalidAuthenticationException - if user identified by username is not the one who generated a token

com.atlassian.crowd.exception.UserNotFoundException - if user does not exist

com.atlassian.crowd.exception.OperationFailedException - if Crowd failed to update e-mail

com.atlassian.crowd.exception.ApplicationNotFoundException - if 'crowd' app has not been found

com.atlassian.crowd.exception.OperationNotPermittedException - if feature is not available

hasUserEmailChangePending

boolean hasUserEmailChangePending(String username,
                                  long directoryId)

Returns true if there is a pending e-mail verification for a user in crowd app, false otherwise.

Parameters:

username - username of the user

directoryId - directory ID of the user

Returns:

true if there is a pending e-mail verification for a user, false otherwise

getPendingNewEmailByUser

String getPendingNewEmailByUser(String username,
                                long directoryId)

Returns new e-mail address for a user in crowd app for whom there's a pending e-mail verification.

Parameters:

username - username of the user

directoryId - directory ID of the user

Returns:

new e-mail address

Throws:

IllegalStateException - if user does not have a pending e-mail validation

getPendingNewEmailByToken

String getPendingNewEmailByToken(String token)

Returns new e-mail address for a e-mail change token.

Parameters:

token - e-mail change token

Returns:

new e-mail address

Throws:

IllegalStateException - if user does not have a pending e-mail validation

resendEmail

void resendEmail(String username,
                 long directoryId)
          throws com.atlassian.crowd.exception.InvalidEmailAddressException,
                 MailSendException,
                 com.atlassian.crowd.exception.UserNotFoundException,
                 com.atlassian.crowd.exception.ApplicationNotFoundException

Resends an e-mail with a new token for a user in crowd app that has a pending e-mail verification. Old token is invalidated.

Parameters:

username - of the user

directoryId - directory ID of the user

Throws:

IllegalStateException - if user does not have a pending e-mail validation

com.atlassian.crowd.exception.InvalidEmailAddressException - if pending e-mail address is not a valid e-mail address

MailSendException - if Crowd failed to re-send e-mail with a token

com.atlassian.crowd.exception.UserNotFoundException - if user does not exist

com.atlassian.crowd.exception.ApplicationNotFoundException - if 'crowd' app has not been found

abort

void abort(String username,
           long directoryId)

Aborts a pending e-mail validation for a given user in crowd app.

Parameters:

username - username of the user

directoryId - directory ID of the user

Throws:

IllegalStateException - if user does not have a pending e-mail validation

isTokenValid

boolean isTokenValid(String token)

Returns true if a given token is a valid e-mail change verification token. False otherwise.

Parameters:

token - e-mail change token

Returns:

true if a given token is a valid e-mail change verification token, false otherwise

isAvailableForDirectory

boolean isAvailableForDirectory(long dirId)

Returns true if e-mail change by end-user feature is available for a given directory. False otherwise.

Feature might be disabled for a given directory because: - Crowd's e-mail server is NOT configured - Directory does not have permissions to change user e-mail

Parameters:

dirId - ID of the directory

Returns:

true if e-mail change by end-user feature is available for a given directory, false otherwise.