New GitHub Auth Class (#242)

* Add helper class for mocking github api in integration tests

* Add helper method for TTL-based test casts

* Add documentation for github auth class

* Add initial vault api base class

* Github auth test cases

* Add Github auth class

* Add github instance property and mark auth_github as deprecated

* Remove stray/out of date comment

* Add missing "minutes" / "m" suffix

* Add test cases for "h" and "m" ttl duration suffixies

* fix docstring and conversion logic

docs/source/hvac_api.rst

@@ -0,0 +1,7 @@
+hvac.api
+========
+
+.. automodule:: hvac.api
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/hvac_api_auth.rst

@@ -0,0 +1,7 @@
+hvac.api.auth
+=============
+
+.. automodule:: hvac.api.auth
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source_reference.rst

@@ -5,6 +5,8 @@ Source Reference
    :maxdepth: 4
 
    source/hvac_v1
+   source/hvac_api
+   source/hvac_api_auth
    source/hvac_utils
    source/hvac_aws_utils
    source/hvac_adapters

docs/usage.rst

@@ -11,6 +11,7 @@ Usage
    usage/kubernetes_auth_method
    usage/approle_auth_method
    usage/ldap_auth_method
+   usage/github
 
 
 Authenticate to different auth backends

docs/usage/github.rst

@@ -0,0 +1,154 @@
+GitHub Auth Method
+==================
+
+.. note::
+    Every method under the :py:attr:`Client class's github attribute<hvac.v1.Client.github>` includes a `mount_point` parameter that can be used to address the Github auth method under a custom mount path. E.g., If enabling the Github auth method using Vault's CLI commands via `vault auth enable -path=my-github github`", the `mount_point` parameter in :py:meth:`hvac.api.auth.Github` methods would be set to "my-github".
+
+Enabling the Auth Method
+------------------------
+
+:py:meth:`hvac.v1.Client.enable_auth_backend`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    github_auth_path = 'company-github'
+    description = 'Auth method for use by team members in our company's Github organization'
+
+    if '%s/' % github_auth_path not in vault_client.list_auth_backends():
+        print('Enabling the github auth backend at mount_point: {path}'.format(
+            path=github_auth_path,
+        ))
+        client.enable_auth_backend(
+            backend_type='github',
+            description=description,
+            mount_point=github_auth_path,
+        )
+
+Configure Connection Parameters
+-------------------------------
+
+:py:meth:`hvac.api.auth.Github.configure`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    client.github.configure(
+        organization='our-lovely-company',
+        max_ttl='48h',  # i.e., A given token can only be renewed for up to 48 hours
+    )
+
+Reading Configuration
+---------------------
+
+:py:meth:`hvac.api.auth.Github.read_configuration`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    github_config = client.github.read_configuration()
+    print('The Github auth method is configured with a ttl of: {ttl}'.format(
+        ttl=github_config['data']['ttl']
+    )
+
+
+Mapping Teams to Policies
+-------------------------
+
+:py:meth:`hvac.api.auth.Github.map_team`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    teams = [
+        dict(name='some-dev-team', policies=['dev-team']),
+        dict(name='admin-team', policies=['administrator']),
+    ]
+    for team in teams:
+        client.github.map_team(
+            team_name=team['name'],
+            policies=team['policies'],
+        )
+
+Reading Team Mappings
+---------------------
+
+:py:meth:`hvac.api.auth.Github.read_team_mapping`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    team_name = 'my-super-cool-team'
+    github_config = client.github.read_team_mapping(
+        team_name=team_name,
+    )
+    print('The Github team {team} is mapped to the following policies: {policies}'.format(
+        team=team_name,
+        policies=github_config['data']['value'],
+    )
+
+
+Mapping Users to Policies
+-------------------------
+
+:py:meth:`hvac.api.auth.Github.map_user`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    users = [
+        dict(name='some-dev-user', policies=['dev-team']),
+        dict(name='some-admin-user', policies=['administrator']),
+    ]
+    for user in users:
+        client.github.map_user(
+            user_name=user['name'],
+            policies=user['policies'],
+        )
+
+Reading User Mappings
+---------------------
+
+:py:meth:`hvac.api.auth.Github.read_user_mapping`
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+
+    user_name = 'some-dev-user'
+    github_config = client.github.read_user_mapping(
+        user_name=user_name,
+    )
+    print('The Github user "{user}" is mapped to the following policies: {policies}'.format(
+        user=user_name,
+        policies=github_config['data']['value'],
+    )
+
+Authentication / Login
+----------------------
+
+:py:meth:`hvac.api.auth.Github.login`
+
+Log in and automatically update the underlying "token" attribute on the :py:meth:`hvac.adapters.Adapter` instance:
+
+.. code:: python
+
+    import hvac
+    client = hvac.Client()
+    login_response = client.github.login(token='some personal github token')
+
+
+

hvac/api/__init__.py

@@ -0,0 +1,8 @@
+"""Collection of Vault API endpoint classes."""
+from hvac.api import auth
+from hvac.api.vault_api_base import VaultApiBase
+
+__all__ = (
+    'VaultApiBase',
+    'auth',
+)

hvac/api/auth/__init__.py

@@ -0,0 +1,7 @@
+"""Collection of classes for various Vault auth methods."""
+
+from hvac.api.auth.github import Github
+
+__all__ = (
+    'Github',
+)