Authenticate Client Applications (Browser & Node.JS)

Beta Feature

Solid Identity Provider support for authentication of client applications is currently not widely available. Currently, only Inrupt’s Enterprise Solid Server (ESS) supports Client ID authentication for client applications and only as a Beta feature.

Application Identity

To access private data on Solid Pods, you must authenticate as a user/agent who has been granted appropriate access to that data.

In Solid, not only can you control who has access to your data, but you can also control which client applications are used to do so. For example, you can choose to allow a user to view your pictures only if the user uses a specific application, or you can choose to allow a user to view your grocery list without specifying which app (i.e., the user can use any app).

Just as Solid users are identified using their WebIDs, Solid applications are also identified using their client identifiers. Unauthenticated applications (including applications without client identifiers) are considered “public” clients.

Public clients cannot have long-lived sessions on the Solid Identity Provider. Some applications may want to use long-lived sessions; for example, server-side applications where users may not be available constantly to re-authenticate upon session expiration. Therefore, these applications may prefer to be identified with a client identifier rather than be public clients.

Application Login

A client identifier is a URL that points to a JSON-LD document per the Solid-OIDC specification: Client Identifiers.

Note

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

To login the application, include the application’s client identifier (in the clientId field) when calling the login() function. For example, the following code snippet includes the application’s client ID https://my-app.example.com/myappid 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://broker.pod.inrupt.com",      // Solid Identity Provider
  redirectUrl: "https://my-app.example.com/solid/", // Redirect back to application
  clientId: "https://my-app.example.com/myappid"    // 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.

Client Identifier

The Resource found when dereferencing an application’s Client Identifier is a JSON-LD document with the @context value of https://www.w3.org/ns/solid/oidc-context.jsonld. For example, the following sample JSON-LD document may be found by dereferencing the client identifier https://my-app.example.com/myappid:

{
  "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld",
  "client_id": "https://my-app.example.com/myappid",
  "redirect_uris": ["https://my-app.example.com/solid/"],
  "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"]
}

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.

scope

Optional. 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

This scope is only recommended for server-side applications as this scope prevents silent authentication.

For the definition of offline_access scope, see OpenID Connect.

Custom values may also be specified.

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:

Hosting Client Identifier Document

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

Additional Information

For information on specifying access for applications, see ACP Access Rules and Create Rule for a Specific Client Application.

Authenticate (Node.js)

Structured Data