AuthUtils.java

/***************************************************************************
   Copyright 2014 Emily Estes

   Licensed under the Apache License, Version 2.0 (the "License");
   you may not use this file except in compliance with the License.
   You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
***************************************************************************/
package net.metanotion.authident;


import net.metanotion.util.EventCalculator;
import net.metanotion.util.EventHandler;
import net.metanotion.util.SecureString;
import net.metanotion.util.State;
import net.metanotion.util.StateMachine;

/** This class implements some utilities that code using the auth-ident package may find helpful. */
public final class AuthUtils {
	/** Run credentials through an AuthPassword instance. If the credentials are accepted this method sends a UserToken
	event to the state machine and returns true. Otherwise it returns false. No matter what happens, it closes the
	secure string containing the password.
		@param pw The AuthPassword instance to check the credentials.
		@param sm The state machine that receives authentication events.
		@param username The username part of the credential to authenticate.
		@param password The password part of the credential to authenticate. This will be erased before this method
			returns.
		@return True if the authentication was successful, false otherwise.
	*/
	public static boolean externalAuthenticate(final AuthPassword<? extends AuthPassword> pw,
			final StateMachine sm,
			final String username,
			final SecureString password) {
		try {
			final UserToken ut = pw.authenticate(username, password);
			if(ut != null) {
				sm.nextState(ut);
				return true;
			}
		} catch (final RuntimeException re) {
		} finally {
			if(password != null) { password.close(); }
		}
		return false;
	}

	/** Determine if a username/password pair authenticates to the same identity as the user query interface provides.
		@param pw The AuthPassword instance to check the credentials.
		@param ut The user token for the currently authenticated user (to compare the authentication attempt against).
		@param username A username credential to authenticate.
		@param password A password credential to authenticate.
		@return True if the identities match, false otherwise.
	*/
	public static boolean checkAuthenticatedIdentityMatches(final AuthPassword pw,
			final UserToken ut,
			final String username,
			final SecureString password) {
		try {
			final CredentialedUserToken aut = pw.authenticate(username, password);
			if((aut != null) && (aut.getID() == ut.getID())) { return true; }
		} catch (final RuntimeException re) {
		} finally {
			if(password != null) { password.close(); }
		}
		return false;
	}

	/** Attempt to lookup a username for a given account. If the token  comes with a credential, use that one,
		otherwise return the first username we find from the AuthPassword implementation provided.
		@param ut The user token to find a username.
		@param pw A password authentication service.
		@return A username for the account given, null if there is no username associated with the account.
	*/
	public static String lookupUsername(final AuthPassword<? extends AuthPassword> pw, final UserToken ut) {
		if(ut instanceof CredentialedUserToken) { return ((CredentialedUserToken) ut).getCredential().toString(); }
		for(final String n: pw.listUsernames(ut)) { return n; }
		return null;
	}

	/** Attach event handlers for auth events to a event calculator.
		When a state machine receives an auth event, the event will either be an instance of net.metanotion.authident.UserToken
		or an instance of net.metanotion.formsauth.LogoutEvent. If an application is using the EventCalculator class
		standard handlers can be attached to the calculator for these login and logout events. This utility method
		provides a shortcut to attach these events to the calculator.
		@param c The event calculator to attach the handlers.
		@param login The event handler to deal with login/authentication events.
		@param logout The event handler to deal with logout events.
		@param <S> the type of the state class used by the application for it's event handlers.
	*/
	public static <S extends State> void addEvents(final EventCalculator<S> c,
			final EventHandler<S> login,
			final EventHandler<S> logout) {
		c.addHandler(UserToken.class, login);
		c.addHandler(LogoutEvent.class, logout);
	}
}