#29803 Add support for 2 factor authentication (2FA)

Adding support for 2FA the API so it is ready when Shotgun supports this. The `auth_token` parameter added to the authentication process defaults to `None` and can be ignored by all clients until 2FA is made available.

Closes #85

Author: KP

README.md

@@ -53,6 +53,10 @@ Integration and unit tests are provided.
 
 ## Changelog
 
+**v3.0.20 - TBD**
+
+   + Add authentication support for Shotgun servers with two-factor authentication turned on.
+
 **v3.0.19 - 2015 Mar 25**
 
    + Add ability to authenticate with Shotgun using `session_token`.

shotgun_api3/__init__.py

@@ -1,4 +1,5 @@
 from shotgun import (Shotgun, ShotgunError, ShotgunFileDownloadError, Fault, 
-                     AuthenticationFault, ProtocolError, ResponseError, Error, __version__)
+                     AuthenticationFault, MissingTwoFactorAuthenticationFault,
+                     ProtocolError, ResponseError, Error, __version__)
 from shotgun import SG_TIMEZONE as sg_timezone
 

shotgun_api3/shotgun.py

@@ -97,6 +97,12 @@ class AuthenticationFault(Fault):
     """Exception when the server side reports an error related to authentication"""
     pass
 
+class MissingTwoFactorAuthenticationFault(Fault):
+    """Exception when the server side reports an error related to missing
+    two factor authentication credentials
+    """
+    pass
+
 # ----------------------------------------------------------------------------
 # API
 
@@ -231,6 +237,7 @@ def __init__(self):
         self.script_name = None
         self.user_login = None
         self.user_password = None
+        self.auth_token = None
         self.sudo_as_login = None
         # uuid as a string
         self.session_uuid = None
@@ -279,7 +286,8 @@ def __init__(self,
                  login=None,
                  password=None,
                  sudo_as_login=None,
-                 session_token=None):
+                 session_token=None,
+                 auth_token=None):
         """Initialises a new instance of the Shotgun client.
 
         :param base_url: http or https url to the shotgun server.
@@ -329,6 +337,13 @@ def __init__(self,
         :param session_token: The session token to use to authenticate to the server. This
         can be used as an alternative to authenticating with a script user or regular user.
         You retrieve the session token by running the get_session_token() method.        
+
+        :param auth_token: The authentication token required to authenticate to
+        a server with two factor authentication turned on. If auth_token is provided,
+        then login and password must be as well and neither script_name nor api_key
+        can be provided. Note that these tokens can be short lived so a session is
+        established right away if an auth_token is provided. A
+        MissingTwoFactorAuthenticationFault will be raised if the auth_token is invalid.
         """
 
         # verify authentication arguments
