Skip to content

Latest commit

 

History

History
106 lines (76 loc) · 4.21 KB

README.md

File metadata and controls

106 lines (76 loc) · 4.21 KB
Raw

README

GoogleAuth is a Java server library that implements the Time-based One-time Password (TOTP) algorithm specified in RFC 6238.

This implementation borrows from Google Authenticator, whose C code has served as a reference, and was created upon code published in this blog post by Enrico M. Crisostomo.

Storing User Credentials

The library does not store nor load user credentials directly, and a hook is provided to users who want to integrate this functionality. The ICredentialRepository interface defines the contract between a credential repository and this library and a custom implementation can be plugged in and used by the library as a user-provided credential repository.

The following methods take a user name as a parameter and require a credential repository to be available:

  • String getSecretKey(String userName).
  • void saveUserCredentials(String userName, ...).

The credentials repository establishes the relationship between a user name and its credentials. This way, API methods receiving only a user name instead of credentials can be used:

  • public GoogleAuthenticatorKey createCredentials(String userName).
  • boolean authorizeUser(String userName, ...).

If an attempt is made to use such methods when no credential repository is configured, a meaningful error is emitted:

java.lang.UnsupportedOperationException: An instance of the
com.warrenstrange.googleauth.ICredentialRepository service must be
configured in order to use this feature.

Registering a Credential Repository

The library looks for instances of this interface using the Java ServiceLoader API (introduced in Java 6), that is, scanning the META-INF/services package looking for a file named com.warrenstrange.googleauth.ICredentialRepository and, if found, loading the provider classes listed therein.

Client Applications

Both the Google Authenticator client applications (available for iOS, Android and BlackBerry) and its PAM module can be used to generate codes to be validated by this library.

However, this library can also be used to build custom client applications if Google Authenticator is not available on your platform or if it cannot be used.

Library Documentation

This library includes full JavaDoc documentation and a JUnit test suite that can be used as example code for most of the library purposes.

Usage

The following code creates a new set of credentials for a user. No user name is provided to the API and it's responsibility of the caller to save them for later use during the authorisation phase.

GoogleAuthenticator gAuth = new GoogleAuthenticator();
final GoogleAuthenticatorKey key = gAuth.createCredentials();

The following code creates a new set of credentials for the user caller and stores them on the configured ICredentialRepository instance:

GoogleAuthenticator gAuth = new GoogleAuthenticator();
final GoogleAuthenticatorKey key = gAuth.createCredentials("caller");

If a credential repository is not configured the code will fail throwing an UnsupportedOperationException.

The following code checks the validity of the specified code against the provided Base32-encoded secretKey:

GoogleAuthenticator gAuth = new GoogleAuthenticator();
boolean isCodeValid = gAuth.authorize(secretKey, code);

The following code checks the validity of the specified code against the secret key of the user caller returned by the configured ICredentialRepository instance:

GoogleAuthenticator gAuth = new GoogleAuthenticator();
boolean isCodeValid = ga.authorizeUser("caller", code);

Bug Reports

Bug reports can be sent directly to the authors.