RDEV-3108 Usernames support, code simplification

Author: rublon-psz

Core/APIMethod.cs

@@ -17,8 +17,7 @@ public abstract class APIMethod
 
         public static class RublonCommonParams
         {
-            public const string FIELD_USER_ID = "appUserId";
-
+            public const string USERNAME_FIELD = "username";
         }
 
         public RESTClient RestClient { get; set; }
@@ -43,10 +42,10 @@ public APIMethod(IRublonConsumer rublon)
         public void Perform()
         {
             var rawPostBody = string.Empty;
-            var parameters = getParams();
-            if (parameters != null && parameters.Count > 0)
+            var requestBodyJSON = prepareRequestBody();
+            if (requestBodyJSON != null && requestBodyJSON.Count > 0)
             {
-                rawPostBody = parameters.ToString();
+                rawPostBody = requestBodyJSON.ToString();
             }
 
             var url = getUrl();
@@ -72,7 +71,7 @@ public void Perform()
         /// Get the API request's parameters object.
         /// </summary>
         /// <returns></returns>
-        protected virtual JObject getParams()
+        protected virtual JObject prepareRequestBody()
         {
             var parameters = new JObject();
             parameters.Add(FIELD_SYSTEM_TOKEN, rublon.SystemToken);

Properties/AssemblyInfo.cs

@@ -31,5 +31,5 @@
 // You can specify all the values or you can default the Build and Revision Numbers
 // by using the '*' as shown below:
 // [assembly: AssemblyVersion("1.0.*")]
-[assembly: AssemblyVersion("1.0.2.0")]
-[assembly: AssemblyFileVersion("1.0.2.0")]
+[assembly: AssemblyVersion("1.1.0.0")]
+[assembly: AssemblyFileVersion("1.1.0.0")]

README.md

@@ -49,8 +49,7 @@ e.g. with a username and password (usually we call it first factor).
 It is a necessary step, because upon Rublon's initialization the service
 must receive certain information about the user:
 
-- a unique Id, stored in the system (inafter called **the integrated system**) implementing the Rublon service,
-- the user's email address.
+- the username, from Rublon for which authentication will be called, (usually it is the same as username from the integrated system).
 
 To experience the full measure of two-factor authentication, the end-user
 should install the Rublon mobile app, available on all leading smartphone
@@ -64,15 +63,14 @@ a Email2FA process which does not require using an additional device of any kind
 
 #### User protection
 
-User protection is active when a user's email address in the integrated system
+User protection is active when a username in the integrated system
 can be matched to a user in the Rublon service.
-For this purpose, the user's email is sent to Rublon servers.
+For this purpose, the username is sent to Rublon servers.
 
-1. If the email is matched to an existing Rublon account, the user's identity
+1. If the username is matched to an existing Rublon account, the user's identity
 can be confirmed using Rublon.
-2. Otherwise, if the user does not possess a Rublon account (the email
-could not be matched), Rublon will use the Email2FA process, trying to verify
-the user's identity by sending a confirmation email message to his email address.
+2. Otherwise, if the user does not possess a Rublon account (the username
+could not be matched), Rublon will start an enrollment process.
 
 #### Identity confirmation
 
@@ -160,7 +158,8 @@ An example of the library's initialization:
 		var rublon = new Rublon(
 			// system token:
 			"A69FC450848B4B94A040416DC4421523",
-			// secret key:			"bLS6NDP7pGjg346S4IHqTHgQQjjSLw3CyApvz5iRjYzgIPN4e9EOi1cQJLrTlvLoHY8zeqg4ILrItYidKJ6JjEUZaA6pR1tZMwSZ"
+			// secret key:			
+			"bLS6NDP7pGjg346S4IHqTHgQQjjSLw3CyApvz5iRjYzgIPN4e9EOi1cQJLrTlvLoHY8zeqg4ILrItYidKJ6JjEUZaA6pR1tZMwSZ"
 		);
 
 <a id="auth"></a>
@@ -179,42 +178,36 @@ Administrator can force users to authenticate using the mobile app (to avoid the
 
 Authenticating a user with the second factor should be initiated when the user
 has successfully passed the first factor of authentication (e.g. the valid user
-credentials have been provided) and the user's unique Id and email address are known.
+credentials have been provided) and the user's unique Id is known.
 
-The `Rublon.Auth()` method will check the user's protection status (using
-the email address) and return a URL address for the web browser to be redirected to
+The `Rublon.Auth()` method will check the user's protection status and return a URL address for the web browser to be redirected to
 (if user protection is active) or `null` in case the user's protection is not active.
 
 <table>
-	<caption><code>Rublon.Auth()</code> method arguments</caption>
+	<caption><code>Rublon.Auth()</code> method has one argument of type <code>AuthenticationParameters</code> with the following fields</caption>
 	<thead><tr>
-		<th>Name</th>
+		<th>Property Name</th>
 		<th>Type</th>
 		<th>Description</th>
 	</tr></thead>
 	<tbody>
             <tr>
-                <td><code>callbackUrl</code></td>
+                <td><code>CallbackUrl</code></td>
                 <td>String</td><td>The integrated system's callback URL</td>
             </tr>
             <tr>
-                <td><code>appUserId</code></td>
+                <td><code>UserName</code></td>
                 <td>String</td>
-                <td>The integrated system's user's unique Id which will allow to log in the user upon successful authentication</td>
+                <td>The integrated system's username, which will allow to log in the user upon successful authentication and match the user to a Rublon account.</td>
             </tr>
             <tr>
-                <td><code>userEmail</code></td><td>String</td>
-                <td>The user's email address in the integrated system which will allow to check the user's protection status and match the user to a Rublon account</td>
+                <td><code>UserEmail</code></td><td>String</td>
+                <td>The user's email address. This is a optional parameter and can be empty. If set the email addresss will be set in Rublon for the given username</td>
             </tr>
             <tr>
-                <td><code>consumerParams</code></td>
+                <td><code>AdditionalParams</code></td>
                 <td>JSONObject</td>
-                <td>Additional transaction parameters (optional)</td>
-            </tr>
-            <tr>
-                <td><code>isPasswordless</code></td>
-                <td>boolean</td>
-                <td>Information if it is a login attempt using passwordless method (optional)</td>
+                <td>Additional transaction parameters (optional), which will be send to Rublon, the ParamsBuilder class can be used to prepare parameters easily</td>
             </tr>
         </tbody>
 </table>
@@ -259,10 +252,10 @@ An example of logging in a user on an integrated system:
 		
 		try { // Initiate a Rublon authentication transaction
 		
-			String url = rublon.Auth(
-				"http://example.com/rublon_callback", // callback URL
-				Session.getUser().getId(), // User Id
-				Session.getUser().getEmail() // User email
+			String url = rublon.Auth(new AuthenticationParameters(){
+					CallbackUrl = "http://example.com/rublon_callback", 
+					Username = Session.getUser().getId()
+				}
 			);
 			
 			if (url != null) { // User protection is active

RublonSDK.csproj

@@ -69,6 +69,7 @@
     <Compile Include="Properties\AssemblyInfo.cs" />
     <Compile Include="TwoFactor\API\BeginTransaction.cs" />
     <Compile Include="TwoFactor\API\Credentials.cs" />
+    <Compile Include="TwoFactor\AuthenticationParameters.cs" />
     <Compile Include="TwoFactor\IRublon.cs" />
     <Compile Include="TwoFactor\Rublon.cs" />
     <Compile Include="TwoFactor\RublonCallback.cs" />

TwoFactor/API/BeginTransaction.cs

@@ -1,5 +1,6 @@
 using Newtonsoft.Json.Linq;
 using Rublon.Sdk.Core;
+using System;
 
 namespace Rublon.Sdk.TwoFactor
 {
@@ -17,17 +18,17 @@ public class BeginTransaction : APIMethod
         protected string callbackUrl;
         protected string userEmail;
         protected string userId;
-        protected JObject consumerParams;
+        protected JObject additionalParams;
 
         /// <summary>
         /// Construct the API method instance.
         /// </summary>
         /// <param name="rublon">Rublon instance.</param>
         /// <param name="callbackUrl">URL of the callback method.</param>
         /// <param name="userEmail">User's email address.</param>
-        /// <param name="userId">User's local ID.</param>
-        public BeginTransaction(Rublon rublon, string callbackUrl, string userEmail, string userId)
-            : this(rublon, callbackUrl, userEmail, userId, new JObject())
+        /// <param name="userName">User's local ID.</param>
+        public BeginTransaction(Rublon rublon, string callbackUrl, string userEmail, string userName)
+            : this(rublon, callbackUrl, userEmail, userName, new JObject())
         {
 
         }
@@ -38,15 +39,15 @@ public BeginTransaction(Rublon rublon, string callbackUrl, string userEmail, str
         /// <param name="rublon">Rublon instance.</param>
         /// <param name="callbackUrl">URL of the callback method.</param>
         /// <param name="userEmail">User's email address.</param>
-        /// <param name="userId">User's local ID.</param>
-        /// <param name="consumerParams">Additional transaction parameters.</param>
-        public BeginTransaction(IRublon rublon, string callbackUrl, string userEmail, string userId, JObject consumerParams)
+        /// <param name="userName">User's local ID.</param>
+        /// <param name="additionalParams">Additional transaction parameters.</param>
+        public BeginTransaction(IRublon rublon, string callbackUrl, string userEmail, string userName, JObject additionalParams)
             : base(rublon)
         {
             this.callbackUrl = callbackUrl;
             this.userEmail = userEmail;
-            this.userId = userId;
-            this.consumerParams = consumerParams;
+            this.userId = userName;
+            this.additionalParams = additionalParams;
         }
 
         /// <summary>
@@ -63,16 +64,23 @@ protected override string getUrl()
             return rublon.APIServer + REQUEST_URI_PATH;
         }
 
-        protected override JObject getParams()
+        protected override JObject prepareRequestBody()
         {
-            var baseParameters = base.getParams();
-            var parameters = new JObject(consumerParams);
+            var baseParameters = base.prepareRequestBody();
+            var parameters = new JObject(additionalParams);
             parameters.Merge(baseParameters);
-            parameters.Add(RublonCommonParams.FIELD_USER_ID, userId);
+            parameters.Add(RublonCommonParams.USERNAME_FIELD, userId);
             parameters.Add(FIELD_CALLBACK_URL, callbackUrl);
-            parameters.Add(FIELD_USER_EMAIL, userEmail.ToLower());
-
+            addUserEmailIfNotEmpty(parameters);            
             return parameters;
         }
+
+        private void addUserEmailIfNotEmpty(JObject parameters)
+        {
+            if (!String.IsNullOrWhiteSpace(userEmail))
+            {
+                parameters.Add(FIELD_USER_EMAIL, userEmail.ToLower());
+            }
+        }
     }
 }

TwoFactor/API/Credentials.cs

@@ -6,12 +6,7 @@ namespace Rublon.Sdk.TwoFactor
     public class Credentials : APIMethod
     {
         public const string REQUEST_URI_PATH = "/api/transaction/credentials";
-
-        /// <summary>
-        /// Field name for the user's device ID.
-        /// </summary>
-        public const string FIELD_DEVICE_ID = "deviceId";
-
+        
         public const string FIELD_ACCESS_TOKEN = "accessToken";
 
         protected string accessToken;
@@ -31,28 +26,19 @@ public Credentials(Rublon rublon, string accessToken)
         /// Get the user's local ID from the response.
         /// </summary>
         /// <returns></returns>
-        public string GetUserId()
+        public string GetUsername()
         {
-            return methodCallResponse.Value<string>(RublonCommonParams.FIELD_USER_ID);
+            return methodCallResponse.Value<string>(RublonCommonParams.USERNAME_FIELD);
         }
-        
-        /// <summary>
-        /// Get the user's device ID from the response.
-        /// </summary>
-        /// <returns></returns>
-        public string GetDeviceId()
-        {
-            return methodCallResponse.Value<string>(FIELD_DEVICE_ID);
-        }        
 
         protected override string getUrl()
         {
             return rublon.APIServer + REQUEST_URI_PATH;
         }
 
-        protected override JObject getParams()
+        protected override JObject prepareRequestBody()
         {
-            var baseParameters = base.getParams();
+            var baseParameters = base.prepareRequestBody();
             baseParameters.Add(FIELD_ACCESS_TOKEN, accessToken);
 
             return baseParameters;

TwoFactor/AuthenticationParameters.cs

@@ -0,0 +1,39 @@
+using Newtonsoft.Json.Linq;
+
+namespace Rublon.Sdk.TwoFactor
+{
+    /// <summary>
+    /// Authentication parameters used during transaction initialisation (transaction init).
+    /// </summary>
+    public class AuthenticationParameters
+    {
+        /// <summary>
+        /// Url which Rublon will redirect browser, when authentication is finished
+        /// </summary>
+        public string CallbackUrl {
+            get;
+            set;
+        }
+
+        /// <summary>
+        /// Username of a user who is authenticated
+        /// </summary>
+        public string Username {
+            get; set;
+        }
+
+        /// <summary>
+        /// Email of a user who is authenticated, this is optional
+        /// </summary>
+        public string UserEmail
+        {
+            get;
+            set;
+        } = "";
+
+        /// <summary>
+        /// Additional parameters send to the transation init request
+        /// </summary>
+        public JObject AdditionalParams { get; set; } = new JObject();
+    }
+}

TwoFactor/IRublon.cs

@@ -6,10 +6,33 @@ namespace Rublon.Sdk.TwoFactor
 {
     public interface IRublon : IRublonConsumer
     {
+        /// <summary>
+        /// Provides logging feature, for debugging purposes its log method is called 
+        /// before and after every call to Rublon authentication server.
+        /// </summary>        
         IRublonLogger Logger { get; set; }
 
-        string Auth(string callbackUrl, string userId, string userEmail);
-        string Auth(string callbackUrl, string userId, string userEmail, JObject consumerParams);
+        /// <summary>
+        /// Initializes the Rublon 2-factor authentication transaction.
+        /// Returns the URL to which browser should be redirected in order to continue authentication process for the started transaction.
+        /// The URL will redirect to the so called Rublon prompt.
+        /// If something will fail the method will throw exception which inherits from RublonException.
+        /// When authentication process is finished in Rublon prompt the process will redirect to authenticationParameters.callbackUrl 
+        /// with access token and <see cref="GetCredentials(string)"/> can be called to finish authentication.
+        /// Instead of get credentials you can also use <see cref="RublonCallback"/> which contains already some logic related to getting access token parameter.
+        /// </summary>
+        /// <param name="authenticationParameters">authentication parameters for the user</param>
+        /// <returns>web URI to Rublon prompt for the created transaction</returns>
+        string Auth(AuthenticationParameters authenticationParameters);
+
+        /// <summary>
+        /// Finishes authentication for a given accessToken and get user's credentials using one-time use access token.
+        /// 
+        /// One-time use access token is a session identifier which will be deleted after first usage.
+        /// This method can be called only once in authentication process.
+        /// </summary>
+        /// <param name="accessToken">access token</param>
+        /// <returns>Credentials</returns>
         Credentials GetCredentials(string accessToken);
     }
 }