API changed a bit before release, readmefile, version bump

mihaj · web-flow · commit b98c34cd5f48 · 2020-12-06T11:14:43.000+01:00
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -1,5 +1,5 @@
 <Project>
   <PropertyGroup>
-    <Version>0.1.6</Version>
+    <Version>0.1.7</Version>
   </PropertyGroup>
 </Project>
diff --git a/README.md b/README.md
@@ -1,72 +1,79 @@
 # QAToolKit Authentication library
-[![Build .NET Library](https://github.com/qatoolkit/qatoolkit-auth-net/workflows/.NET%20Core/badge.svg?branch=main)](https://github.com/qatoolkit/qatoolkit-auth-net/actions)
+[![Build .NET Library](https://github.com/qatoolkit/qatoolkit-auth-net/workflows/Build%20.NET%20Library/badge.svg)](https://github.com/qatoolkit/qatoolkit-auth-net/actions)
 [![CodeQL](https://github.com/qatoolkit/qatoolkit-auth-net/workflows/CodeQL%20Analyze/badge.svg)](https://github.com/qatoolkit/qatoolkit-auth-net/security/code-scanning)
 [![Sonarcloud Quality gate](https://github.com/qatoolkit/qatoolkit-auth-net/workflows/Sonarqube%20Analyze/badge.svg)](https://sonarcloud.io/dashboard?id=qatoolkit_qatoolkit-auth-net)
 [![NuGet package](https://img.shields.io/nuget/v/QAToolKit.Auth?label=QAToolKit.Auth)](https://www.nuget.org/packages/QAToolKit.Auth/)
 
 ## Description
-`QAToolKit.Auth` is a .NET Standard 2.1 library, that contains core objects and functions of the toolkit. It's normally not used as a standalone library but is a dependency for other QAToolKit libraries.
+`QAToolKit.Auth` is a .NET Standard 2.1 library, that retrieves the JWT access tokens from different identity providers.
+
+Currently it supports next Identity providers and Oauth2 flows:
+- `Keycloak`: Library supports Keycloak [client credentials flow](https://tools.ietf.org/html/rfc6749#section-4.4) or `Protection API token (PAT)` flow. Additionally you can replace the PAT with user token by exchanging the token.
 
 Supported .NET frameworks and standards: `netstandard2.0`, `netstandard2.1`, `netcoreapp3.1`, `net5.0`
 
-## 1. HttpRequest functions
-HttpRequest object is one of the main objects that is shared among the QA Toolkit libraries. `QAToolKit.Core` library contains `HttpRequestTools` which can manipulate the HttpRequest object.
+## 1. Keycloak support
 
-For example URL, header and Body generators: `HttpRequestUrlGenerator`, `HttpRequestBodyGenerator` and `HttpRequestHeaderGenerator`.
+Keycloak support is limited to the `client credential` or `Protection API token (PAT)` flow in combination with `token exchange`.
 
-### 1.1. HttpRequestUrlGenerator
-This is a method that will accept key/value pairs for replacement of placeholders in the `HttpRequest` object. Replacement object are stored in a dictionary, which `prevents mistakes with duplicated keys`.
-Also dictionary keys are case insensitive when looking for values to replace.
+### 1.1. Client credential flow
 
-```csharp
-options.AddReplacementValues(new Dictionary<string, object> {
-    {
-        "version",
-        "1"
-    },
-    {
-        "parentId",
-        "4"
-    }
-});
+A mocked request below is sent to the Keycloak endpoint, and the PAT token is retrieved:
+
+```bash
+curl -X POST \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    -d 'grant_type=client_credentials&client_id=${client_id}&client_secret=${client_secret}' \
+    "http://localhost:8080/auth/realms/${realm_name}/protocol/openid-connect/token"
 ```
 
-In the example above we say: "Replace `{version}` and {parentId} placeholders in Path and URL parameters and JSON body models."
+Read [more](https://www.keycloak.org/docs/latest/authorization_services/#_service_protection_whatis_obtain_pat) here in the Keycloak documentation.
 
-In other words, if you have a test API endpoint like this: https://api.demo.com/v{version}/categories?parent={parentId} that will be set to https://api.demo.com/v1/categories?parent=4.
+Now let's retrive a PAT token with QAToolKit Auth libraray:
 
-That, does not stop there, you can also populate JSON request bodies.
+```csharp
+var auth = new KeycloakAuthenticator(options =>
+{
+    options.AddClientCredentialFlowParameters(
+                new Uri("https://my.keycloakserver.com/auth/realms/realmX/protocol/openid-connect/token"), 
+                "my_client",
+                "client_secret");
+});
 
-### 1.2. HttpRequestBodyGenerator
+var token = await auth.GetAccessToken();
+```
 
-For example if you set the replacement value to stringified json:
+### 1.2. Client credential flow with token exchange
 
-```csharp
-options.AddReplacementValues(new Dictionary<string, object> {
-    {
-        "id",
-        "100"
-    },
-    {
-        "category",
-        "{\"id\":1,\"name\":\"dog\"}"
-    }
-});
+If you want to replace the PAT token with user token, you can additionally specify a username. A mocked request looks like this:
+
+```bash
+curl -X POST \
+    -H "Content-Type: application/x-www-form-urlencoded" \
+    -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&client_id=${client_id}&client_secret=${client_secret}&subject_token=eyJhbGciOiJI...&requested_subject=myuser@users.com' \
+    "http://localhost:8080/auth/realms/${realm_name}/protocol/openid-connect/token"
 ```
-than the parent model object will be replaced with the stringified json above.
 
-What happend behind the curtains, the model proxy class is generated, which is then used to Deserialized the JSON into the object.
-`HttpRequest` list is then scanned and values are properly replaced.
+As you see it has a different `grant_type` and additionally 2 more properties in the URL; PAT token (`subject_token`) and userName for which we want to replace the token (`requested_subject`).
 
-### 1.3. HttpRequestHeaderGenerator
+```csharp
+var auth = new KeycloakAuthenticator(options =>
+{
+    options.AddClientCredentialFlowParameters(
+                new Uri("https://my.keycloakserver.com/auth/realms/realmX/protocol/openid-connect/token"), 
+                "my_client",
+                "client_secret"); 
+    options.AddUserNameForImpersonation("myuser@users.com");
+});
 
-To-do
+var token = await auth.GetAccessToken();
+```
 
 ## To-do
 
 - **This library is an early alpha version**
-- `HttpRequestHeaderGenerator` is missing implementation.
-- `HttpRequestBodyGenerator` need to cover the whole spectrum of object tipes. Currently it's missing arrays, and nested objects. It's on the priority list.
+- Add more providers identity providers.
+- Add more OAuth2 flows.
 
 ## License
 
diff --git a/src/QAToolKit.Auth.Test/Keycloak/KeycloakOptionsTests.cs b/src/QAToolKit.Auth.Test/Keycloak/KeycloakOptionsTests.cs
@@ -27,6 +27,19 @@ public void KeycloakOptionsTest_Successful()
             Assert.Equal("12345", options.ClientId);
             Assert.Equal("12345", options.Secret);
             Assert.Equal(new Uri("https://api.com/token"), options.TokenEndpoint);
+            Assert.True(options.UseImpersonation);
+        }
+
+        [Fact]
+        public void KeycloakOptionsNoImpersonationTest_Successful()
+        {
+            var options = new KeycloakOptions();
+            options.AddClientCredentialFlowParameters(new Uri("https://api.com/token"), "12345", "12345");
+
+            Assert.Equal("12345", options.ClientId);
+            Assert.Equal("12345", options.Secret);
+            Assert.Equal(new Uri("https://api.com/token"), options.TokenEndpoint);
+            Assert.False(options.UseImpersonation);
         }
 
         [Theory]
diff --git a/src/QAToolKit.Auth/Keycloak/KeycloakOptions.cs b/src/QAToolKit.Auth/Keycloak/KeycloakOptions.cs
@@ -23,6 +23,10 @@ public class KeycloakOptions
         /// Username / email of the user for which you want to retrieve the access token
         /// </summary>
         public string UserName { get; set; }
+        /// <summary>
+        /// If username is set use impersonation
+        /// </summary>
+        public bool UseImpersonation { get; private set; } = false;
 
         /// <summary>
         /// Add client credential flow parameters
@@ -57,6 +61,7 @@ public KeycloakOptions AddUserNameForImpersonation(string userName)
                 throw new ArgumentNullException($"{nameof(userName)} is null.");
 
             UserName = userName;
+            UseImpersonation = true;
             return this;
         }
     }
diff --git a/src/QAToolKit.Auth/Keycloak/KeycloakTokenService.cs b/src/QAToolKit.Auth/Keycloak/KeycloakTokenService.cs
@@ -15,10 +15,10 @@ internal class KeycloakTokenService : IDisposable
         private readonly string _clientId;
         private readonly string _secret;
         private string _accessToken = null;
-        private DateTimeOffset? _accessTokenValidity = null;
         private readonly string _assemblyName;
         private readonly string _assemblyVersion;
         private readonly string _impersonatedUsername;
+        private readonly bool _useImpersonation;
 
         public KeycloakTokenService(KeycloakOptions keycloakOptions)
         {
@@ -27,19 +27,16 @@ public KeycloakTokenService(KeycloakOptions keycloakOptions)
             _tokenEndpoint = keycloakOptions.TokenEndpoint;
             _clientId = keycloakOptions.ClientId;
             _secret = keycloakOptions.Secret;
+            _impersonatedUsername = keycloakOptions.UserName;
+            _useImpersonation = keycloakOptions.UseImpersonation;
 
             _assemblyName = typeof(KeycloakTokenService).Assembly.GetName().Name;
             _assemblyVersion = typeof(KeycloakTokenService).Assembly.GetName().Version.ToString();
-            _impersonatedUsername = keycloakOptions.UserName;
+
         }
 
         public async Task<string> GetAccessTokenAsync()
         {
-            if (IsAccessTokenValid())
-            {
-                return _accessToken;
-            }
-
             await PostTokenClientCredentials();
 
             return _accessToken;
@@ -59,21 +56,15 @@ private async Task PostTokenClientCredentials()
                 new KeyValuePair<string, string>("client_secret", _secret)
             });
 
-            var now = DateTimeOffset.Now;
-
             var response = await _client.SendAsync(request);
 
             if (response.IsSuccessStatusCode)
             {
                 dynamic body = JObject.Parse(await response.Content.ReadAsStringAsync());
 
-                if (string.IsNullOrEmpty(_impersonatedUsername))
+                if (!_useImpersonation)
                 {
-                    string at = body.access_token;
-                    int ei = body.expires_in;
-
-                    _accessToken = at;
-                    _accessTokenValidity = now.AddSeconds(ei);
+                    _accessToken = body.access_token;
                 }
                 else
                 {
@@ -101,11 +92,7 @@ private async Task PostTokenClientCredentials()
                         {
                             dynamic content = JObject.Parse(contentStr);
 
-                            string at = content.access_token;
-                            int ei = content.expires_in;
-
-                            _accessToken = at;
-                            _accessTokenValidity = now.AddSeconds(ei);
+                            _accessToken = content.access_token;
                         }
                         else
                         {
@@ -124,17 +111,6 @@ private async Task PostTokenClientCredentials()
             }
         }
 
-        private bool IsAccessTokenValid(DateTimeOffset? now = null)
-        {
-            if (_accessToken == null || !_accessTokenValidity.HasValue)
-                return false;
-
-            if (!now.HasValue)
-                now = DateTimeOffset.Now;
-
-            return _accessTokenValidity.Value.AddSeconds(-TokenValidityOffsetSeconds) >= now;
-        }
-
         private HttpRequestMessage CreateBasicTokenEndpointRequest()
         {
             var request = new HttpRequestMessage(HttpMethod.Post, _tokenEndpoint);
