DOCSEARCHbyAlgolia
Submit Docs

googleauth

repository·master·Indexed 22 days ago

https://github.com/wstrange/googleauth

A Java server-side library implementing the Time-based One-time Password (TOTP) algorithm (RFC 6238). It provides tools for secret generation, verification, and credential storage integration via the ICredentialRepository interface to help developers add multi-factor authentication to Java applications.

Tokens
1.2K
Snippets
4
Records
5
Agent score
28%

What's inside googleauth

  1. Understand Scratch Codes

    master

    By default, createCredentials() generates 5 scratch codes along with the shared secret. Scratch codes serve as a safety net for users who lose access to their primary token device.

    Note: Scratch codes are not part of the TOTP standard. Their implementation and usage are entirely up to the developer.

  2. Create and verify TOTP credentials

    master

    To implement TOTP multi-factor authentication, follow these steps:

    1. Create Credentials: Use GoogleAuthenticator.createCredentials() to generate a new set of credentials. This returns a GoogleAuthenticatorKey object.
    2. Share Secret: Provide the user with the shared secret obtained via key.getKey(). This secret is used to configure their token device (e.g., Google Authenticator app).
    3. Verify Password: When the user provides a TOTP password, verify it using gAuth.authorize(secretKey, password).

    Note on Defaults: By default, the library expects a 6-digit integer that changes every 30 seconds. While password length and validity windows can be customized, many standard client apps (like Google Authenticator) do not support customization and rely on these defaults.

    // 1. Create credentials
GoogleAuthenticator gAuth = new GoogleAuthenticator();
final GoogleAuthenticatorKey key = gAuth.createCredentials();

// 2. Get the secret to give to the user
String secretKey = key.getKey();

// 3. Later, verify a password provided by the user
boolean isCodeValid = gAuth.authorize(secretKey, password);

  3. Install GoogleAuth via Maven or Gradle

    master

    Add the googleauth dependency to your build configuration. The library automatically pulls in Apache Commons Codec and Apache HTTP client as required dependencies.

    Requirements:

    • Minimum Java version: Java 7.
    ### Maven
<dependency>
  <groupId>com.warrenstrange</groupId>
  <artifactId>googleauth</artifactId>
  <version>1.4.0</version>
</dependency>

### Gradle
compile 'com.warrenstrange:googleauth:1.4.0'

  4. Use GoogleAuth as a software client

    master

    You can use the library to generate TOTP codes programmatically. This is useful for testing or for building a custom software-based token application that acts as an alternative to the Google Authenticator app.

    GoogleAuthenticator gAuth = new GoogleAuthenticator();
int code = gAuth.getTotpPassword(secretKey);

  5. Implement ICredentialRepository to manage user credentials

    master

    The library provides the ICredentialRepository interface to bridge the gap between the library and your application's user storage. This allows you to use user names directly in API calls instead of manually passing secret keys.

    Implementation Requirements

    You must implement two methods in your ICredentialRepository implementation:

    1. String getSecretKey(String userName)
    2. void saveUserCredentials(String userName, ...)

    Registering the Repository

    You can register your repository in two ways:

    1. Per-instance: Use the credentialRepository property on the IGoogleAuthenticator interface.
    2. ServiceLoader: Place a file named com.warrenstrange.googleauth.ICredentialRepository in the META-INF/services package containing the fully qualified name of your provider class.

    Usage with Repository

    Once configured, you can use user-centric methods:

    • createCredentials(userName): Creates credentials and automatically saves them via the repository.
    • authorizeUser(userName, code): Retrieves the secret key for the user from the repository and validates the code.
    // Setup with a repository
GoogleAuthenticator gAuth = new GoogleAuthenticator();
// (Assuming repository is configured via ServiceLoader or property)

// Create and store credentials for 'Bob'
final GoogleAuthenticatorKey key = gAuth.createCredentials("Bob");

// Verify a code for 'Bob'
boolean isCodeValid = gAuth.authorizeUser("Bob", code);