feat: Support PAT using client credentials

documentation/getting-started.md

@@ -84,6 +84,115 @@ It uses the CLI parameter `-a http://localhost:4000/` to inform the RS where it
 which internally sets the Components.js variable `urn:solid-server:uma:variable:AuthorizationServer`
 to the provided value.
 
+## Authenticating as Resource Owner
+
+There are some APIs on the AS where a Resource Owner (RO) has to identify themself.
+Specifically, the policy APIs, as described in the [policy management documentation](policy-management.md),
+and the client credentials API described further below.
+Two authentication methods are supported: OIDC tokens, both Solid and standard, and unsafe WebID strings.
+
+To use OIDC, the `Bearer` authorization scheme needs to be used, followed by the token.
+For example, `Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI...`.
+
+To directly pass a WebID, the `WebID` scheme can be used together with a URL encoded WebID.
+For example, `Authorization: WebID http%3A%2F%2Fexample.com%2Fprofile%2Fcard%23me`.
+No validation is performed in this case, so this should only be used for development and debugging purposes.
+
+## Authenticating as Resource Server
+
+The RS has to send several requests to the AS, as described below.
+Generally, these requests are done for a specific user,
+e.g., registering a resource for its owner,
+or requesting access on an owner's resource.
+To identify both itself and the owner,
+the RS has to send a Personal Access Token (PAT) in the authorization header
+when making such a request.
+As the UMA specification does not have strong requirements on how such a token should be generated,
+the specific implementation of our AS is described here.
+
+The following steps need to be taken:
+1. The owner requests client credentials from the AS for a specific RS, which is the client here,
+   as described in RFC 7591.
+2. The AS returns an id/secret combination which uniquely identifies this owner/RS combination.
+3. The owner provides this id/secret combination to the RS.
+4. Before making a request, the RS uses this id/secret combination to request an access token from the AS
+   with scope `uma_protection`, as described in RFC 6749 and RFC 7617.
+   This token is the PAT.
+5. The RS uses this bearer token for the request.
+
+### Requesting client credentials
+
+To register a RS, the owner should find the `registration_endpoint` API in the AS' UMA configuration.
+They should then POST a request there with a body as follows:
+```json
+{
+  "client_name": "descriptive name for the RS (optional)",
+  "client_uri": "http://localhost:3000"
+}
+```
+
+The AS will then respond with client credentials such as
+```json
+{
+  "client_uri": "http://localhost:3000",
+  "client_name": "descriptive name for the RS (optional)",
+  "client_id": "1be8b63f-29c2-4d2c-9932-8784a28de5cf",
+  "client_secret": "184984651984...",
+  "client_secret_expires_at": "0",
+  "grant_types": [ "client_credentials", "refresh_token" ],
+  "token_endpoint_auth_method": "client_secret_basic"
+}
+```
+
+This response, or at least the `client_id` and `client_secret` should then be passed along to the RS.
+
+### Sending the credentials to the RS (CSS specific)
+
+This section is specific for our CSS implementation of the RS
+and is irrelevant if you have your own custom RS.
+
+The implementation makes use of the
+[CSS account API](https://communitysolidserver.github.io/CommunitySolidServer/latest/usage/account/json-api/).
+A new `pat` entry has been added to the account controls after authenticating.
+This API expects a POST request with the following body:
+```json
+{
+  "id": "1be8b63f-29c2-4d2c-9932-8784a28de5cf",
+  "secret": "184984651984...",
+  "issuer": "http://localhost:4000/uma"
+}
+```
+Sending this request will update the stored credentials for the authenticated user.
+
+### Requesting a PAT as RS
+
+To request a PAT, the RS needs to find the `token_endpoint` API in the AS UMA config.
+A PAT can then be requested by sending a POST request with a `application/x-www-form-urlencoded` body as follows:
+```
+grant_type=client_credentials&scope=uma_protection
+```
+A JSON body containing the same information would also work.
+
+The important thing is that the `Authorization` header needs to be set using the Basic id/secret combination
+as described in RFC 7617.
+Specifically, that means you generate a string `$MY_ID:$MY_secret` and generating the base 64 encoding of this result.
+The Authorization header should then contain `Basic $ENCODED_RESULT`.
+
+The AS will then respond with a body containing the generated access token:
+```json
+{
+  "access_token": "eyJhbGciOi...",
+  "refresh_token":  "efe2dea0-9cb4-4ffd-9dbe-a581a249202b",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "uma_protection"
+}
+```
+
+This access token then needs to be sent along in a Bearer Authorization header when making the necessary requests.
+The current implementation of the AS allows the PAT to be reused until it is expired,
+which can be useful when doing bulk resource registration.
+
 ## Resource registration
 
 The Federated UMA specification requires that the RS registers every resource at the AS.

documentation/policy-management.md

@@ -16,21 +16,12 @@ The current implementation supports the following requests on the UMA server:
 These requests comply with some restrictions:
 
 - When the URL contains a policy ID, it must be URI encoded.
-- Every request requires a valid Authorization header, which is detailed below.
+- Every request requires a valid Authorization header.
 
-### Authorization
-
-The policy API supports similar authentication tokens as the UMA API,
-but expects them in the Authorization header,
-as the body is already used for other purposes.
-Two authorization methods are supported: OIDC tokens, both Solid and standard, and unsafe WebID strings.
-
-To use OIDC, the `Bearer` authorization scheme needs to be used, followed by the token.
-For example, `Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI...`.
+### Authentication
 
-To directly pass a WebID, the `WebID` scheme can be used together with a URL encoded WebID.
-For example, `Authorization: WebID http%3A%2F%2Fexample.com%2Fprofile%2Fcard%23me`.
-No validation is performed in this case, so this should only be used for development and debugging purposes.
+The client is expected to use the authentication method
+described in the [getting started documentation](getting-started.md).
 
 ### Creating policies
 

packages/css/config/init-pat.json

@@ -0,0 +1,33 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solidlab/uma-css/^0.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/asynchronous-handlers/^1.0.0/components/context.jsonld"
+  ],
+  "@graph": [
+    {
+      "comment": "Automatically registers a PAT for every account on server start"
+    },
+    {
+      "@id": "urn:solid-server:default:PatSeedRegistrar",
+      "@type": "PatSeedRegistrar",
+      "accountStorage": { "@id": "urn:solid-server:default:AccountStorage" },
+      "accountStore": { "@id": "urn:solid-server:default:AccountStore" },
+      "umaClient": { "@id": "urn:solid-server:default:UmaClient" },
+      "patUpdater": { "@id": "urn:solid-server:default:PatUpdater" }
+    },
+    {
+      "comment": "The PatSeedRegistrar is added to the list of Initializers so Components.js finds and instantiate it.",
+      "@id": "urn:solid-server:default:PrimaryParallelInitializer",
+      "@type": "ParallelHandler",
+      "handlers": [{ "@id": "urn:solid-server:default:PatSeedRegistrar" }]
+    },
+    {
+      "@id": "urn:solid-server:default:StatusDependantServerConfigurator",
+      "@type": "StatusDependantServerConfigurator",
+      "dependants": [
+        { "@id": "urn:solid-server:default:PatSeedRegistrar" }
+      ]
+    }
+  ]
+}

