Solid-OIDC

Abstract

The Solid OpenID Connect (Solid-OIDC) specification defines how resource servers verify the identity of relying parties and end users based on the authentication performed by an OpenID provider. Solid-OIDC builds on top of OpenID Connect 1.0 for use within the Solid ecosystem.

Status of this document

This report was published by the Solid Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

1Introduction

This section is non-normative

The Solid project aims to change the way web applications work today to improve privacy and user control of personal data by utilizing current standards, protocols, and tools, to facilitate building extensible and modular decentralized applications based on Linked Data principles.

This specification is written for Authorization and Resource Server owners intending to implement Solid-OIDC. It is also useful to Solid application developers charged with implementing a Solid-OIDC client.

The OAuth 2.0 [RFC6749] and OpenID Connect Core 1.0 [OIDC-CORE] web standards were published in October 2012 and November 2014, respectively. Since publication they've seen rapid and widespread adoption across the industry, in turn gaining extensive "real-world" data and experience. The strengths of the protocols are now clear; however, in a changing eco-system where privacy and control of digital identities are becoming more pressing concerns, it is also clear that additional functionality is required.

The additional functionality documented herein aims to address:

1. Resource servers and their Authorization servers having no existing trust relationship with identity providers.

2. Ephemeral Clients as a first-order use-case.

2Terminology

This section is non-normative

This specification uses the terms "access token", "authorization server", "resource server" (RS), "token endpoint", "grant type", and "client" as defined by The OAuth 2.0 Authorization Framework [RFC6749].

Throughout this specification, we will use the term OpenID Provider (OP) in line with the terminology used in the Open ID Connect Core 1.0 specification (OIDC) [OIDC-CORE]. It should be noted that this is distinct from the entity referred to as an Authorization Server by the OAuth 2.0 Authorization Framework (OAuth) [RFC6749].

This specification also uses the following terms:

WebID as defined by [WEBID]

A WebID is a URI with an HTTP or HTTPS scheme which denotes an Agent (Person, Organization, Group, Device, etc.).

JSON Web Token (JWT) as defined by [RFC7519]

A string representing a set of claims as a JSON object that is encoded in a JWS or JWE, enabling the claims to be digitally signed or MACed and/or encrypted.

JSON Web Key (JWK) as defined by [RFC7517]

A JSON object that represents a cryptographic key. The members of the object represent properties of the key, including its value.

Demonstration of Proof-of-Possession at the Application Layer (DPoP) as defined by [DPOP]

A mechanism for sender-constraining OAuth tokens via a proof-of-possession mechanism on the application level.

DPoP Proof as defined by [DPOP]

A DPoP proof is a JWT that is signed (using JWS) using a private key chosen by the client.

Proof Key for Code Exchange (PKCE) as defined by [RFC7636]

An extension to the Authorization Code flow which mitigates the risk of an authorization code interception attack.

3Core Concepts

This section is non-normative

In a decentralized ecosystem, such as Solid, an OP may be an identity-as-a-service vendor or, at the other end of the spectrum, a user-controlled OP. In either case, the user may be authenticating from a browser or an application.

Therefore, this specification assumes the use of the Authorization Code Flow with PKCE, in accordance with OAuth and OIDC best practices. It is also assumed that there are no preexisting trust relationships with the OP. This means that client registration, whether dynamic, or static, is entirely optional.

4Basic Flow

This section is non-normative

Details of the flow are available in [SOLID-OIDC-PRIMER]

sequenceDiagram
  participant WebID as 👩 End-User's WebID Document
  participant OP as 👩 OpenID Provider
  participant ClientID as ⚙️ Client's ID Document
  participant C as ⚙️ Client
  participant RS as ☁️ Resource Server
  participant AS as ☁️ Authorization Server
  C ->> RS: unauthenticated request
  RS ->> C: 401 with a WWW-Authenticate HTTP header
  Note over C: 👩 User provides their WebID ⌨️
  C ->> WebID: get WebID document to discover OpenID Provider
  WebID ->> C: WebID document
  C ->> OP: start Authorization Code grant
  OP->> ClientID: get Client ID document
  ClientID->> OP: ClientID document
  Note over OP: compare redirect_uri
  OP ->> C: return Authorization Code
  C ->> OP: present Authorization Code and DPoP proof
  Note over OP:  ⚙️ Client is authenticated ✅
  OP ->> C: return DPoP bound OIDC ID Token
  Note over C: 👩 User is authenticated ✅
  C ->> AS: request Access Token and push solid Claim Token (including ID Token)
  AS ->> WebID: get WebID document to verify OpenID Provider
  WebID ->> AS: WebID document
  AS ->> OP: get OP's public key to verify ID Token (JWS)
  OP ->> AS: JWKS
  Note over AS: 👩 User and ⚙️ Client are authenticated ✅
  AS ->> C: provide Access Token
  C ->> RS: request with Access Token
  alt Token introspection
  RS ->> AS: token introspection request
  AS ->> RS: token introspection response
  else signed JWT
    Note over RS, AS: Verify AS signature
  end
  Note over RS: 👩 User and ⚙️ Client are authenticated ✅
  RS ->> C: representation

