diff --git a/lws10-core/Authorization.html b/lws10-core/Authorization.html new file mode 100644 index 0000000..03ea254 --- /dev/null +++ b/lws10-core/Authorization.html @@ -0,0 +1,338 @@ +

+ Linked Web Storage describes a mechanism for persisting and managing protected data on the Web. Authorization is the mechanism + by which agents request and present access tokens in order to access this protected data. +

+ +
+

Roles

+ +

+ The roles in LWS authorization are the same as those defined by OAuth 2.0 Section 1.1 [[!RFC6749]]: +resource owner, +resource server, +client (called in this specification authorization client to avoid ambiguity), and +authorization server. + A storage server is a type of resource server that also conforms to the LWS storage specification. +

+
+ +
+ +

Protocol Flow

+ +

+ This specification describes the interaction between a client and an authorization server as well as + the interaction between a client and a conforming storage server. +

+ +

+ The interaction between the authorization server and the storage server is out of scope of this specification. + The authorization server may be the same server as the storage server or it may be a separate entity. +

+ +
+

Authorization Server Discovery

+ +

+ All protected resources managed by a storage server require a valid access token, generated by a trusted + authorization server. A client can discover the location of a trusted authorization server by making an + unauthorized HTTP request to a protected resource. +

+ +

+ A storage server generating a 401 (Unauthorized) response MUST send a WWW-Authenticate header + field containing at least one conforming challenge. A conforming challenge will include the parameters described below: +

+ + + +

+ Other headers and parameters MAY be included. +

+ +

+ An example 401 response is included below. +

+ + 
+HTTP/2 401 Unauthorized
+Link: ; rel="storageDescription"
+WWW-Authenticate: Bearer as_uri="https://authorization.example",
+                realm="https://storage.example/storage_1",
+                error="invalid_token"
+
+
+ +
+

Authorization Server Metadata

+ +

+ An authorization server MUST provide a metadata resource to allow clients to discover endpoint locations and capabilities as described + in [[!RFC8414]]. This metadata resource MUST be available at a URL with the path /.well-known/lws-configuration. +

+ +

+ An authorization server SHOULD advertise the subject tokens that it supports by including a subject_token_types_supported + entry in the server metadata document. This entry is a JSON array containing a list of valid subject_token_type values + that can be supplied at the authorization server's token endpoint. +

+ +

+ An example authorization server metadata resource is included below. +

+ + 
+{
+    "issuer": "https://authorization.example",
+    "grant_types_supported": [
+        "urn:ietf:params:oauth:grant-type:token-exchange"],
+    "token_endpoint": "https://authorization.example/token",
+    "jwks_uri": "https://authorization.example/jwks",
+    "claims_supported": [
+        "sub",
+        "iss",
+        "client_id",
+        "aud"],
+    "response_types_supported": [
+        "token"],
+    "subject_token_types_supported": [
+        "urn:ietf:params:oauth:token-type:jwt",
+        "urn:ietf:params:oauth:token-type:id-token"]
+}
+
+ +
+ +
+

Token Exchange

+ +

+ An LWS authorization server is a conforming OAuth 2.0 authorization server, capable of issuing access tokens to a client + for use with a storage server. In order to issue an access token, a client must first present a valid subject token, + such as an end-user credential, to the authorization server via OAuth 2.0 Token Exchange [[!RFC8693]]. +

+ +
+ +
Request
+ +

+ The authorization server's token endpoint MUST support the urn:ietf:params:oauth:grant-type:token-exchange + grant type, as described in OAuth 2.0 Token Exchange [[!RFC8693]]. +

+ +

+ When performing the token exchange grant type, the following additional requirements apply: +

+ +
    +
  • The resource parameter is REQUIRED. The value of this parameter MUST be an absolute URI and will be used to populate the + aud (audience) claim in the resulting access token. The supplied value will be the same as the + realm parameter response in a WWW-Authenticate challenge. The authorization server + MUST reject any request in which the resource parameter identifies an unknown or untrusted storage. +
    • + +
  • + The subject_token parameter is REQUIRED. The value of this parameter MUST include a valid subject token, + such as an end-user credential. +
    • + +
  • + Before returning an access token to the client, the authorization server MUST successfully validate all presented tokens. +
    • +
+ +

+ Non-normative example of a token request (the subject_token parameter has been truncated). +

