VCCS authentication Python client

Python client to communicate with VCCS authentication backends.

Since the VCCS authentication backend and client does not include native
TLS support, it is expected that some external software is used to secure
the communication between the frontends (where vccs_client is used) and
the backends (where vccs_auth is used).

If this external software is nginx for example, fault tolerance can be
achieved at the same time.


  frontend(s) :                                           backend(s) :
                                 HTTPS
                               to remote
             HTTP                hosts                 HTTP
vccs_client ------ local nginx -+-----+- remote nginx --+--- vccs_auth
                                 \   /                   \
                                  \ /                     +- vccs_auth
                                   X
                                  / \
                                 /   \
vccs_client ------ local nginx -+-----+- remote nginx --+--- vccs_auth
                                                         \
                                                          +- vccs_auth




Usage :

  >>> import vccs_client
  >>>

Create an authentication factor instance :

  >>> f = vccs_client.VCCSPasswordFactor('password', credential_id=4712)
  >>> f.salt
  '$2a$12$F0TIdfp4quhVJYIOO1ojU.'
  >>>

The salt and the credential_id needs to be remembered in the client
application for use when validating the password later on.


Create an authentication client instance :

  >>> a = vccs_client.VCCSClient()

  (VCCSClient() takes an optional base URL parameter, with the default
   being base_url='http://localhost:8550/').

Ask authentication backend to add the new credential to it's private
credential store (at the moment, only a single factor per add request
is supported, although the interface requires a list of factors) :

  >>> a.add_credentials('ft@example.net', [f])
  True
  >>>

Make a subsequent authentication request for the new credential :

  >>> a.authenticate('ft@example.net', [f])
  True
  >>>

Create a factor with an incorrect password :

  >>> incorrect_f = vccs_client.VCCSPasswordFactor('foobar', credential_id=4712,
  ...       salt='$2a$12$F0TIdfp4quhVJYIOO1ojU.')
  >>>

Try to authenticate with this incorrect credential :

  >>> a.authenticate('ft@example.net', [incorrect_f])
  False
  >>>


Add an OATH token credential :

  >>> o = vccs_client.VCCSOathFactor('oath-hotp', 4712, nonce=nonce, aead=aead)
  >>>

  (the nonce and AEAD would be generated by an 'originating' YubiHSM)

Authentication using an OATH credential :

  >>> o = vccs_client.VCCSOathFactor('oath-hotp', 4712, user_code='123456')
  >>> a.authenticate('ft@example.net', [o])
  True
  >>>


Multi-factor authentiation :

  >>> a.authenticate('ft@example.net', [f, o])
  True
  >>>


Revoke a credential (irreversible!) :

  >>> r = vccs_client.VCCSRevokeFactor(4712, 'testing revoke', reference='foobar')
  >>> client.revoke_credentials('ft@example.net', [r])
  True
  >>>


---

Fredrik Thulin <fredrik@thulin.net>, 2013-04-19