Authenticate Client Applications

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 apps 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 WebID is just like any other WebID. WebID is a URL that acts as an identifier in Solid. The Resource found at this URL is the application’s profile, which contains information about your app.

To login the application, send the application’s WebID to the Solid Identity Provider during the login process. That is, when calling the login() function, set the clientId parameter to the application’s WebID.

For example, the following code snippet passes the application’s WebID https://my-app.domain/profile#app to the login() function.

// The `login()` redirects the user to their identity provider;
// i.e., moves the user away from the current page.
await login({
  // Specify the URL of the user's Solid Identity Provider.
  oidcIssuer: "https://broker.pod.inrupt.com",
  // Specify the URL the Solid Identity Provider should redirect to after the user logs in.
  redirectUrl: "https://my-app.domain/redirect/",
  // Specify the app WebID so that the Solid Identity Provider can verify login information.
  clientId: "https://my-app.domain/profile#app"
});

The Solid Identity Provider verifies the WebID provided during the login with the information in the profile. 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.

Note

Although the example uses the @inrupt/solid-client-authn-browser, the concepts also apply to @inrupt/solid-client-authn-node.

Application WebID and Profile

An application’s WebID is the application’s profile URL appended with a hash fragment. 1 The value of the hash fragment is arbitrary but must also appear in the profile document itself. Specifically, the hash fragment must appear as part of a solid:oidcRegistration statement.

For example, if an application’s WebID is https://my-app.domain/profile#app:

  • The profile document must be served at https://my-app.domain/profile.

  • The hash fragment #app must appear as part of a solid:oidcRegistration statement in the profile document. For details, see Application Profile Template.

1

A WebID can also have a URL without the hash fragment. For details, see https://www.w3.org/2005/Incubator/webid/spec/identity/#dfn-webid.

Application Profile Template

The Resource found at an application’s WebID is the application’s profile, which contains information about your app.

For example, the following is a profile associated with the example WebID https://my-app.domain/profile#app and can be used as a template for other application profiles:

Important

  • The hash fragment of the WebID, in this example #app, must appear in the profile document as part of a solid:oidcRegistration statement. In the example, it appears on line 3 of the document.

  • The #app is an arbitrary fragment chosen for the example. You can specify a different value for your application.

@prefix solid: <http://www.w3.org/ns/solid/terms#> .

<#app> solid:oidcRegistration """{
    
    # Mandatory values

    "client_id" : "https://my-app.domain/profile#app",
    "redirect_uris" : ["https://my-app.domain/callback"],
    "scope" : "openid",
    "grant_types" : ["authorization_code"],
    "response_types" : ["code"],

    # Optional values
    
    "client_name" : "Solid Application Name",
    "client_uri" : "https://my-app.domain/",
    "logo_uri" : "https://my-app.domain/logo.png",
    "tos_uri" : "https://my-app.domain/tos.html",
    "default_max_age" : 60000,
}""" .

The following table describes the fields in the JSON document specified after the solid:oidcRegistration predicate:

Field

Description

client_id

A string containing the application’s WebID. The clientId parameter 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 parameter passed to the login() function must match one of the specified URIs exactly.

scope

A string containing a space-delimited list of OAuth2.0 scopes your application is allowed to request. OAuth2.0 scopes include:

Scope

Description

openid

This scope is mandatory.

offline_access

If offline_access is specified, only the application receives a refresh token; the user will be prompted each time.

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

Custom values may also be specified.

grant_types

An array containing the OAuth2.0 flows supported by your application. Acceptable values are:

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

This is only useful for apps that have declared the offline_access scope, and therefore discouraged for in-browser apps.

response_types

An array containing the methods the Solid Identity Provider should use to send information to the application when redirecting the user to complete login.

"code" should be the only value specified in the array.

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.

default_max_age

(Optional) A number that indicates the maximum time, in seconds, that a user can remain authenticated. If the user last authenticated to the Solid Identity Provider more than default_max_age seconds ago, the user is logged out.

See RFC 7591 or more information on the fields.

See also:

Hosting Application Profile

There are no specific restrictions on where the profile document can be hosted. For instance, the profile document does not have to be hosted at the same domain as the application itself. For example, the solid-client-authn-browser demo app, which is meant to run on the localhost domain, uses GitHub to host the application WebID at https://raw.githubusercontent.com/inrupt/solid-client-authn-js/main/packages/browser/examples/single/bundle/client-app-profile.ttl#app.

For applications available in production with their own domains, you may chose to serve the application profile as you would any other static asset.

For other applications that do not have a domain name yet, some options include:

Additional Information

For information on specifying access for applications, see ACP Access Rules and Manage Rules for Specific Client Applications.