gr.iccs.isense.circ4life.rest.resources

Class AccessControlManager

java.lang.Object

gr.iccs.isense.circ4life.rest.resources.AccessControlManager

public class AccessControlManager
extends Object

Common Access Control Manager functionality.

All authentication and Authorization of the ICT Platform is implemented with the help of a Keycloak (https://www.keycloak.org/) server. The server is deployed at https://circ4life.iccs.gr/auth/ and automatically handles all integrated applications. OpenID Connect (https://openid.net/connect/) is the methodology of the authentication and authorization.

OpenID Connect is an identity mechanism based on OAuth 2.0 protocol. The end users of a service (humans or applications) provide their credentials and a registered Client ID into a pre-defined Token endpoint in exchange of an Access Token. The Client ID is something the administrator of the Keycloak server has already setup and the credentials can be obtained the same way or with some kind of registration. With this triplet at hand, a user or an application program can gain authorization by exchanging them for an Access Token that allows access to protected resources by supplying the token along the resource request.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	AccessControlManager.AccessTokens Encapsulation of Access and Refresh tokens.
static class	AccessControlManager.LoginResult Encapsulation of login result.
static class	AccessControlManager.NotificationEmailType Email notification types enumeration.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ECOACCOUNTS_GROUP The group name of the Eco-account enabled users.
static String	ECOCREDITCALC_CLIENTID The client ID to use in order to login and access the Eco-credit calculator REST services.
static String	ENDUSERMODULE_CLIENTID The client ID to use in order to login and access the EndUserModule REST services.
static Logger	logger Logger.
static String	RECYCLEMODULE_CLIENTID The client ID to use in order to login and access the RecycleModule REST services.
static String	RETAILERMODULE_CLIENTID The client ID to use in order to login and access the RetailerModule REST services.
static int	UUIDLENGTH Keycloak default UUID length (as of version 4.8.3.Final).

Constructor Summary

Constructors

Constructor and Description
AccessControlManager()

Method Summary

Modifier and Type	Method and Description
static void	closeAdminAPIClient() Close the Access Control Manager Admin API client, logging out the user also.
static boolean	createEcoAccountUser(String username, String password, String email, String firstname, String lastname, String locale) Create an Eco-account enabled user in the Access Control Manager.
static AccessControlManager.LoginResult	ecoAccountLogin(String ClientID, String Username, String Password) Reverse proxy of getAccessTokens(String, String, String) that first checks if the user belongs to the Eco-accounts ACM group and has verified the registration email address.
static boolean	endSession(String ClientID, AccessControlManager.AccessTokens accessTokens) Perform a session logout on the Access Control Manager, using the corresponding Client ID and access/refresh tokens.
static boolean	existsGroupUUID(String groupuuid) Check if the specified group Universally Unique ID exists in the Access Control Manager.
static boolean	existsUserUUID(String useruuid) Check if the specified user Universally Unique ID exists in the Access Control Manager.
static AccessControlManager.AccessTokens	getAccessTokens(String ClientID, String Username, String Password) Perform a session login on the Access Control Manager and get the access/refresh tokens.
static String	getEmail(String useruuid) Retrieve a user's email address from Universally Unique ID.
static String	getEmailUUID(String email) Get the email's Universally Unique ID from the Access Control Manager.
static String	getGroupUUID(String group) Get the group's Universally Unique ID from the Access Control Manager.
static String	getPrincipalName(javax.ws.rs.core.SecurityContext securityContext) Get the user name from the specified SecurityContext.
static String	getUsername(String useruuid) Retrieve a user's username from Universally Unique ID.
static String	getUsernameUUID(String username) Get the username's Universally Unique ID from the Access Control Manager.
static boolean	isEnabled()
static boolean	isProperFormatUUID(String useruuid) Check the format and NOT THE EXISTENCE of the specified String against the specification of a user's UUID.
static boolean	isUserAuthenticated(javax.ws.rs.core.SecurityContext securityContext) Check if the specified SecurityContext contains an authenticated user.
static boolean	isUserEmailVerified(String useruuid) Check if the specified user has verified his email address.
static AccessControlManager.AccessTokens	refreshAccessTokens(String ClientID, AccessControlManager.AccessTokens accessTokens, boolean check_expiration) Perform a refresh of the access tokens, optionally check the expiration.
static boolean	removeEcoAccountUser(String useruuid) Remove the Eco-account enabled user from the Access Control Manager.
static boolean	sendNotificationEmail(String useruuid, AccessControlManager.NotificationEmailType emailtype) Send notification email to a registered user.
static boolean	sendResetPasswordEmail(String useruuid) Send the reset password email to a registered user, in order to change his password in case he forgot it.
static boolean	sendVerificationEmail(String useruuid) Send the verification email to a registered but not yet enabled user, in order to verify his email address and enable the account.
static boolean	setUserEmailVerified(String useruuid, boolean emailVerified) Set the email verification status of the specified user.
static boolean	updateEcoAccountUser(String useruuid, String password, String email, String firstname, String lastname, String locale) Update the user representation in the Access Control Manager.

Methods inherited from class java.lang.Object

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

Field Detail

logger

public static final Logger logger

Logger.

ECOCREDITCALC_CLIENTID

public static final String ECOCREDITCALC_CLIENTID

The client ID to use in order to login and access the Eco-credit calculator REST services.

See Also:

Constant Field Values

ENDUSERMODULE_CLIENTID

public static final String ENDUSERMODULE_CLIENTID

The client ID to use in order to login and access the EndUserModule REST services.

See Also:

Constant Field Values

RECYCLEMODULE_CLIENTID

public static final String RECYCLEMODULE_CLIENTID

The client ID to use in order to login and access the RecycleModule REST services.

See Also:

Constant Field Values

RETAILERMODULE_CLIENTID

public static final String RETAILERMODULE_CLIENTID

The client ID to use in order to login and access the RetailerModule REST services.

See Also:

Constant Field Values

UUIDLENGTH

public static final int UUIDLENGTH

Keycloak default UUID length (as of version 4.8.3.Final).

See Also:

Constant Field Values

ECOACCOUNTS_GROUP

public static final String ECOACCOUNTS_GROUP

The group name of the Eco-account enabled users.

See Also:

Constant Field Values

Constructor Detail

AccessControlManager

public AccessControlManager()

Method Detail

isEnabled

public static boolean isEnabled()

Returns:

true if Access Control Manager is enabled, false otherwise.

isUserAuthenticated

public static boolean isUserAuthenticated(javax.ws.rs.core.SecurityContext securityContext)

Check if the specified SecurityContext contains an authenticated user.

Parameters:

securityContext - the SecurityContext to check for user authentication.

Returns:

true if the user is authenticated and user name can be retrieved, false otherwise.

isUserEmailVerified

public static boolean isUserEmailVerified(String useruuid)

Check if the specified user has verified his email address.

Parameters:

useruuid - the user's Universally Unique ID.

Returns:

true if email address is verified, false otherwise.

setUserEmailVerified

public static boolean setUserEmailVerified(String useruuid,
                                           boolean emailVerified)

Set the email verification status of the specified user.

Parameters:

useruuid - the user's Universally Unique ID.

emailVerified - flag to denote if the email should be set as verified or not.

Returns:

true if set properly, false otherwise.

getPrincipalName

public static String getPrincipalName(javax.ws.rs.core.SecurityContext securityContext)

Get the user name from the specified SecurityContext.

Parameters:

securityContext - the SecurityContext.

Returns:

the user name as String if the SecurityContext has an authenticated user, null otherwise.

getUsernameUUID

public static String getUsernameUUID(String username)

Get the username's Universally Unique ID from the Access Control Manager.

Parameters:

username - the registered user's Access Control Manager username.

Returns:

the username's Universally Unique ID if username is valid, null otherwise.

getEmailUUID

public static String getEmailUUID(String email)

Get the email's Universally Unique ID from the Access Control Manager.

Parameters:

email - the registered user's Access Control Manager email.

Returns:

the email's Universally Unique ID if email is valid, null otherwise.

getGroupUUID

public static String getGroupUUID(String group)

Get the group's Universally Unique ID from the Access Control Manager.

Parameters:

group - the Access Control Manager group name.

Returns:

the group's Universally Unique ID if group is a valid name, null otherwise.

existsUserUUID

public static boolean existsUserUUID(String useruuid)

Check if the specified user Universally Unique ID exists in the Access Control Manager.

Parameters:

useruuid - the Universally Unique ID.

Returns:

true if exists, false otherwise.

existsGroupUUID

public static boolean existsGroupUUID(String groupuuid)

Check if the specified group Universally Unique ID exists in the Access Control Manager.

Parameters:

groupuuid - the Universally Unique ID.

Returns:

true if exists, false otherwise.

getEmail

public static String getEmail(String useruuid)

Retrieve a user's email address from Universally Unique ID.

Parameters:

useruuid - the Universally Unique ID.

Returns:

the email address as String if user exists and email can be retrieved, null otherwise.

getUsername

public static String getUsername(String useruuid)

Retrieve a user's username from Universally Unique ID.

Parameters:

useruuid - the Universally Unique ID.

Returns:

the username as String if user exists and username can be retrieved, null otherwise.

isProperFormatUUID

public static boolean isProperFormatUUID(String useruuid)

Check the format and NOT THE EXISTENCE of the specified String against the specification of a user's UUID. This can be used for quick testing without contacting the Access Control Manager, of whether the specified String could represent a user's UUID. For UUID existence, use existsUserUUID(String).

Parameters:

useruuid - the Universally Unique ID.

Returns:

true if the format is as expected, false otherwise.

ecoAccountLogin

public static AccessControlManager.LoginResult ecoAccountLogin(String ClientID,
                                                               String Username,
                                                               String Password)
                                                        throws IllegalArgumentException

Reverse proxy of getAccessTokens(String, String, String) that first checks if the user belongs to the Eco-accounts ACM group and has verified the registration email address.

Parameters:

ClientID - registered client ID on Access Control Manager.

Username - registered user name on Access Control Manager.

Password - registered user's password on Access Control Manager.

Returns:

an AccessControlManager.AccessTokens object filled with valid token from the Access Control Manager, or null on failure.

Throws:

IllegalArgumentException - if the provided ClientID or credentials are not recognized by the Access Control Manager.

getAccessTokens

public static AccessControlManager.AccessTokens getAccessTokens(String ClientID,
                                                                String Username,
                                                                String Password)
                                                         throws IllegalArgumentException

Perform a session login on the Access Control Manager and get the access/refresh tokens.

Parameters:

ClientID - registered client ID on Access Control Manager.

Username - registered user name on Access Control Manager.

Password - registered user's password on Access Control Manager.

Returns:

an AccessControlManager.AccessTokens object filled with valid token from the Access Control Manager, or null on failure.

Throws:

IllegalArgumentException - if the provided ClientID or credentials are not recognized by the Access Control Manager.

refreshAccessTokens

public static AccessControlManager.AccessTokens refreshAccessTokens(String ClientID,
                                                                    AccessControlManager.AccessTokens accessTokens,
                                                                    boolean check_expiration)

Perform a refresh of the access tokens, optionally check the expiration.

Parameters:

ClientID - registered client ID on Access Control Manager.

accessTokens - an AccessControlManager.AccessTokens object filled with valid token from the Access Control Manager that correspond to the session asked to end.

check_expiration - if true then check the expiration of the specified access tokens and only perform the refresh if they have expired.

Returns:

the rereshed access tokens on success, null otherwise.

endSession

public static boolean endSession(String ClientID,
                                 AccessControlManager.AccessTokens accessTokens)

Perform a session logout on the Access Control Manager, using the corresponding Client ID and access/refresh tokens.
CAUTION: This method performs a REQUEST to end the session, does not end the session even if true is returned. The responsible authority for this is the Access Control Manager, where all session handling is done. An HTTP 200 status code in the response indicates the proper acceptance of the request and if the Access Control Manager has no issue, the user session is then ended.

Parameters:

ClientID - registered client ID on Access Control Manager.

accessTokens - an AccessControlManager.AccessTokens object filled with valid token from the Access Control Manager that correspond to the session asked to end.

Returns:

true if the session end request is performed without errors, false otherwise.

closeAdminAPIClient

public static void closeAdminAPIClient()

Close the Access Control Manager Admin API client, logging out the user also.

createEcoAccountUser

public static boolean createEcoAccountUser(String username,
                                           String password,
                                           String email,
                                           String firstname,
                                           String lastname,
                                           String locale)

Create an Eco-account enabled user in the Access Control Manager. A verification email should be sent in order to fully enable the account. The account is by default enabled but not email verified after creation.

Parameters:

username - the username.

password - the password.

email - the email.

firstname - the user's real world first name.

lastname - the user's real world family name.

locale - ISO 639 alpha-2 language code for this locale. Supported values are configured in the ACM.

Returns:

true if the user account was created successfully, false otherwise.

sendVerificationEmail

public static boolean sendVerificationEmail(String useruuid)

Send the verification email to a registered but not yet enabled user, in order to verify his email address and enable the account.

Parameters:

useruuid - the user's Universally Unique ID.

Returns:

true if the user was found, he is not yet enabled and the email was sent successfully, false otherwise.

sendResetPasswordEmail

public static boolean sendResetPasswordEmail(String useruuid)

Send the reset password email to a registered user, in order to change his password in case he forgot it.

Parameters:

useruuid - the user's Universally Unique ID.

Returns:

true if the user was found and the email was sent successfully, false otherwise.

sendNotificationEmail

public static boolean sendNotificationEmail(String useruuid,
                                            AccessControlManager.NotificationEmailType emailtype)

Send notification email to a registered user.

Parameters:

useruuid - the user's Universally Unique ID.

emailtype - email notification type.

Returns:

true if the user was found and the email was sent successfully, false otherwise.

removeEcoAccountUser

public static boolean removeEcoAccountUser(String useruuid)

Remove the Eco-account enabled user from the Access Control Manager.

Parameters:

useruuid - the user's Universally Unique ID.

Returns:

true if the account removal was successful, false otherwise.

updateEcoAccountUser

public static boolean updateEcoAccountUser(String useruuid,
                                           String password,
                                           String email,
                                           String firstname,
                                           String lastname,
                                           String locale)

Update the user representation in the Access Control Manager. Only the input parameters that are not null are updated.

Parameters:

useruuid - the user's Universally Unique ID.

password - the updated password.

email - the updated email.

firstname - the updated user's real world first name.

lastname - the updated user's real world family name.

locale - ISO 639 alpha-2 language code for this locale. Supported values are configured in the ACM.

Returns:

true if the user account was updated successfully or no field was provided (no change required), false otherwise.