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 ofhttps://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 |
||||||||
---|---|---|---|---|---|---|---|---|---|
|
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.,
|
||||||||
|
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 of OAuth 2.0 grant types that the client can use at the authorization server’s token endpoint.
For additional values, see the |
||||||||
|
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", "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’slogin()
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.