Appendix: Client ID Registration (Browser & Node.JS)

Applications must be registered with the Solid Identity Provider before they can login users with OpenID Connect or request OAuth 2.0 access tokens. Inrupt’s client libraries provide login APIs that can handle the client registration via Solid-OIDC registration using a Client ID document.

A Client ID is a URL that points to a JSON-LD document. The JSON-LD document contains various metadata about the client that is used for client registration.

Perform Client ID Registration during Login

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.

Inrupt’s login APIs support registering the client using a Solid-OIDC Client ID document. To handle Client ID registration during login, set the clientId option to the application’s client identifier when calling the login() function.

For example, the following code snippet includes the application’s client ID 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://login.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:

• A @context value of https://www.w3.org/ns/solid/oidc-context.jsonld.

• Fields conformant to an OIDC client registration.

For example, the following sample JSON-LD document may be found by dereferencing the client identifier https://my-app.example.com/myappid:

{
  "@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"],
  "scope" : "openid offline_access webid",
  "grant_types" : ["refresh_token","authorization_code"]
}

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	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 Include offline_access to be issued refresh tokens. For the definition of offline_access scope, see OpenID Connect. webid webid is mandatory. Custom values may also be specified.
grant_types	An array of OAuth 2.0 grant types that the client can use at the authorization server’s token endpoint. "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. Used for apps that have declared the offline_access scope (i.e., discouraged for in-browser apps). For additional values, see the grant_types definition in https://datatracker.ietf.org/doc/html/rfc7591#section-2.
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",
    "redirect_uris": ["http://localhost:3000/index.html"],
    "client_name": "My Test 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",
    "scope" : "openid offline_access webid",
    "grant_types" : ["refresh_token","authorization_code"]
  }
  

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

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

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 Matcher Statements and Create Policy to Match Agents and Clients.