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
#appmust appear as part of asolid:oidcRegistrationstatement 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 asolid:oidcRegistrationstatement. In the example, it appears on line 3 of the document.The
#appis 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 |
||||||
|---|---|---|---|---|---|---|---|
|
A string containing the application’s WebID. The |
||||||
|
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
|
||||||
|
A string containing a space-delimited list of OAuth2.0 scopes your application is allowed to request. OAuth2.0 scopes include:
Custom values may also be specified. |
||||||
|
An array containing the OAuth2.0 flows supported by your application. Acceptable values are:
|
||||||
|
An array containing the methods the Solid Identity Provider should use to send information to the application when redirecting the user to complete login.
|
||||||
|
(Optional) A string containing a user-friendly name for the application. |
||||||
|
(Optional) A string containing the application’s homepage URI. |
||||||
|
(Optional) A string containing the URI where the application’s logo is available. |
||||||
|
(Optional) A string containing the URI where the application’s terms of service are available. |
||||||
|
(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
|
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:
Hosting the profile on GitHub, like the the solid-client-authn-browser demo app.
Hosting the profile on a Solid Pod.
Additional Information¶
For information on specifying access for applications, see ACP Access Rules and Manage Rules for Specific Client Applications.