+ + 
+POST /token HTTP/1.1
+Host: authorization.example
+Content-Type: application/x-www-form-urlencoded
+
+grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Atoken-exchange
+&resource=https%3A%2F%2Fstorage.example%2Fstorage_1
+&subject_token=eyJ0eXAiOiJhcytqd3QiLCJhbGciO...fiK51VwhsxJ-siBMR-YFiA
+&subject_token_type=urn%3Aietf%3Aparams%3Aoauth%3Atoken-type%3Aid_token
+
+
+ +
+
Response
+ +

+ If the token request is valid and the client is authorized to make the request, the authorization server response MUST + conform to Section 5.1 from the OAuth 2.0 Authorization Framework [[!RFC6749]]. The resulting access token MUST conform + to the JSON Web Token Profile for OAuth 2.0 Access Tokens [[!RFC9068]]. +

+ +

+ In addition, the access token must meet the following requirements: +

+ +
    +
  • + sub (subject) — REQUIRED. This claim MUST be an absolute URI identifying the agent performing the operation +
    • +
  • + iss (issuer) — REQUIRED. This claim MUST be the absolute URI of the authorization server +
    • +
  • + client_id (client id) — REQUIRED. This claim MUST be an absolute URI identifying the client. +
    • +
  • + aud (audience) — REQUIRED. This claim MUST include the absolute URI supplied by the client + in the resource parameter. This value will be used to restrict the entities for which the access token is valid. This will + be the same value as provided by a storage server in the realm parameter of a WWW-Authenticate challenge. +
    • +
  • + exp (expiration) — REQUIRED. Authorization servers SHOULD issue tokens with short lifetimes + (RECOMMENDED: 300 seconds or less) to limit exposure from token theft. +
    • +
  • + iat (issued at) — REQUIRED. +
    • +
  • + jti (JWT ID) — REQUIRED. +
    • +
+ +

+ A non-normative example of a successful token response is included below. +

+ + 
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+    "access_token":"eyJ0eXAiOiJhcytqd3QiLCJhbGciOiJFUzI1NiIs...DeWt4QuZXso",
+    "token_type":"Bearer",
+    "expires_in":3600
+}
+
+ +

+ All invalid or unauthorized requests MUST result in an error response as described in Section 5.2 in + the OAuth 2.0 Authorization Framework [[!RFC6749]]. +

+ + 
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+    "error":"invalid_request"
+}
+
+
+ +
+
Example access token
+ +

+ An example access token issued by an authorization server is included below. +

+ + 
+{
+  "kid": "ec51c6b2",
+  "kty": "EC",
+  "alg": "ES256",
+  "crv": "P-256",
+  "typ": "at+jwt"
+}
+.
+{
+  "sub": "https://id.example/agent",
+  "iss": "https://authorization.example",
+  "client_id": "https://app.example/id",
+  "aud": "https://storage.example",
+  "exp": 1735686300,
+  "iat": 1735686000,
+  "jti": "550e8400-e29b-41d4-a716-446655440000"
+}
+.
+signature
+
+
+
+
+

Token Validation by a Storage Server

+ +

+ Once a client is in possession of an access token, it will present this token to a storage server. + The storage server is responsible for verifying this token before performing any operation. +

+ +
+
Presentation
+ +

+ A client MUST present an access token to a storage server using the Authorization header + with an authentication scheme as defined in [[!RFC6750]]. +

+ + 
+Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...
+
+
+ +
+
Validation
+ +

+ A storage server MUST validate an access token by performing the following checks, rejecting the request upon any failure: +

+ +
    +
  • + JWT Signature Validation: Verify the JWT signature using the authorization server's public key retrieved from the + jwks_uri specified in the authorization server metadata. Storage servers SHOULD cache these keys and + MUST support key rotation. +
    • +
  • + Issuer Validation: Verify the iss claim matches the expected authorization server identifier. +
    • +
  • + Audience Validation: Verify the aud claim contains exactly one value and this value is an absolute URI identifying the storage server which logically contains the target resource. +
    • +
  • + Temporal Validation, subject to an allowable clock skew between systems. +
      +
    • + Verify the current time is before the exp (expiration) claim. +
      • +
    • + Verify the current time is not before the nbf (not before) claim, if present. +
      • +
    • + Verify that the iat (issued at) claim is not in the future. +
      • +
    +
    • +
+ +

+ If validation fails, the storage server MUST return 401 Unauthorized with a WWW-Authenticate header + containing an appropriate error parameter (e.g., invalid_token, invalid_request, or insufficient_scope). +

+ +

+ If the token is otherwise valid but an authorization policy does not allow the requested operation, + the storage server MUST reject the request. +

