{"id":13740564,"url":"https://github.com/wstrange/GoogleAuth","last_synced_at":"2025-05-08T20:31:55.665Z","repository":{"id":2199763,"uuid":"3148173","full_name":"wstrange/GoogleAuth","owner":"wstrange","description":"Google Authenticator Server side code","archived":false,"fork":false,"pushed_at":"2025-01-03T22:36:31.000Z","size":371,"stargazers_count":1052,"open_issues_count":11,"forks_count":332,"subscribers_count":77,"default_branch":"master","last_synced_at":"2025-01-03T23:27:04.671Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wstrange.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2012-01-10T20:06:54.000Z","updated_at":"2025-01-03T22:36:35.000Z","dependencies_parsed_at":"2022-08-10T09:02:27.965Z","dependency_job_id":null,"html_url":"https://github.com/wstrange/GoogleAuth","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wstrange%2FGoogleAuth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wstrange%2FGoogleAuth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wstrange%2FGoogleAuth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wstrange%2FGoogleAuth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wstrange","download_url":"https://codeload.github.com/wstrange/GoogleAuth/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253144876,"owners_count":21861141,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T04:00:49.831Z","updated_at":"2025-05-08T20:31:55.325Z","avatar_url":"https://github.com/wstrange.png","language":"Java","funding_links":[],"categories":["Authorization","Java","安全","Authorization Development"],"sub_categories":["\u003ca name=\"authZ-java\"\u003e\u003c/a\u003eJava"],"readme":"[![Build Status](https://travis-ci.org/wstrange/GoogleAuth.svg?branch=develop)](https://travis-ci.org/wstrange/GoogleAuth)\n[![License](https://img.shields.io/badge/license-BSD-blue.svg?style=flat)](https://github.com/wstrange/GoogleAuth/blob/master/LICENSE)\n\nREADME\n======\n\nGoogleAuth is a Java server library that implements the _Time-based One-time\nPassword_ (TOTP) algorithm specified in [RFC 6238][RFC6238].\n\nThis implementation borrows from [Google Authenticator][gauth], whose C code has\nserved as a reference, and was created upon code published in [this blog\npost][tgb] by Enrico M. Crisostomo.\n\n\nWhom Is This Library For\n------------------------\n\nAny developer who wants to add TOTP multi-factor authentication to a Java\napplication and needs the server-side code to create TOTP shared secrets,\ngenerate and verify TOTP passwords.\n\nUsers may use TOTP-compliant token devices (such as those you get from your\nbank), or a software-based token application (such as Google Authenticator).\n\nRequirements\n------------\n\nThe minimum Java version required to build and use this library is Java 7.\n\nInstalling\n----------\n\nAdd a dependency to your build environment.\n\nIf you are using Maven:\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.warrenstrange\u003c/groupId\u003e\n      \u003cartifactId\u003egoogleauth\u003c/artifactId\u003e\n      \u003cversion\u003e1.4.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\nIf you are using Gradle:\n\n     compile 'com.warrenstrange:googleauth:1.4.0'\n\nThe required libraries will be automatically pulled into your project:\n\n  * Apache Commons Codec.\n  * Apache HTTP client.\n\nClient Applications\n-------------------\n\nBoth the Google Authenticator client applications (available for iOS, Android\nand BlackBerry) and its PAM module can be used to generate codes to be validated\nby this library.\n\nHowever, this library can also be used to build custom client applications if\nGoogle Authenticator is not available on your platform or if it cannot be used.\n\nLibrary Documentation\n---------------------\n\nThis library includes full JavaDoc documentation and a JUnit test suite that can\nbe used as example code for most of the library purposes.\n\nTexinfo documentation sources are also included and a PDF manual can be\ngenerated by an Autotools-generated `Makefile`:\n\n  * To bootstrap the Autotools, the included `autogen.sh` script can be used.\n\n        $ ./autogen.sh\n\n  * Configure and build the documentation:\n\n        $ ./configure\n        $ make pdf\n\nSince typical users will not have a TeX distribution installed in their\ncomputers, the PDF manuals for every version of GoogleAuth are hosted at\n[this address][pdfdoc].\n\nUsage\n-----\n\nThe following code creates a new set of credentials for a user.  No user name is\nprovided to the API and it is a responsibility of the caller to save it for\nlater use during the authorisation phase.\n\n    GoogleAuthenticator gAuth = new GoogleAuthenticator();\n    final GoogleAuthenticatorKey key = gAuth.createCredentials();\n\nThe user should be given the value of the _shared secret_, returned by\n\n    key.getKey()\n\nso that the new account can be configured into its token device.  A convenience\nmethod is provided to easily encode the secret key and the account information\ninto a QRcode.\n\nWhen a user wishes to log in, he will provide the TOTP password generated by his\ndevice.  By default, a TOTP password is a 6 digit integer that changes every 30\nseconds.  Both the password length and its validity can be changed.  However,\nmany token devices such as Google Authenticator use the default values specified\nby the TOTP standard and they do not allow for any customization.\n\nThe following code checks the validity of the specified `password` against the\nprovided Base32-encoded `secretKey`:\n\n    GoogleAuthenticator gAuth = new GoogleAuthenticator();\n    boolean isCodeValid = gAuth.authorize(secretKey, password);\n\nSince TOTP passwords are time-based, it is essential that the clock of both the\nserver and the client are synchronised within the tolerance used by the\nlibrary.  The tolerance is set by default to a window of size 3 and can be\noverridden when configuring a `GoogleAuthenticator` instance.\n\nClient\n------\n\nThis library can generate TOTP codes for testing or for use as a software-based\nclient.\n\n    GoogleAuthenticator gAuth = new GoogleAuthenticator();\n    int code = gAuth.getTotpPassword(secretKey);\n    \nThe codes generated in this way can be used as an alternative to the codes that \nwould be generated by the Google Authenticator App (or other client device).\n\nScratch codes\n-------------\n\nBy default 5 scratch codes are generated together with a new shared secret.\nScratch codes are meant to be a safety net in case a user loses access to their\ntoken device.  Scratch nodes are _not_ a functionality required by the TOTP\nstandard and it is up to the developer to decide whether they should be used in\nhis application.\n\nStoring User Credentials\n------------------------\n\nThe library can assist with fetching and storing user credentials and a hook is\nprovided to users who want to integrate this functionality.  The\n*ICredentialRepository* interface defines the contract between a credential\nrepository and this library.\n\nThe credential repository can be set in multiple ways:\n\n  * The credential repository can be set on a per-instance basis, using the\n  `credentialRepository` property of the `IGoogleAuthenticator` interface.\n\n  * The library looks for instances of this interface using the\n    [Java ServiceLoader API][serviceLoader] (introduced in Java 6), that is,\n    scanning the `META-INF/services` package looking for a file named\n    `com.warrenstrange.googleauth.ICredentialRepository` and, if found, loading\n    the provider classes listed therein.\n\nTwo methods needs to be implemented in the *ICredentialRepository* interface.\n\n  * `String getSecretKey(String userName)`.\n  * `void saveUserCredentials(String userName, ...)`.\n\nThe credentials repository establishes the relationship between a user _name_\nand its credentials.  This way, API methods receiving only a user name instead\nof credentials can be used.\n\nThe following code creates a new set of credentials for the user `Bob` and\nstores them on the configured `ICredentialRepository` instance:\n\n    GoogleAuthenticator gAuth = new GoogleAuthenticator();\n    final GoogleAuthenticatorKey key = gAuth.createCredentials(\"Bob\");\n\n\nThe following code checks the validity of the specified `code` against the\nsecret key of the user `Bob` returned by the configured\n`ICredentialRepository` instance:\n\n    GoogleAuthenticator gAuth = new GoogleAuthenticator();\n    boolean isCodeValid = gAuth.authorizeUser(\"Bob\", code);\n\n\nIf an attempt is made to use such methods when no credential repository is\nconfigured, an exception is thrown:\n\n    java.lang.UnsupportedOperationException: An instance of the\n      com.warrenstrange.googleauth.ICredentialRepository service must be\n      configured in order to use this feature.\n\nBug Reports\n-----------\n\nPlease, [read the manual][pdfdoc] before opening a ticket.  If you have read the\nmanual and you still think the behaviour you are observing is a bug, then open a\nticket on [github][githubIssues].\n\n----\n\nCopyright (c) 2013 Warren Strange\n\nCopyright (c) 2014-2019 Enrico M. Crisostomo\n\nAll rights reserved.\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n* Redistributions of source code must retain the above copyright notice, this\n  list of conditions and the following disclaimer.\n\n* Redistributions in binary form must reproduce the above copyright notice,\n  this list of conditions and the following disclaimer in the documentation\n  and/or other materials provided with the distribution.\n\n* Neither the name of the author nor the names of its\n  contributors may be used to endorse or promote products derived from\n  this software without specific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE\nDISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE\nFOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\nDAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR\nSERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER\nCAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,\nOR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE\nOF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[RFC6238]: https://tools.ietf.org/html/rfc6238\n[gauth]: https://code.google.com/p/google-authenticator/\n[tgb]: http://thegreyblog.blogspot.com/2011/12/google-authenticator-using-it-in-your.html?q=google+authenticator\n[serviceLoader]: http://docs.oracle.com/javase/6/docs/api/java/util/ServiceLoader.html\n[SecureRandom]: http://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html\n[sr-algorithms]: http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#SecureRandom\n[githubIssues]: https://github.com/wstrange/GoogleAuth/issues\n[pdfdoc]: https://drive.google.com/folderview?id=0BxZtP9CHH-Q6TzRSaWtkQ0pEYk0\u0026usp=sharing\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwstrange%2FGoogleAuth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwstrange%2FGoogleAuth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwstrange%2FGoogleAuth/lists"}