Authentication in Swagger UI & documentation

CHANGELOG.md

@@ -11,6 +11,7 @@
 - Added grid to manage organisations in administration area.
 - Added grid to manage users in administration area.
 - Added local Keycloak server for development.
+- Added authentication in Swagger UI.
 
 ### Changed
 

README.md

@@ -69,3 +69,44 @@ docker inspect --format='{{json .State.Health.Status}}' container_name
 ## Neue Version erstellen
 
 Ein neuer GitHub _Pre-release_ wird bei jeder Änderung auf [main](https://github.com/GeoWerkstatt/geopilot) [automatisch](./.github/workflows/pre-release.yml) erstellt. In diesem Kontext wird auch ein neues Docker Image mit dem Tag _:edge_ erstellt und in die [GitHub Container Registry (ghcr.io)](https://github.com/geowerkstatt/geopilot/pkgs/container/geopilot) gepusht. Der definitve Release erfolgt, indem die Checkbox _Set as the latest release_ eines beliebigen Pre-releases gesetzt wird. In der Folge wird das entsprechende Docker Image in der ghcr.io Registry mit den Tags (bspw.: _:v1.2.3_ und _:latest_) [ergänzt](./.github/workflows/release.yml).
+
+## Authentifizierung
+
+Fürs Login auf geopilot wird ein Identity Provider mit OpenID Connect (OIDC) vorausgesetzt.
+Der verwendete OAuth2 Flow ist _Authorization Code Flow with Proof Key for Code Exchange (PKCE)_.
+
+### Token
+
+Zur Authentifizierung aus dem Frontend wird das ID-Token und aus dem Swagger UI das Access-Token verwendet.
+Dabei wird geprüft, dass das Token von der angegebenen Authority ausgestellt wurde (`iss` Claim) und für die Client-Id gültig ist (`aud` Claim).
+Zusätzlich werden folgende Claims im Token vorausgesetzt: `sub`, `email` und `name`.
+Diese werden beispielsweise bei den OIDC Scopes `openid`, `profile` und `email` mitgeliefert.
+
+### Redirect URIs
+
+Als erlaubte Redirect URIs müssen für das Login aus dem Frontend `https://<app-domain>` und aus Swagger UI `https://<app-domain>/swagger/oauth2-redirect.html` angegeben werden.
+_([Entwicklungsumgebung](./config/realms/keycloak-geopilot.json): `https://localhost:5173` und `https://localhost:7188/swagger/oauth2-redirect.html`)_
+
+### Swagger UI
+
+Je nach Identity Provider wird die Audience automatisch gesetzt, sobald ein passender Scope verwendet wird.
+Der Wert `ApiScope` in den Appsettings kann dazu verwendet werden, um diesen im Swagger UI zur Auswahl anzuzeigen.
+
+In der [Entwicklungsumgebung](./config/realms/keycloak-geopilot.json) wird die Audience stattdessen mit einem Keycloak Protocol Mapper festgelegt.
+
+### Appsettings
+
+Folgende Appsettings müssen definiert sein (Beispiel aus [appsettings.Development.json](./src/Geopilot.Api/appsettings.Development.json) für die Entwicklungsumgebung):
+```json5
+"Auth": {
+    // General auth options
+    "Authority": "http://localhost:4011/realms/geopilot", // Token issuer
+    "ClientId": "geopilot-client", // Token audience
+
+    // Swagger UI auth options
+    "AuthorizationUrl": "http://localhost:4011/realms/geopilot/protocol/openid-connect/auth", // OAuth2 login URL
+    "TokenUrl": "http://localhost:4011/realms/geopilot/protocol/openid-connect/token", // OAuth2 token URL
+    "ApiScope": "<custom app scope> (optional)",
+    "ApiOrigin": "https://localhost:7188" // Swagger UI origin
+}
+```

config/realms/keycloak-geopilot.json

@@ -14,11 +14,29 @@
       "alwaysDisplayInConsole": true,
       "redirectUris": [
         "https://localhost:5173",
-        "http://localhost:5173"
+        "http://localhost:5173",
+        "https://localhost:7188/swagger/oauth2-redirect.html",
+        "http://localhost:5173/swagger/oauth2-redirect.html"
       ],
       "webOrigins": [
         "https://localhost:5173",
-        "http://localhost:5173"
+        "http://localhost:5173",
+        "https://localhost:7188"
+      ],
+      "protocolMappers": [
+        {
+          "name": "geopilot-audience-mapper",
+          "protocol": "openid-connect",
+          "protocolMapper": "oidc-audience-mapper",
+          "consentRequired": false,
+          "config": {
+            "included.client.audience": "geopilot-client",
+            "id.token.claim": "false",
+            "lightweight.claim": "false",
+            "access.token.claim": "true",
+            "introspection.token.claim": "true"
+          }
+        }
       ]
     }
   ],