@@ -355,6 +370,13 @@ def __init__(self,
             if api_key is None:
                 raise ValueError("script_name provided without api_key")
 
+        if auth_token is not None:
+            if login is None or password is None:
+                raise ValueError("must provide a user login and password with an auth_token")
+
+            if script_name is not None or api_key is not None:
+                raise ValueError("cannot provide an auth_code with script_name/api_key")
+
         # Can't use 'all' with python 2.4
         if len([x for x in [session_token, script_name, api_key, login, password] if x]) == 0:
             if connect:
@@ -365,6 +387,7 @@ def __init__(self,
         self.config.script_name = script_name
         self.config.user_login = login
         self.config.user_password = password
+        self.config.auth_token = auth_token
         self.config.session_token = session_token
         self.config.sudo_as_login = sudo_as_login
         self.config.convert_datetimes_to_utc = convert_datetimes_to_utc
@@ -423,8 +446,6 @@ def __init__(self,
             proxy_addr = "http://%s%s:%d" % (auth_string, self.config.proxy_server, self.config.proxy_port)
             self.config.proxy_handler = urllib2.ProxyHandler({self.config.scheme : proxy_addr})
 
-
-
         if ensure_ascii:
             self._json_loads = self._json_loads_ascii
 
@@ -438,6 +459,15 @@ def __init__(self,
         if connect:
             self.server_caps
 
+        # When using auth_token in a 2FA scenario we need to switch to session-based
+        # authentication because the auth token will no longer be valid after a first use.
+        if self.config.auth_token != None:
+            self.config.session_token = self.get_session_token()
+            self.config.user_login = None
+            self.config.user_password = None
+            self.config.auth_token = None
+
+
     # ========================================================================
     # API Functions
 
@@ -1519,11 +1549,17 @@ def get_attachment_download_url(self, attachment):
                 None, None, None))
         return url
 
-    def authenticate_human_user(self, user_login, user_password):
+    def authenticate_human_user(self, user_login, user_password, auth_token=None):
         '''Authenticate Shotgun HumanUser. HumanUser must be an active account.
-        @param user_login: Login name of Shotgun HumanUser
-        @param user_password: Password for Shotgun HumanUser
-        @return: Dictionary of HumanUser including ID if authenticated, None is unauthorized.
+        :param user_login: Login name of Shotgun HumanUser
+
+        :param user_password: Password for Shotgun HumanUser
+
+        :param auth_token: One-time token required to authenticate Shotgun HumanUser
+        when two factor authentication is turned on.
+
+        :return: Dictionary of HumanUser including ID if authenticated, None if unauthorized.
+        """
         '''
         if not user_login:
             raise ValueError('Please supply a username to authenticate.')
@@ -1534,24 +1570,29 @@ def authenticate_human_user(self, user_login, user_password):
         # Override permissions on Config obj
         original_login = self.config.user_login
         original_password = self.config.user_password
+        original_auth_token = self.config.auth_token
 
         self.config.user_login = user_login
         self.config.user_password = user_password
+        self.config.auth_token = auth_token
 
         try:
             data = self.find_one('HumanUser', [['sg_status_list', 'is', 'act'], ['login', 'is', user_login]], ['id', 'login'], '', 'all')
             # Set back to default - There finally and except cannot be used together in python2.4
             self.config.user_login = original_login
             self.config.user_password = original_password
+            self.config.auth_token = original_auth_token
             return data
         except Fault:
             # Set back to default - There finally and except cannot be used together in python2.4
             self.config.user_login = original_login
             self.config.user_password = original_password
+            self.config.auth_token = original_auth_token
         except:
             # Set back to default - There finally and except cannot be used together in python2.4
             self.config.user_login = original_login
             self.config.user_password = original_password
+            self.config.auth_token = original_auth_token
             raise
 
 
@@ -1597,7 +1638,8 @@ def get_session_token(self):
         session_token = (rv or {}).get("session_id")
         if not session_token:
             raise RuntimeError("Could not extract session_id from %s", rv)
-        self.config.session_token = session_token 
+        self.config.session_token = session_token
+
         return session_token
 
     def _build_opener(self, handler):
@@ -1669,6 +1711,8 @@ def _auth_params(self):
                 "user_login" : str(self.config.user_login),
                 "user_password" : str(self.config.user_password),
             }
+            if self.config.auth_token:
+                auth_params["auth_token"] = str(self.config.auth_token)
 
         # Use script name instead
         elif self.config.script_name and self.config.api_key:
@@ -1867,14 +1911,15 @@ def _response_errors(self, sg_response):
 
         :raises ShotgunError: If the server response contains an exception.
         """
- 
+
         ERR_AUTH = 102 # error code for authentication related problems
+        ERR_2FA  = 106 # error code when 2FA authentication is required but no 23FA token provided.
 
         if isinstance(sg_response, dict) and sg_response.get("exception"):
-            
             if sg_response.get("error_code") == ERR_AUTH:
                 raise AuthenticationFault(sg_response.get("message", "Unknown Authentication Error"))
-
+            elif sg_response.get("error_code") == ERR_2FA:
+                raise MissingTwoFactorAuthenticationFault(sg_response.get("message", "Unknown 2FA Authentication Error"))
             else:
                 # raise general Fault            
                 raise Fault(sg_response.get("message", "Unknown Error"))

tests/test_api.py

@@ -1408,6 +1408,7 @@ def test_bad_auth(self):
         api_key = self.config.api_key
         login = self.config.human_login
         password = self.config.human_password
+        auth_token = "111111"
 
         # Test various combinations of illegal arguments
         self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url)
@@ -1417,6 +1418,12 @@ def test_bad_auth(self):
         self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, login=login)
         self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, password=password)
         self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, script_name, login=login, password=password)
+        self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, login=login, auth_token=auth_token)
+        self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, password=password, auth_token=auth_token)
+        self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, script_name, login=login,
+                          password=password, auth_token=auth_token)
+        self.assertRaises(ValueError, shotgun_api3.Shotgun, server_url, api_key=api_key, login=login,
+                          password=password, auth_token=auth_token)
 
         # Test failed authentications
         sg = shotgun_api3.Shotgun(server_url, script_name, api_key)