• Using the Libraries »
• Authentication »
• Authenticate Client Applications (Browser & Node.JS)

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

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.

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.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://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.jsonld"    // Client Identifier 
});

The Solid Identity Provider verifies the specified clientId and redirectUrl values with those found in the identifying JSON-LD document. You can specify the localhost url (i.e., https://localhost:<port>) in the redirect_uris in the client identifier document and the login() call to test with a locally running application.

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 Identifier document. As such, you may encounter an error if you use the Client Identifier document to log in, and later modify the Client Identifier document and reuse the document for login.

Client Identifier

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

• Either a file extension of .json or .jsonld.

• A @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.jsonld:

{
  "@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. Tip To test with a locally running application during development, you can specify the localhost url (i.e., https://localhost:<port>) in both: the redirect_uris in the Client Identifier, and the redirectUrl in the application’s login() call.
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:

• Solid-OIDC specification: Client Identifiers.

• OAuth2.0 website

• OpenID Connect (OIDC) Dynamic Client Registration

• Solid OIDC Primer

Hosting Client Identifier 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.

During development, to test with an application running on localhost, specify the localhost url (i.e., https://localhost:<port>) as the redirect url in the Client Identifier document and the application; i.e.,

• the redirect_uris in the Client Identifier,

  {
    "@context": "https://www.w3.org/ns/solid/oidc-context.jsonld",
    "client_id": "https://my-app.example.com/myappid.jsonld",
    "redirect_uris": ["http://localhost:3000/index.html"],
    "client_name": "Access Test App"
  }
  

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

  await login({
    oidcIssuer: 'https://broker.pod.inrupt.com',
    clientId: 'https://my-app.example.com/myappid.jsonld',
    redirectUrl: 'http://localhost:3000/index.html',
    clientName: 'Access Test App2',
  });
  

Note

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

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