docs: improve readme

Catglobe · Nov 27, 2024 · 8b9ec61 · 8b9ec61
1 parent 545d26c
commit 8b9ec61
Show file tree

Hide file tree

Showing 3 changed files with 73 additions and 20 deletions.
diff --git a/README.md b/README.md
@@ -13,17 +13,16 @@ npm install catglobe.cgscript.deployment
 npm install catglobe.cgscript.runtime
 ```
 
-# Usage of the library
-
-## Development
+## Oidc client setup on server
 
-Development takes place on a developers personal device, which means that the developer can run the site locally and test it before deploying it to the staging server.
+### Runtime
 
-The authentication model is therefore that the developer logs into the using his own personal account. This account needs to have enough permission to set impersonation as configured on the scripts.
+Runtime requires the user to log in to the Catglobe site, and then the server will call the CgScript with the user's credentials.
 
+Adjust the following cgscript with the parentResourceId, clientId, clientSecret and name of the client and the requested scopes for your purpose and execute it on your Catglobe site.
 ```cgscript
 number parentResourceId = 42;
-string clientId = "13BAC6C1-8DEC-46E2-B378-90E0325F8132"; //use your own id -> store this in appsettings.Development.json
+string clientId = "13BAC6C1-8DEC-46E2-B378-90E0325F8132"; //use your own id -> store this in appsettings.json
 bool canKeepSecret = true; //demo is a server app, so we can keep secrets
 string clientSecret = "secret";
 bool askUserForConsent = false;
@@ -38,6 +37,62 @@ OidcAuthenticationFlow_createOrUpdate(parentResourceId, clientId, clientSecret,
 	canKeepSecret, layout, RedirectUri, PostLogoutRedirectUri, scopes, optionalscopes, name);
 ```
 
+Edit your appsettings.json file to include the following with the clientId, clientSecret and the requested scopes:
+```json
+"CatglobeOidc": {
+  "Authority": "https://localhost:5001/",
+  "ClientId": "13BAC6C1-8DEC-46E2-B378-90E0325F8132",
+  "ClientSecret": "secret",
+  "PostLogoutRedirectUri": "https://localhost:7176/authentication/logout-callback",
+  "RedirectUri": "https://localhost:7176/authentication/login-callback",
+  "ResponseType": "code",
+  "DefaultScopes": [ "email", "offline_access", "roles" ],
+  "SaveTokens": true
+},
+"CatglobeApi": {
+  "FolderResourceId": 42,
+  "Site": "https://localhost:5001/"
+},
+```
+
+## asp.net setup
+
+### Runtime
+In your start procedure, add the following:
+```csharp
+const string SCHEMENAME = "CatglobeOidc"; //must match the section name in appsettings.json
+
+// Add services to the container.
+var services = builder.Services;
+services.AddAuthentication(SCHEMENAME)
+        .AddOpenIdConnect(SCHEMENAME, oidcOptions => {
+            builder.Configuration.GetSection(SCHEMENAME).Bind(oidcOptions);
+            oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
+         })
+        .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme);
+services.AddCgScript(builder.Configuration.GetSection("CatglobeApi"));
+```
+
+Optionally, setup refresh-token refreshing as part of the cookie handling:
+```csharp
+      services.AddSingleton<CookieOidcRefresher>();
+      services.AddOptions<CookieAuthenticationOptions>(CookieAuthenticationDefaults.AuthenticationScheme).Configure<CookieOidcRefresher>((cookieOptions, refresher) => {
+         cookieOptions.Events.OnValidatePrincipal = context => refresher.ValidateOrRefreshCookieAsync(context, SCHEMENAME);
+      });
+```
+You can find the CookieOidcRefresher [here](https://github.com/dotnet/blazor-samples/blob/main/9.0/BlazorWebAppOidc/BlazorWebAppOidc/CookieOidcRefresher.cs).
+
+
+
+# Usage of the library
+
+## Development
+
+Development takes place on a developers personal device, which means that the developer can run the site locally and test it before deploying it to the staging server.
+
+The authentication model is therefore that the developer logs into the using his own personal account. This account needs to have enough permission to set impersonation as configured on the scripts.
+
+
 ## Staging and Deployment
 
 ```cgscript

diff --git a/demos/BlazorWebApp/BlazorWebApp/DemoUsage/SetupRuntime.cs b/demos/BlazorWebApp/BlazorWebApp/DemoUsage/SetupRuntime.cs
@@ -16,14 +16,14 @@ public static void Configure(WebApplicationBuilder builder)
       // Add services to the container.
       var services = builder.Services;
       services.AddAuthentication(SCHEMENAME)
-                       .AddOpenIdConnect(SCHEMENAME, oidcOptions => {
-                           builder.Configuration.GetSection(SCHEMENAME).Bind(oidcOptions);
-                           // ........................................................................
-                           // The OIDC handler must use a sign-in scheme capable of persisting 
-                           // user credentials across requests.
-                           oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
-                        })
-                       .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme);
+              .AddOpenIdConnect(SCHEMENAME, oidcOptions => {
+                  builder.Configuration.GetSection(SCHEMENAME).Bind(oidcOptions);
+                  // ........................................................................
+                  // The OIDC handler must use a sign-in scheme capable of persisting 
+                  // user credentials across requests.
+                  oidcOptions.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
+               })
+              .AddCookie(CookieAuthenticationDefaults.AuthenticationScheme);
 
       services.AddSingleton<CookieOidcRefresher>();
       // attaches a cookie OnValidatePrincipal callback to get
@@ -41,7 +41,7 @@ public static void Configure(WebApplicationBuilder builder)
       services.AddHttpForwarder();
 
       services.AddCgScript(builder.Configuration.GetSection("CatglobeApi"));
-      
+
       //and this is custom to this specific example... The rest above can be reused for pretty much any site
       services.AddSingleton<IWeatherForecaster, ServerWeatherForecaster>();
       services.AddSingleton<IPublicWeatherForecaster, ServerPublicWeatherForecaster>();
@@ -54,10 +54,8 @@ public static void Use(WebApplication app)
       //Add this, if you need the browser (blazor wasm or javascript) to be able to call CgScript
       //add     <PackageReference Include="Microsoft.Extensions.ServiceDiscovery.Yarp" Version="9.0.0" />
       var site = app.Services.GetRequiredService<IOptions<CgScriptOptions>>().Value.Site;
-      app.MapForwarder("/api/cgscript", site+"api/cgscript", transformBuilder =>
-      {
-         transformBuilder.AddRequestTransform(async transformContext =>
-         {
+      app.MapForwarder("/api/cgscript", site + "api/cgscript", transformBuilder => {
+         transformBuilder.AddRequestTransform(async transformContext => {
             var accessToken = await transformContext.HttpContext.GetTokenAsync("access_token");
             transformContext.ProxyRequest.Headers.Authorization = new("Bearer", accessToken);
          });

diff --git a/demos/BlazorWebApp/BlazorWebApp/appsettings.json b/demos/BlazorWebApp/BlazorWebApp/appsettings.json
@@ -16,7 +16,7 @@
     "PostLogoutRedirectUri": "https://localhost:7176/authentication/logout-callback",
     "RedirectUri": "https://localhost:7176/authentication/login-callback",
     "ResponseType": "code",
-    "DefaultScopes": [ "email", "offline_access" ],
+    "DefaultScopes": [ "email", "offline_access", "roles" ],
     "SaveTokens": true
   },
   "CatglobeApi": {