Authenticate Client Applications (Browser & Node.JS)

Beta Feature

Solid Identity Provider support for WebID-based authentication for client applications is currently not widely available. Currently, only Inrupt’s Enterprise Solid Server (ESS) supports WebID-based 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 WebIDs. Unauthenticated applications (including applications without WebIDs) 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 WebID rather than be public clients.

Application Login

An application’s WebID is a URL that points to a JSON-LD document per the Solid-OIDC specification.

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 WebID (in the clientId field) when calling the login() function. For example, the following code snippet includes the application’s WebID 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 WebID 
});

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 WebID in its requests to the Solid Server. The Solid Server uses these WebIDs to enforce access control.

Application Identifier

The Resource found at an application’s WebID is a JSON-LD document with the @context value of https://www.w3.org/ns/solid/oidc-context.jsonld. For example, given a WebID of https://my-app.example.com/myappid, the following may be a sample JSON-LD document found at that URL:

{
  "@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 value must be set to https://www.w3.org/ns/solid/oidc-context.jsonld.

client_id

A string containing the application’s WebID. 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 Application Identifier

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