Solid-OIDC

Editor’s Draft,

More details about this document
This version:
https://solid.github.io/solid-oidc/
Test Suite:
https://solid.github.io/solid-oidc-tests/
Issue Tracking:
GitHub
Editors:
Aaron Coburn (Inrupt)
elf Pavlik
Dmitri Zagidulin
Former Editors:
Adam Migus (The Migus Group)
Ricky White (The Migus Group)

Abstract

A key challenge on the path toward re-decentralizing user data on the Worldwide Web is the need to access multiple potentially untrusted resources servers securely. This document aims to address that challenge by building on top of current and future web standards, to allow entities to authenticate within a Solid ecosystem.

Status of this document

This section describes the status of this document at the time of its publication.

This document was published by the Solid Community Group as an Editor’s Draft. The sections that have been incorporated have been reviewed following the Solid process. However, the information in this document is still subject to change. You are invited to contribute any feedback, comments, or questions you might have.

Publication as an Editor’s Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

1. Introduction

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.

1.1. Out of Scope

This section is non-normative

At the time of writing, there is no demonstrated use case for a strongly asserted identity; however, it is likely that authorization requirements will necessitate it.

2. Terminology

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 Identity Provider (IdP) 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.

3. Core Concepts

This section is non-normative

In a decentralized ecosystem, such as Solid, an IdP may be an identity-as-a-service vendor or, at the other end of the spectrum, a user-controlled IdP. In any 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 IdP. This means that client registration, whether dynamic, or static, is entirely optional.

3.1. WebIDs

This section is non-normative

In line with Linked Data principles, a WebID is a HTTP URI that, when dereferenced, resolves to a profile document that is structured data in an RDF 1.1 format. This profile document allows people to link with others to grant access to identity resources as they see fit. WebIDs underpin Solid and are used as a primary identifier for Users in this specification.

4. Basic Flow

This section is non-normative

Details of the flow are available in [Solid.OIDC.Primer]

Basic sequence of authenticating the user and the client.

5. Client Identifiers

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

5.1. Client ID Document

When a Client Identifier is dereferenced, the resource MUST be serialized as an application/ld+json document unless content negotiation requires a different outcome.

The serialized JSON form of a Client ID Document SHOULD use the normative JSON-LD @context provided at https://www.w3.org/ns/solid/oidc-context.jsonld such that the resulting document produces a JSON serialization of an OIDC client registration, per the definition of client registration metadata from [RFC7591] section 2.

Also, the IdP MUST dereference the Client ID Document and match any Client-supplied parameters with the values in the Client ID Document.

Further, the redirect_uri provided by the Client MUST be included in the registration redirect_uris list.

This example uses JSON-LD for the Client ID Document:

https://app.example/id

{
  "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld",

  "client_id": "https://app.example/id",
  "client_name": "Solid Application Name",
  "redirect_uris": ["https://app.example/callback"],
  "post_logout_redirect_uris": ["https://app.example/logout"],
  "client_uri": "https://app.example/",
  "logo_uri" : "https://app.example/logo.png",
  "tos_uri" : "https://app.example/tos.html",
  "scope" : "openid profile offline_access webid",
  "grant_types" : ["refresh_token","authorization_code"],
  "response_types" : ["code"],
  "default_max_age" : 3600,
  "require_auth_time" : true
}

5.1.1. JSON-LD context

This specification defines a JSON-LD context for use with OIDC Client ID Documents. This context is available at https://www.w3.org/ns/solid/oidc-context.jsonld. Client ID Documents that reference this JSON-LD context MUST use the HTTPS scheme.

NOTE: the oidc vocabulary that is part of this context uses the HTTP scheme.

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"
      ]
    },
    "post_logout_redirect_uris": {
      "@id": "oidc:post_logout_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"
    }
  }
}

5.2. OIDC Registration

If the Client does not use an identifier that can be dereferenced, then it MUST present a client identifier registered with the IdP via either OIDC dynamic or static registration. See also [OIDC.DynamicClientRegistration].

6. Requesting the WebID Claim using a Scope Value

In OpenID Connect, scope values are used to request that particular information be make 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.

7. Token Instantiation

Assuming one of the following options

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

7.1. DPoP-bound OIDC ID Token

When requesting a DPoP-bound OIDC ID Token, the Client MUST send a DPoP proof JWT that is valid according to the OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP) § section-5. The DPoP proof JWT is used to bind the OIDC ID Token to a public key. See also: [DPOP].

With the webid scope, the DPoP-bound OIDC ID Token payload MUST contain these claims:

An example OIDC ID Token:

{
    "webid": "https://janedoe.com/web#id",
    "iss": "https://idp.example.com",
    "sub": "janedoe",
    "aud": ["https://client.example.com/web#id", "solid"],
    "azp": "https://client.example.com/web#id",
    "iat": 1311280970,
    "exp": 1311281970,
    "cnf":{
      "jkt":"0ZcOCORZNYy-DWpqq30jZyJGHTN0d2HglBV3uiguA4I"
    }
}

8. Resource Access

8.1. Authorization Server Discovery

When a Client performs an unauthenticated request to a protected resource, the Resource Server MUST respond with the HTTP 401 status code, and a WWW-Authenticate HTTP header. See also: Hypertext Transfer Protocol (HTTP/1.1): Authentication § section-4.1

The WWW-Authenticate HTTP header MUST include an as_uri parameter unless the authentication scheme requires a different mechanism for discovering an associated authorization server.

Authorization Servers SHOULD implement User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization [UMA].

8.2. Obtaining an Access Token

For Authorization Servers that conform to [UMA], the http://openid.net/specs/openid-connect-core-1_0.html#IDToken profile MUST be supported. This profile MUST be advertised in the uma_profiles_supported metadata of the Authorization Server discovery document User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization § rfc.section.2.

