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 ofhttps://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 |
||||||
---|---|---|---|---|---|---|---|
|
The context for the JSON-LD document. The expected |
||||||
|
A string containing the application’s Client Identifier. 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
Tip To test with a locally running application during
development, you can specify the localhost url (i.e.,
|
||||||
|
Optional. 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. |
||||||
|
(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 string containing the URI where the application’s privacy policy is available. |
||||||
|
(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, 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’slogin()
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.