+
+
+
diff --git a/lws10-core/IANA-Considerations.html b/lws10-core/IANA-Considerations.html new file mode 100644 index 0000000..4559673 --- /dev/null +++ b/lws10-core/IANA-Considerations.html @@ -0,0 +1,45 @@ +
+

well-known URI Registry

+ +

+ This specification adds the following value to the "Well-Known URIs" registry [[IANA.well-known]] established by RFC 5785 [[RFC5785]]. +

+ + +
+ +
+

OAuth Authorization Server Metadata Registry

+ +

+ This specification adds the following value to the "OAuth Authorization Server Metadata" registry [[IANA.OAuth.Parameters]] established by [[RFC8414]]. +

+ + +
diff --git a/lws10-core/Privacy-Considerations.html b/lws10-core/Privacy-Considerations.html new file mode 100644 index 0000000..a74ca68 --- /dev/null +++ b/lws10-core/Privacy-Considerations.html @@ -0,0 +1,20 @@ +
+

Authorization Privacy

+ +

+ Minimal Disclosure: Authorization servers SHOULD issue tokens containing only information necessary for + authorization. Avoid including sensitive subject attributes unless required. +

+ +

+ Logging: Implementations SHOULD NOT log full token contents. If logging is necessary, tokens should be truncated or hashed. +

+ +

+ When using pseudonymous identifiers in JWTs, client applications SHOULD request a batch issuance of JWTs and each JWT SHOULD be used only one + time against the storage server. This makes it harder for a storage server to use pseudonymous identifiers to correlate requests. + This does not prevent the storage server from using other information such as similarities in JWT content or originating IP address + to correlate requests. When using pseudonymous identifiers, the authorization server SHOULD NOT issue the same pseudonymous identifier + more than once. +

+
diff --git a/lws10-core/Security-Considerations.html b/lws10-core/Security-Considerations.html new file mode 100644 index 0000000..d516a13 --- /dev/null +++ b/lws10-core/Security-Considerations.html @@ -0,0 +1,49 @@ +
+

Authorization Security

+ +

+ The recommendations described in Best Current Practice for OAuth 2.0 Security [[!RFC9700]] apply to this specification. +

+ +
+

Transport Security

+ +

+ An Authorization Server implementation MUST support TLS. When using TLS, the client MUST perform a TLS/SSL server certificate check, per RFC 6125 [[!RFC6125]]. + Implementation security considerations can be found in "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)" [[!BCP195]]. +

+
+ +
+

Token Security

+ +

+ Bearer tokens are vulnerable to theft and replay. Required mitigations include: +

+ + +
+ +
+

End-User Credential Protection

+ +

+ End-user credentials with unrestricted audiences MUST NOT be provided to untrusted authorization servers. +

+ +

+ If an end-user credential issuer is unable to restrict the audience of a token, clients SHOULD use a mechanism + such as OAuth 2.0 Token Exchange [[!RFC8693]] to create audience-restricted credentials before interacting with authorization servers. +

+
+
diff --git a/lws10-core/index.html b/lws10-core/index.html index e35b7f5..e5328e0 100644 --- a/lws10-core/index.html +++ b/lws10-core/index.html @@ -198,49 +198,10 @@

Authentication

- +

Authorization

-

- A resource manager dicates the requesting agents, eiher directly, by listing them in a strawman-ACLs document: -

- 
-[]
-  a straw:AccessControlResource ;
-  straw:resource ex:myServedResource ;
-  straw:accessControl [
-    a straw:AccessControl ;
-    straw:apply [
-      a straw:Policy ;
-      straw:allow acl:Read ;
-      straw:anyOf [
-        a straw:Matcher ;
-        straw:agent ex:RequestingAgent1, ex:RequestingAgent2 ;
-      ]
-    ]
-  ] .
-
- -

- Or by deferring to a trusted authorization server as in this strawman-ACLs document: -

- 
-[]
-  a straw:AccessControlResource ;
-  straw:resource ex:myServedResource ;
-  straw:accessControl [
-    a straw:AccessControl ;
-    straw:apply [
-      a straw:Policy ;
-      straw:allow acl:Read ;
-      straw:anyOf [
-        a straw:Matcher ;
-        straw:authorizer ex:AutorServer3 ;
-      ]
-    ]
-  ] .
-
- +
@@ -384,7 +345,7 @@

Security Considerations

Formal security considerations section covering threat models, security requirements, and implementation guidance for secure LWS deployments.

-
+
@@ -392,7 +353,12 @@

Privacy Considerations

Privacy implications of the LWS Protocol, including data minimization, user consent, and privacy-preserving implementation patterns.

-
+
+
+ +
+

IANA Considerations

+