packages/css/config/seed.json

@@ -4,7 +4,10 @@
     "password": "abc123",
     "pods": [{
       "name": "alice"
-    }]
+    }],
+    "authz": {
+      "server": "http://localhost:4000/uma"
+    }
   },
   {
     "email": "bob@example.org",
@@ -13,7 +16,10 @@
       {
         "name": "bob"
       }
-    ]
+    ],
+    "authz": {
+      "server": "http://localhost:4000/uma"
+    }
   },
   {
     "email": "demo@example.org",
@@ -22,7 +28,10 @@
       {
         "name": "demo"
       }
-    ]
+    ],
+    "authz": {
+      "server": "http://localhost:4000/uma"
+    }
   },
   {
     "email": "resources@example.org",
@@ -31,6 +40,9 @@
       {
         "name": "resources"
       }
-    ]
+    ],
+    "authz": {
+      "server": "http://localhost:4000/uma"
+    }
   }
 ]

packages/css/config/uma/default.json

@@ -12,10 +12,10 @@
     "uma-css:config/uma/overrides/token-extractor.json",
     "uma-css:config/uma/overrides/www-auth.json",
 
-    "uma-css:config/uma/parts/cli.json",
     "uma-css:config/uma/parts/client.json",
     "uma-css:config/uma/parts/fetcher.json",
     "uma-css:config/uma/parts/owner-util.json",
+    "uma-css:config/uma/parts/pat.json",
     "uma-css:config/uma/parts/resource-registrar.json",
     "uma-css:config/uma/parts/server-configurator.json"
   ]

packages/css/config/uma/parts/client.json

@@ -16,7 +16,8 @@
         "@id": "urn:solid-server:default:UmaFetcher"
       },
       "identifierStrategy": { "@id": "urn:solid-server:default:IdentifierStrategy" },
-      "resourceSet": { "@id": "urn:solid-server:default:CachedResourceSet" }
+      "resourceSet": { "@id": "urn:solid-server:default:CachedResourceSet" },
+      "baseUrl":{ "@id": "urn:solid-server:default:variable:baseUrl" }
     }
   ]
 }

