Skip to content

LWS Authentication #43

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
acoburn merged 8 commits into from
Dec 18, 2025
Merged

LWS Authentication #43

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
c313b1a
Add core LWS Authentication requirements
acoburn Nov 14, 2025
56c808e
Add OpenID authentication suite
acoburn Nov 14, 2025
50f8bdf
Add SAML Authentication suite
acoburn Nov 14, 2025
1f38b74
Add self-signed CID-based authentication suite
acoburn Nov 14, 2025
e0f0943
Add did:key authentication suite
acoburn Nov 14, 2025
24fc1be
Formatting and grammar
acoburn Nov 24, 2025
ef1f4b9
Formatting changes
acoburn Nov 24, 2025
7120d43
Fix typo
acoburn Dec 15, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,13 +3,16 @@
This is the repository for lws-protocol. You're welcome to contribute! Let's make the Web rock our socks
off!
To see the most recent HTML rendered version of the specification from this repository can be found at the following:
* [LWS Protocol](https://w3c.github.io/lws-protocol/spec/)
* [LWS Protocol](https://w3c.github.io/lws-protocol/lws10-core/)


## (1.0) Specs:

- [core](lws10-core/)
- [authn-openid](lws10-authn-openid/)
- [`core`](lws10-core/): Core protocol
- [`authn-openid`](lws10-authn-openid/): OpenID Connect Authentication Suite
- [`authn-saml`](lws10-authn-saml/): SAML 2.0 Authentication Suite
- [`authn-ssi-cid`](lws10-authn-ssi-cid): Self-signed Controlled Identifier Authentication Suite
- [`authn-ssi-did-key`](lws10-authn-ssi-did-key): Self-signed `did:key` Authentication Suite


## Contribution Guidelines:
Expand Down
185 changes: 173 additions & 12 deletions lws10-authn-openid/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,25 +2,20 @@
<html lang="en">
<head>
<meta charset="utf-8">
<title>LWS Protocol</title>
<title>LWS Authentication Suite: OpenID Connect</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove"></script>
<link rel="stylesheet" href="local.css"/>
<script class='remove'>
// See https://respec.org/docs/ for how to configure ReSpec
var respecConfig = {
specStatus: "ED",
shortName: "lws-protocol",
shortName: "lws-authn-openid",
editors: [{
name: "Pierre-Antoine Champin"
}, {
name: "ericP"
}, {
name: "Jesse Wright"
}, {
name: "Erich Bremer"
name: "Aaron Coburn"
}],
github: "w3c/lws-protocol",
shortName: "authn-openid",
xref: ["web-platform"],
group: "lws",
};
Expand All @@ -29,7 +24,7 @@
<body>
<section id="abstract">
<p>
This document defines how to identify and validate end-user agents, enabling authorization claims to be enforced by Linked Web Storage Authorisation Servers.
This document defines an OpenID Connect-based authentication suite for the Linked Web Storage (LWS) protocol, enabling LWS applications to integrate with OpenID providers.
</p>
</section>
<section id="sotd">
Expand All @@ -41,12 +36,178 @@
<section id="introduction">
<h2>Introduction</h2>
<p>
This document defines a mechanism for identifying agents and end users that plan to interact with a linked web storage server.
This specification does not mandate a particular format for end-user credentials, though it does describe how existing identity systems can be used in conjunction with the linked web storage authorization framework.
OpenID Connect is a widely used mechanism for web-based authentication. This authentication suite describes how an OpenID provider can be used with Linked Web Storage-conforming applications.
</p>
</section>
<section id="conformance"></section>

<section id="terminology">
<h2>Terminology</h2>

<p>
The terms "authorization server" and "client" are defined by The OAuth 2.0 Authorization Framework [[!RFC6749]].
</p>

<p>
The terms "OpenID provider", "id token", "end-user", and "issuer" are defined by OpenID Connect Core 1.0 [[!OPENID-CONNECT-CORE]].
</p>

<p>
The term "openid connect discovery" is defined by OpenID Connect Discovery 1.0 [[!OPENID-CONNECT-DISCOVERY]].
</p>

<p>
The term "controlled identifier document" is defined by W3C Controlled Identifiers 1.0 [[!CID-1.0]].
</p>

<p>
The terms "JSON Web Token (JWT)" and "claim" are defined by JSON Web Token [[!RFC7519]].
</p>

<p>
The term "JSON Web Key (JWK)" is defined by JSON Web Key [[!RFC7517]].
</p>

<p>
The terms "end-user credential" and "authentication suite" are defined by Linked Web Storage Protocol [[!LWS-PROTOCOL]]
</p>
</section>

<section id="serialization">
<h2>End-User Credential Serialization</h2>

<p>
OpenID Connect defines a protocol for producing signed ID Tokens, which are used to describe an end-user.
An ID Token is serialized as a signed JSON Web Token (JWT). In order to use an ID Token as an LWS end-user credential,
the following additional requirements apply.
</p>

<ul>
<li>
The ID Token MUST NOT use "none" as the signing algorithm.
</li>

<li>
The ID Token MUST use the <code>sub</code> (subject) claim for the LWS subject identifier.
</li>

<li>
The ID Token MUST use the <code>iss</code> (issuer) claim for the LWS issuer identifier.
</li>

<li>
The ID Token MUST use the <code>azp</code> (authorized party) claim for the LWS client identifier.
</li>

<li>
Any audience restriction in the ID Token MUST use the <code>aud</code> (audience) claim.
The <code>aud</code> claim SHOULD include the client identifier and any additional target
audience such as an authorization server.
</li>
</ul>

<p>
An example ID Token that is also an LWS end-user credential is included below.
</p>

<pre id="example-id-token" class="example">
{
"typ": "JWT",
"kid": "12dbe73a",
"kty": "EC",
"alg": "ES256",
"crv": "P-256"
}
.
{
"sub": "https://id.example/end-user",
"iss": "https://openid.example",
"azp": "https://client.example/17da1b",
"aud": ["https://client.example/17da1b", "https://as.example"],
"iat": 1761313600,
"exp": 1761313900
}
.
signature
</pre>
</section>

<section id="validation">
<h2>End-User Credential Validation</h2>

<p>
For an ID Token to validate as an LWS end-user credential,
there must be a trust relationship between the verifier and the issuing party.
</p>

<p>
In the absence of a pre-existing trust relationship, the validator MUST dereference the <code>sub</code> (subject) claim in the end-user credential.
The resulting resource MUST be formatted as a valid controlled identifier document [[!CID-1.0]] with an <code>id</code> value equal to the subject identifier.
</p>

<p>
The verifier MUST use the subject's controlled identifier document to locate a service object whose <code>serviceEndpoint</code> value
is equal to the value of the <code>iss</code> claim from the end-user credential, and whose <code>type</code> value is equal to <code>https://www.w3.org/ns/lws#OpenIdProvider</code>.
The verifier MUST perform OpenID Connect Discovery to locate the public portion of the JSON Web Key (JWK) used to sign the end-user credential.
The JWT MUST be validated as described by OpenID Connect Core Section 3.1.3.7 [[!OPENID-CONNECT-CORE]].
</p>

<p>
This document also covers a variety of security, privacy, internationalization, and accessibility considerations for ecosystems that use the technologies described in this specification.
An example Controlled Identifier Document for an agent using OpenID Connect is included below.
</p>

<pre id="example-cid" class="example">
{
"@context": [
"https://www.w3.org/ns/cid/v1"
],
"id": "https://id.example/end-user",
"service": [{
"type": "https://www.w3.org/ns/lws#OpenIdProvider",
"serviceEndpoint": "https://openid.example"
}]
}
</pre>
</section>

<section id="token-type">
<h2>Token Type Identifier</h2>

<p>
An ID Token used as an end-user credential MUST use the <code>urn:ietf:params:oauth:token-type:id_token</code> URI when interacting with an authorization server.
</p>

</section>

<section id="security-considerations" class="informative">
<h2>Security Considerations</h2>

<p>
All security considerations described in "Best Current Practice for OAuth 2.0 Security" [[RFC9700]] and "OpenID Connect Core 1.0" Section 16 [[OPENID-CONNECT-CORE]] apply to this specification.
</p>

<p>
An OpenID provider should support a mechanism to restrict the audience of an end-user credential to a limited set of entities, including an authorization server.
One mechanism for achieving this is to use Resource Indicators for OAuth 2.0 [[RFC8707]].
A client in possession of an end-user credential with no audience restrictions should exchange this token for an equivalent audience-restricted token by using, for example, OAuth 2.0 Token Exchange [[RFC8693]].
</p>
Copy link
Member

@elf-pavlik elf-pavlik Nov 22, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure if I understand the intended flow here, I'm happy to work on a sequence diagram that could be used as non-normative reference at least for the conversation. Is the idea here that OP also implements Token Exchange and cilent can exchange token without audience restriction obtained via authorization code grant (for example with FedCM to improve UX) and later exchanges that token for audience restricted tokens without user interation needed? In that case wouldn't make sense that the OP is both iss and aud of the initial token obtained via authorization code flow? If I understand the direction correctly, this could possibly be an alternative to sender constrained tokens, with the trade-off that it requires more http requests to do all the token exchange with the OP.

Copy link
Member Author

@acoburn acoburn Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention is not that the OP also implements token exchange.

In the case that an OP does not issue audience constrained ID tokens, the idea is that there could be a token exchange mechanism in the user's trust domain (not at the same server). A similar mechanism is described at https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-01.html

Copy link
Member

@elf-pavlik elf-pavlik Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

https://www.ietf.org/archive/id/draft-ietf-oauth-identity-assertion-authz-grant-01.html#name-overview
It seems like IdP AS issues the Id Token and later exchanges it for ID-JAG, I guess the main point is that it is the same security domain as you said.

I like simple naming of the distinct

  • IdP Authorization Server
  • Resource Authorization Server

the second one I understand to be the one in #45

This draft seems very close to what I was asking for on GNAP mailing list back in 2021
https://mailarchive.ietf.org/arch/msg/txauth/nhV4f59Xf5EaZ8c-YjkWWN6oCr0/

I wasn't aware of this work, thanks for the pointer 🙏


<p>
An OpenID provider should provide support for "OAuth 2.0 Authorization Server Issuer Identification" [[RFC9207]] by including an <code>iss</code> parameter in the authorization response of an OAuth flow.
</p>

<p>
An OpenID provider should provide support for end-user logout, such as RP-Initiated Logout 1.0.
</p>

<p>
The issuer of an end-user credential is responsible for validating the client identifier.
The issuer may use mechanisms such as OAuth Client Metadata Document, OAuth 2.0 Client Id Prefix, or OpenID Federation.
Comment on lines +204 to +205
Copy link
Member

@elf-pavlik elf-pavlik Nov 22, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is there a plan to further specify this part? Does the current text mean that issuers have to implement all three mentioned mechanisms? I think there may need to be a MUST somewhere, otherwise client identifiers can't be relied on, at least in the open ecosystem. I don't suggest it being fully addressed in this PR, if desired I could create a dedicated issue to track it.

Copy link
Member Author

@acoburn acoburn Nov 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There is not currently a plan to further specify this part. This section only states that an issuer is responsible for verifying the client identifier. This list here is simply a non-exhaustive collection of examples. An issuer is under no obligation to implement any of these, certainly not all three. I do not believe there needs to be a MUST here: the details of the validation mechanism is out of scope of the LWS protocol.

</p>

<p>
It is recommended that OpenID providers support WebAuthn [[WEBAUTHN-3]] as a mechanism for authenticating users.
</p>
</section>
</body>
</html>
Loading