Appendix: Client ID Document (Browser & Node.JS)

An application identifies itself using a client identifier (Client ID).

A Client ID can be:

• a URL that dereferences to a Client ID Document.

• a value that has been registered using either OIDC dynamic or static registration.

Inrupt’s client libraries provide login APIs that can support the use of a Client ID that dereferences to a Client ID Document.

The Client ID Document is JSON-LD document that contains various metadata about the client.

Perform Login with Client ID (of type URL)

Note

An application can host its JSON-LD document in any location; however, if possible, it is recommended that the application itself hosts the JSON-LD document as a static resource.

Inrupt’s client libraries provide login APIs that can support the use of a Client ID (of type URL) that dereferences to a Client ID Document. When calling the login() function, set the clientId option to the application’s Client ID.

For example, the following code snippet includes the application’s client ID https://my-app.example.com/myappid.jsonld to the login() function:

// `login()` sends users to their Solid Identity Provider;
// Once logged in, returns users to the specified `redirectUrl`.
// Both the `redirectURL` and the `clientId` value must appear
// in the Client Identifier document located at the specified URL.
await login({
  oidcIssuer: "https://login.inrupt.com",      // Solid Identity Provider
  redirectUrl: "https://my-app.example.com/login/callback/", // Redirect back to application
  clientId: "https://my-app.example.com/myappid.jsonld"    // Client Identifier 
});

The Solid Identity Provider verifies the specified clientId and redirectUrl values with those found in the identifying JSON-LD document.

Once the login flow completes, the application includes both the user WebID and the application’s Client ID in its requests to the Solid Server. The Solid Server uses these identifiers to enforce access control.

Note

ESS OpenID Service caches the Client ID Document. As such, you may encounter an error if, within the caching period, you use the Client ID Document to log in, and later modify the Client ID Document and reuse the document for login.

Client ID Document

The Resource found when dereferencing an application’s Client ID is a JSON-LD document with:

• A @context value of https://www.w3.org/ns/solid/oidc-context.jsonld.

• Fields conformant to an OIDC client registration.

For example, assume the following sample JSON-LD document may be found by dereferencing the Client ID https://my-app.example.com/myappid.jsonld:

{
  "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld",
  "client_id": "https://my-app.example.com/myappid.jsonld",
  "redirect_uris": [ "https://my-app.example.com/login/callback/" ],
  "client_name": "My Sample App",
  "client_uri": "https://my-app.example.com/",
  "logo_uri": "https://my-app.example.com/logo.png",
  "tos_uri": "https://my-app.example.com/terms.html",
  "policy_uri": "https://my-app.example.com/policy.html",
  "contacts": [
    "someone@example.com"
  ],
  "scope": "openid offline_access webid",
  "grant_types": [
    "refresh_token",
    "authorization_code"
  ]
}

Field	Description
@context	The context for the JSON-LD document. The expected @context value is https://www.w3.org/ns/solid/oidc-context.jsonld.
client_id	A string containing the application’s Client Identifier. The clientId value passed to the login() function must match the specified value exactly.
redirect_uris	An array containing URIs where the Solid Identity Provider may redirect the user to complete the login process, i.e., where the application’s handleIncomingRedirect() will be called. The redirectUrl value passed to the login() function must match one of the specified URIs exactly. Tip During development, to test with an application that is only running locally, you can specify the localhost url (e.g., https://localhost:<port>/ or https://localhost:<port>/some/login/callback/route/) in both: the redirect_uris in the Client Identifier, and the redirectUrl in the application’s login() call. Remove the localhost url from redirect_uris when you are running in production.
scope	A string containing a space-delimited list of OAuth2.0 scopes your application is allowed to request. OAuth2.0 scopes include: Scope Notes openid If scope specified, openid is mandatory. offline_access Include offline_access to be issued refresh tokens. For the definition of offline_access scope, see OpenID Connect. webid webid is mandatory. Custom values may also be specified.
grant_types	An array of OAuth 2.0 grant types that the client can use at the authorization server’s token endpoint. "authorization_code" The default authentication flow, based on redirections between the application and the Solid Identity Provider. "refresh_token" The flow where a refresh token is used to “refresh” an expired session. Used for apps that have declared the offline_access scope (i.e., discouraged for in-browser apps). For additional values, see the grant_types definition in https://datatracker.ietf.org/doc/html/rfc7591#section-2.
client_name	Optional. A string containing a user-friendly name for the application.
client_uri	Optional. A string containing the application’s homepage URI.
logo_uri	Optional. A string containing the URI where the application’s logo is available.
tos_uri	Optional. A string containing the URI where the application’s terms of service are available.
policy_uri	Optional. A string containing the URI where the application’s privacy policy is available.
contacts	Optional. An array of contact information for the application.

Tip

For additional fields to include in the document as well as more information on the aforementioned fields, see RFC7591.

See also:

• Solid-OIDC specification: Client Identifiers.

• OAuth2.0 website

• OpenID Connect (OIDC) Dynamic Client Registration

• Solid OIDC Primer

Hosting Client ID Document

Recommended Although an application can host its JSON-LD document in any location, it is recommended that the application itself hosts the JSON-LD document as a static resource if possible.

Redirect URI Value During Development

During development, to test with an application running only on localhost, specify the localhost url (e.g., https://localhost:<port>/ or https://localhost:<port>/some/login/callback/route/) as the redirect url in the Client ID Document and the application; i.e.,

• the redirect_uris in the Client ID Document,

  {
    "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld",
    "client_id": "https://my-app.example.com/myappid",
    "redirect_uris": ["http://localhost:3000/"],
    "client_name": "My Test App",
    "client_uri": "https://my-app.example.com/",
    "logo_uri": "https://my-app.example.com/logo.png",
    "tos_uri": "https://my-app.example.com/terms.html",
    "policy_uri": "https://my-app.example.com/policy.html",
    "scope" : "openid offline_access webid",
    "grant_types" : ["refresh_token","authorization_code"]
  }
  

• the redirectUrl in the application’s login() call.

  await login({
    oidcIssuer: 'https://login.inrupt.com',
    clientId: 'https://my-app.example.com/myappid',
    redirectUrl: 'http://localhost:3000/'
  });
  

Important

Remove the localhost url from redirect_uris when you are running in production.

Note

ESS OpenID Service caches the Client ID Document. As such, you may encounter an error if, within the caching period, you use the Client ID Document to log in, and later modify the Client ID Document and reuse the document for login.

Additional Information

For information on specifying access for applications, see Matcher Statements and Create Policy to Match Agents and Clients.