5Client Identifiers

OAuth and OIDC require the Client application to identify itself to the OP and RS by presenting a client identifier (Client ID). Solid applications SHOULD use a URI that can be dereferenced as a Client ID Document.

6WebID Profile

Dereferencing the WebID URL results in a WebID Profile.

?webid <http://www.w3.org/ns/solid/terms#oidcIssuer> ?iss .

7Requesting the WebID Claim using a Scope Value

Solid-OIDC uses scope values, as defined in [RFC6749] Section 3.3 and [OIDC-CORE] Section 5.4 to specify what information is made available as Claim Values.

Solid-OIDC defines the following scope value for use with claim requests:

webid

REQUIRED. This scope requests access to the End-User's webid Claim.

8Issuer Validation after receiving the Authorization Code

In accordance with Best Current Practice [RFC9700], defense against Mix-Up Attacks is required in Solid-OIDC as clients are expected to interact with more than one OP. To this end, this specification adopts the mechanism defined in [RFC9207].

The OP MUST include the iss query parameter alongside the authorization code when redirecting the user agent back to the Client's redirect_uri. The value of the iss parameter MUST be the Issuer Identifier of the OP, as defined in [OIDC-CORE].

Upon receiving the authorization response, the Client MUST validate the iss parameter:

• The Client MUST check for the presence of the iss parameter.

• The Client MUST verify that the iss value matches the Issuer Identifier of the OP to which the authorization request was sent.

If the iss parameter is missing or does not match the expected value, the Client MUST reject the response, MUST NOT exchange the authorization code for tokens, and SHOULD signal an error to the user.

9Token Instantiation

Assuming one of the following options

• Client ID and Secret, and valid DPoP Proof (for dynamic and static registration)

• Dereferencable Client Identifier with a proper Client ID Document and valid DPoP Proof (for a Solid client identifier)

the OP MUST return A DPoP-bound OIDC ID Token.

10Resource Access

11Solid-OIDC Conformance Discovery

An OpenID Provider that conforms to the Solid-OIDC specification MUST advertise it in the OpenID Connect Discovery 1.0 [OIDC-DISCOVERY] resource by including webid in its scopes_supported metadata property.

12Security Considerations

This section is non-normative

As this specification builds upon existing web standards, security considerations from OAuth, OIDC, PKCE, and the DPoP specifications may also apply unless otherwise indicated. The following considerations should be reviewed by implementors and system/s architects of this specification.

Some of the references within this specification point to documents with a Living Standard or Draft status, meaning their contents can still change over time. It is advised to monitor these documents, as such changes might have security implications.

In addition to above considerations, implementors should consider the Security Considerations in context of the Solid Protocol [SOLID-PROTOCOL].

13Privacy Considerations

14Acknowledgments

This section is non-normative

The Solid Community Group would like to thank the following individuals for reviewing and providing feedback on the specification (in alphabetical order):

Tim Berners-Lee, Justin Bingham, Sarven Capadisli, Aaron Coburn, Matthias Evering, Jamie Fiedler, Michiel de Jong, Ted Thibodeau Jr, Kjetil Kjernsmo, Mitzi László, Pat McBennett, Adam Migus, Jackson Morgan, Davi Ottenheimer, Justin Richer, severin-dsr, Henry Story, Michael Thornburgh, Emmet Townsend, Ruben Verborgh, Ricky White, Paul Worrall, Dmitri Zagidulin.

15Appendix A: Full JSON-LD context

The JSON-LD context is defined as:

{
  "@context": {
    "@version": 1.1,
    "@protected": true,
    "oidc": "http://www.w3.org/ns/solid/oidc#",
    "xsd": "http://www.w3.org/2001/XMLSchema#",
    "client_id": {
      "@id": "@id",
      "@type": "@id"
    },
    "client_uri": {
      "@id": "oidc:client_uri",
      "@type": "@id"
    },
    "logo_uri": {
      "@id": "oidc:logo_uri",
      "@type": "@id"
    },
    "policy_uri": {
      "@id": "oidc:policy_uri",
      "@type": "@id"
    },
    "tos_uri": {
      "@id": "oidc:tos_uri",
      "@type": "@id"
    },
    "redirect_uris": {
      "@id": "oidc:redirect_uris",
      "@type": "@id",
      "@container": [
        "@id",
        "@set"
      ]
    },
    "require_auth_time": {
      "@id": "oidc:require_auth_time",
      "@type": "xsd:boolean"
    },
    "default_max_age": {
      "@id": "oidc:default_max_age",
      "@type": "xsd:integer"
    },
    "application_type": {
      "@id": "oidc:application_type"
    },
    "client_name": {
      "@id": "oidc:client_name"
    },
    "contacts": {
      "@id": "oidc:contacts"
    },
    "grant_types": {
      "@id": "oidc:grant_types"
    },
    "response_types": {
      "@id": "oidc:response_types"
    },
    "scope": {
      "@id": "oidc:scope"
    },
    "token_endpoint_auth_method": {
      "@id": "oidc:token_endpoint_auth_method"
    }
  }
}

Conformance

References