Metadata-Version: 1.1
Name: collective.googleauthenticator
Version: 0.1.1
Summary: Two-step verification for Plone 4 using the Google Authenticator app.
Home-page: https://github.com/collective/collective.googleauthenticator
Author: Goldmund, Wyldebeast & Wunderliebe
Author-email: info@gw20e.com
License: GPL 2.0
Description: ================================================
        collective.googleauthenticator
        ================================================
        Two-step verification (http://en.wikipedia.org/wiki/Two-step_verification) for Plone 4 with use
        of Google Authenticator app. This app allows users to enable the two-step verification for their
        Plone accounts. A mobile device with Google Authenticator app installed is required.
        
        Prerequiresites
        ================================================
        - GoogleAuthenticator app installed on mobile device (official app available for
          Android, iPhone and Blackberry; third-party app exists for Windows Phone
          http://www.windowsphone.com/en-us/store/app/authenticator/e7994dbc-2336-4950-91ba-ca22d653759b)
        - Plone 4 (tested with Plone >= 4.2.6)
        
        Usage
        ================================================
        Case 1: Enabling the two-step verification
        ------------------------------------------------
        Pre-conditions: User is not logged into the Plone site, does not yet have two-step verification
        enabled and has installed the Google Authenticator app (including the advised bar code scanner) on
        his mobile device.
        
        From "Personal information" page click the first of the two links under "Enable two-step
        verification".
        
        That will bring you to a page on which a bar code is shown.
        
        You're supposed to scan the bar code shown on the page using the bar code scanner installed on your
        mobile device, which you're going to use for verification.
        
        After you have successfully scanned the bar code, enter the token shown in the "Enter the
        verification code to activate two-step verification" field for confirmation and press the "Verify"
        button.
        
        Upon successful confirmation (you should see a message stating that) the two-step verification
        is enabled for your account.
        
        Case 2: Two-step verification
        ------------------------------------------------
        Pre-conditions: User is not logged in and has enabled the two-step verification.
        
        When you log into the Plone site (just using username and password), you would see an extra
        screen on which you are asked to provide the token, generated by Google Authenticator.
        
        You should then open the Google Authenticator app on your mobile device and type in the token
        shown into the "Enter code" field.
        
        If token is valid, you would be logged in.
        
        Case 3: Lost tokens
        ------------------------------------------------
        Pre-conditions: User is not logged in, has enabled the two-step verification.
        
        There might be cases when you have lost your token (either removed it from your app by accident
        or lost the mobile device). For such cases, you can reset the bar code.
        
        Log into the Plone site (just using username and password), for to see the extra
        screen on which you are asked to provide the token, generated by Google Authenticator and follow
        the link (help text of the "Enter code" field). You would then land on the page where from you
        can request the bar code reset.
        
        Enter your username in the "Username" field, press the "Submit" button. Link for resetting your
        bar code appear in your mailbox shortly. Having clicked on the link to reset the bar code, would
        bring your to a page where you can scan the bar-code same way you have done it when setting up the
        two-step verification.
        
        Scan the code with your mobile device and enter the code in the "Enter the verification code to
        activate the two-step verification" field.
        
        Upon successful confirmation (you should see a message stating that) your bar code is reset.
        
        Case 4: Disabling the two-step verification
        ------------------------------------------------
        Pre-conditions: User is logged in and has enabled the two-step verification.
        
        From "Personal information" page click the second of the two links under "Enable two-step
        verification".
        
        Implementation details
        ================================================
        This package is beta. Comments and suggestions are welcome.
        
        - Plone PAS plugin, which checks if user has the two-step verification enabled for
          user trying to log in. If so, redirect user to a separate page (a view), where the extra 
          credentials (Google Authenticator token) is asked for.
        - Google Authenticator token validation form view. If token is valid, definitely authenticates the user.
        - Google Authenticator setup form view, where each user scans a bar code image is shown and fills in the token
          generated by his Google Authenticator app. Upon successful token validation, the two-step verification
          is enabled for the user.
        - User record is extended with two fields:
              * `enable_two_factor_authentication` (bool): Indicates whether user has enabled the two-step
                verification for his profile.
              * `two_factor_authentication_secret` (str): Users' secret key to be used for generating the bar code 
                image. Filled in automatically when user enables the two-step verification.
        - Google Authenticator disable view, on which user can disable the two-step verification for his account.
        - The Plone standard login form (skins/login_form.cpt) has been overridden (the `came_from` form field taken out). 
          Still the "came from" functionality works still in the very same way as it was before, just slightly 
          different - in a way that it works well with Google Authenticator too.
        - The Plone standard "popupforms.js" has been overridden. The part of login forms being shown in an overlay
          has been taken out, due to the problems of Google Authenticator working with overlays. This issue might be
          solved in future versions of the app.
        
        Installation
        ================================================
        Buildout
        ------------------------------------------------
        >>> [instance]
        >>> eggs +=
        >>>     collective.googleauthenticator
        
        >>> zcml +=
        >>>     collective.googleauthenticator
        
        ZMI
        ------------------------------------------------
        ZMI -> portal_quickinstaller
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Choose "Google Authenticator Plone" and install it.
        
        ZMI -> acl_users
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        1. Choose "Collective Google Authenticator PAS" from the drop down menu (upper right corner of the page).
        
        2. Make sure the "Active plugins" section of "Authentication" has the following plugins in the given
           order (critical!):
        
            - collective_google_authenticator
            - session
            - source_users
        
        App specific settings
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        Go to the app settings (http://your-plone-site.com/@@google-authenticator-settings)
        and enter a secret key (can be any string; think of it as some sort of a password).
        
        Notes
        ================================================
        It's important that Google Authenticator comes as first in the ZMI -> acl_users -> Authentication.
        
        Tested in combination with the following products:
        
        - The `Products.LoginLockout` (https://pypi.python.org/pypi/Products.LoginLockout). `GoogleAuthenticator`
          comes as first, `LoginLockout` as second. All works fine.
        
        Documentation
        ================================================
        See the documentation at:
        
        - http://collectivegoogleauthenticator.readthedocs.org/en/latest/
        - http://pythonhosted.org/collective.googleauthenticator/
        
        Development status
        ================================================
        Beta
        
        Support
        ================================================
        For feature requests or bugs, open an issue. For questions, send us an email to info@gw20e.com.
        
        TODOs and Roadmap
        ================================================
        See "TODOS.rst" file for the list of TODOs.
        
        License
        ================================================
        GPL 2.0
        
        Authors & copyright
        ================================================
        Copyright (C) 2014 Goldmund, Wyldebeast & Wunderliebe.
        
        Authors listed in alphabetic order (by name):
        
        - Artur Barseghyan
        - Kim Chee Leong
        - Peter Uittenbroek
        
        Changelog
        ================================================
        
        0.1 (13-01-2014)
        ------------------------------------------------
        
        - Initial release.
        
Keywords: google authenticator,two-step verification,multi-factor authentication,two-factor authentication
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.6
Classifier: Topic :: Software Development :: Libraries :: Python Modules