docker-compose.yml

@@ -65,6 +65,9 @@ services:
       ReverseProxy__Clusters__stacBrowserCluster__Destinations__stacBrowserDestination__Address: http://stac-browser:8080/
       Auth__Authority: http://localhost:4011/realms/geopilot
       Auth__ClientId: geopilot-client
+      Auth__AuthorizationUrl: http://localhost:4011/realms/geopilot/protocol/openid-connect/auth
+      Auth__TokenUrl: http://localhost:4011/realms/geopilot/protocol/openid-connect/token
+      Auth__ApiOrigin: http://localhost:5173
       Validation__InterlisCheckServiceUrl: http://interlis-check-service/
     volumes:
       - ./src/Geopilot.Api/Uploads:/uploads

src/Geopilot.Api/Program.cs

@@ -102,6 +102,53 @@
 
     // Workaround for STAC API having multiple actions mapped to the "search" route.
     options.ResolveConflictingActions(apiDescriptions => apiDescriptions.First());
+
+    var scopes = new Dictionary<string, string>
+    {
+        { "openid", "Open Id" },
+        { "email", "User Email" },
+        { "profile", "User Profile" },
+    };
+    var apiScope = builder.Configuration["Auth:ApiScope"];
+    if (apiScope != null)
+    {
+        scopes.Add(apiScope, "geopilot API (required)");
+    }
+
+    options.AddSecurityDefinition(JwtBearerDefaults.AuthenticationScheme, new OpenApiSecurityScheme
+    {
+        Name = "Authorization",
+        Scheme = JwtBearerDefaults.AuthenticationScheme,
+        In = ParameterLocation.Header,
+        Type = SecuritySchemeType.OAuth2,
+        Flows = new OpenApiOAuthFlows
+        {
+            AuthorizationCode = new OpenApiOAuthFlow
+            {
+                Scopes = scopes,
+                AuthorizationUrl = new Uri(builder.Configuration["Auth:AuthorizationUrl"] !),
+                TokenUrl = new Uri(builder.Configuration["Auth:TokenUrl"] !),
+                RefreshUrl = new Uri(builder.Configuration["Auth:TokenUrl"] !),
+            },
+        },
+    });
+    options.AddSecurityRequirement(new OpenApiSecurityRequirement
+    {
+        {
+            new OpenApiSecurityScheme
+            {
+                Reference = new OpenApiReference
+                {
+                    Type = ReferenceType.SecurityScheme,
+                    Id = JwtBearerDefaults.AuthenticationScheme,
+                },
+                Scheme = "oauth2",
+                Name = JwtBearerDefaults.AuthenticationScheme,
+                In = ParameterLocation.Header,
+            },
+            Array.Empty<string>()
+        },
+    });
 });
 
 builder.Services
@@ -189,6 +236,10 @@
 app.UseSwaggerUI(options =>
 {
     options.SwaggerEndpoint("/swagger/v1/swagger.json", "geopilot API v1.0");
+
+    options.OAuthClientId(builder.Configuration["Auth:ClientId"]);
+    options.OAuth2RedirectUrl($"{builder.Configuration["Auth:ApiOrigin"]}/swagger/oauth2-redirect.html");
+    options.OAuthUsePkce();
 });
 
 app.UseHttpsRedirection();

src/Geopilot.Api/appsettings.Development.json

@@ -1,7 +1,10 @@
 {
   "Auth": {
     "Authority": "http://localhost:4011/realms/geopilot",
-    "ClientId": "geopilot-client"
+    "ClientId": "geopilot-client",
+    "AuthorizationUrl": "http://localhost:4011/realms/geopilot/protocol/openid-connect/auth",
+    "TokenUrl": "http://localhost:4011/realms/geopilot/protocol/openid-connect/token",
+    "ApiOrigin": "https://localhost:7188"
   },
   "Logging": {
     "LogLevel": {