packages/css/config/uma/parts/fetcher.json

@@ -10,16 +10,11 @@
       "fetcher": {
         "@type": "RetryingFetcher",
         "fetcher": {
-          "@type": "SignedFetcher",
-          "fetcher": {
-            "@type": "BaseFetcher"
-          },
-          "baseUrl": { "@id": "urn:solid-server:default:variable:baseUrl" },
-          "keyGen": { "@id": "urn:solid-server:default:JwkGenerator" }
+          "@type": "BaseFetcher"
         },
         "retries": 150,
         "exponent": 3,
-        "retryOn": [401, 500]
+        "retryOn": [500]
       }
     }
   ]

packages/css/config/uma/parts/owner-util.json

@@ -8,14 +8,17 @@
       "comment": "Provides utility for interacting with pod owner metadata",
       "@id": "urn:solid-server:default:OwnerUtil",
       "@type": "OwnerUtil",
+      "accountStorage": {
+        "@id": "urn:solid-server:default:AccountStorage"
+      },
+      "accountStore": {
+        "@id": "urn:solid-server:default:AccountStore"
+      },
       "podStore": {
         "@id": "urn:solid-server:default:PodStore"
       },
       "storageStrategy": {
         "@id": "urn:solid-server:default:StorageLocationStrategy"
-      },
-      "umaServerURL": {
-        "@id": "urn:solid-server:uma:variable:AuthorizationServer"
       }
     }
   ]

packages/css/config/uma/parts/pat.json

@@ -0,0 +1,48 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solid/community-server/^8.0.0/components/context.jsonld",
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solidlab/uma-css/^0.0.0/components/context.jsonld"
+  ],
+  "@graph": [
+    {
+      "@id": "urn:solid-server:default:AccountPatRouter",
+      "@type": "AuthorizedRouteHandler",
+      "route": {
+        "@id": "urn:solid-server:default:AccountPatRoute",
+        "@type": "RelativePathInteractionRoute",
+        "base": { "@id": "urn:solid-server:default:AccountIdRoute" },
+        "relativePath": "pat/"
+      },
+      "source": {
+        "@type": "ViewInteractionHandler",
+        "source": {
+          "@id": "urn:solid-server:default:PatUpdateHandler",
+          "@type": "PatUpdateHandler",
+          "patUpdater": {
+            "@id": "urn:solid-server:default:PatUpdater",
+            "@type": "PatUpdater",
+            "accountStore": { "@id": "urn:solid-server:default:AccountStore" },
+            "podStore": { "@id": "urn:solid-server:default:PodStore" },
+            "resourceStore": { "@id": "urn:solid-server:default:ResourceStore" },
+            "umaClient": { "@id": "urn:solid-server:default:UmaClient" }
+          }
+        }
+      }
+    },
+
+    {
+      "@id": "urn:solid-server:default:InteractionRouteHandler",
+      "@type": "StatusWaterfallHandler",
+      "handlers": [{ "@id": "urn:solid-server:default:AccountPatRouter" }]
+    },
+
+    {
+      "@id": "urn:solid-server:default:AccountControlHandler",
+      "@type": "ControlHandler",
+      "controls": [{
+        "ControlHandler:_controls_key": "pat",
+        "ControlHandler:_controls_value": { "@id": "urn:solid-server:default:AccountPatRoute" }
+      }]
+    }
+  ]
+}

packages/css/package.json

@@ -57,11 +57,11 @@
     "build": "yarn build:ts && yarn build:components",
     "build:ts": "yarn run -T tsc",
     "build:components": "yarn run -T componentsjs-generator -r uma-css -s src/ -c dist/components -i .componentsignore --lenient",
-    "start:unseeded": "yarn run community-solid-server -m . -c ./config/default.json -a http://localhost:4000/",
-    "start": "yarn run community-solid-server -m . -c ./config/default.json --seedConfig ./config/seed.json -a http://localhost:4000/",
+    "start:unseeded": "yarn run community-solid-server -m . -c ./config/default.json",
+    "start": "yarn run community-solid-server -m . -c ./config/default.json ./config/init-pat.json  --seedConfig ./config/seed.json",
     "demo": "yarn run demo:setup && yarn run demo:start",
     "demo:setup": "yarn run -T shx rm -rf ./tmp && yarn run -T shx cp -R ../../demo/data ./tmp",
-    "demo:start": "yarn run community-solid-server -m . -c ./config/demo.json -f ./tmp -a http://localhost:4000/"
+    "demo:start": "yarn run community-solid-server -m . -c ./config/demo.json ./config/init-pat.json -f ./tmp"
   },
   "dependencies": {
     "@solid/community-server": "^8.0.0-alpha.1",