When using the http://openid.net/specs/openid-connect-core-1_0.html#IDToken profile with an UMA-based Authorization Server, the Authorization Server MUST be capable of exchanging a valid Solid-OIDC ID Token § 7.1 DPoP-bound OIDC ID Token for an OAuth 2.0 Access Token.

Note: Clients can push additional claims by requesting an upgraded RPT User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization § rfc.section.3.3.1

8.3. DPoP Proof Validation

A DPoP Proof that is valid according to DPoP Internet-Draft, Section 4.3, MUST be present when a DPoP-bound OIDC ID Token is used.

8.4. OIDC ID Token Validation

The DPoP-bound OIDC ID Token MUST be validated according to DPoP Internet-Draft, Section 6, but the AS MAY perform additional verification in order to determine whether to grant access to the requested resource.

The user’s WebID in the webid claim MUST be dereferenced and checked against the iss claim in the OIDC ID Token. If the iss claim is different from the domain of the WebID, then the AS MUST check the WebID document for the existence of a statement matching ?webid <http://www.w3.org/ns/solid/terms#oidcIssuer> ?iss., where ?webid and ?iss are the values of the webid and iss claims respectively. This prevents a malicious identity provider from issuing valid OIDC ID Tokens for arbitrary WebIDs.

Unless the AS acquires IdP keys through some other means, or the AS chooses to reject tokens issued by this IdP, the AS MUST follow OpenID Connect Discovery 1.0 [OIDC.Discovery] to find an IdP’s signing keys (JWK).

8.4.1. WebID Issuer Discovery via Link Headers

A server hosting a WebID document MAY transmit the http://www.w3.org/ns/solid/terms#oidcIssuer values via Link Headers but it MUST be the same as in the RDF representation. A client MUST treat the RDF in the body of the WebID document as canonical but MAY use the Link Header values as an optimization.

Link: <https://oidc.example>; rel="http://www.w3.org/ns/solid/terms#oidcIssuer"; anchor="#id"

9. Solid-OIDC Conformance Discovery

An Identity Provider that conforms to the Solid-OIDC specification MUST advertise this in the OpenID Connect Discovery 1.0 [OIDC.Discovery] resource. An Identity Provider would indicate this support by including webid in the scopes_supported metadata property.

{
    "scopes_supported": ["openid", "offline_access", "webid"]
}

10. Security 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].

10.1. TLS Requirements

All TLS requirements outlined in [BCP195] apply to this specification.

All tokens, Client, and User credentials MUST only be transmitted over TLS.

10.2. Client IDs

An AS SHOULD assign a fixed set of low trust policies to any client identified as anonymous.

Implementors SHOULD expire ephemeral Client IDs that are kept in server storage to mitigate the potential for a bad actor to fill server storage with unexpired or otherwise useless Client IDs.

10.3. Client Secrets

Client secrets SHOULD NOT be stored in browser local storage. Doing so will increase the risk of data leaks should an attacker gain access to Client credentials.

10.4. Client Trust

This section is non-normative

Clients are ephemeral, client registration is optional, and most Clients cannot keep secrets. These, among other factors, are what makes Client trust challenging.

11. Privacy Considerations

11.1. OIDC ID Token Reuse

This section is non-normative

With JWTs being extendable by design, there is potential for a privacy breach if OIDC ID Tokens get reused across multiple authorization servers. It is not unimaginable that a custom claim is added to the OIDC ID Token on instantiation. This addition may unintentionally give other authorization servers consuming the OIDC ID Token information about the user that they may not wish to share outside of the intended AS.

12. Acknowledgments

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.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.

References

Normative References

[DPOP]
D. Fett; et al. OAuth 2.0 Demonstration of Proof-of-Possession at the Application Layer (DPoP). URL: https://tools.ietf.org/html/draft-ietf-oauth-dpop-04
[OIDC.Core]
N. Sakimura; et al. OpenID Connect Core 1.0. URL: https://openid.net/specs/openid-connect-core-1_0.html
[OIDC.Discovery]
N. Sakimura; et al. OpenID Connect Discovery 1.0. URL: https://openid.net/specs/openid-connect-discovery-1_0.html
[OIDC.DynamicClientRegistration]
N. Sakimura; J. Bradley; M.B. Jones. OpenID Connect Dynamic Client Registration 1.0. URL: https://openid.net/specs/openid-connect-registration-1_0.html
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[RFC6749]
D. Hardt, Ed.. The OAuth 2.0 Authorization Framework. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749
[RFC7517]
M. Jones. JSON Web Key (JWK). May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7517
[RFC7519]
M. Jones; J. Bradley; N. Sakimura. JSON Web Token (JWT). May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7519
[RFC7591]
J. Richer, Ed.; et al. OAuth 2.0 Dynamic Client Registration Protocol. July 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7591
[RFC7636]
N. Sakimura, Ed.; J. Bradley; N. Agarwal. Proof Key for Code Exchange by OAuth Public Clients. September 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7636
[Solid.OIDC.Primer]
Jackson Morgan; Aaron Coburn; Matthieu Bosquet. Solid-OIDC Primer. URL: https://solid.github.io/solid-oidc/primer/
[Solid.Protocol]
Sarven Capadisli; et al. Solid Protocol. URL: https://solidproject.org/TR/protocol
[UMA]
Eve Maler; Maciej Machulak; Justin Richer. User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization. URL: https://docs.kantarainitiative.org/uma/wg/rec-oauth-uma-grant-2.0.html
[WebID]
Andrei Sambra; Henry Story; Tim Berners-Lee. WebID 1.0. URL: https://www.w3.org/2005/Incubator/webid/spec/identity/