Skip to content

Commit e1f8c32

Browse files
jeswrCopilotCopilotlangsamu
authored
feat: add guide for authenticating with a script (#14)
* feat: add guide for authenticating with a script * Update docs/guides/authenticating_with_a_script.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * feat: add guide for authenticating with a script (#15) * Initial plan * Address review feedback: load OIDC_ISSUER from env var, add cross-platform instructions Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Samu Lang <langsamu@users.noreply.github.com> * Update docs/guides/authenticating_with_a_script.md Co-authored-by: Samu Lang <langsamu@users.noreply.github.com> * fix: use optional SOLID_RESOURCE_URL for authenticated fetch example (#16) * Initial plan * fix: add optional SOLID_RESOURCE_URL env var for the resource to fetch Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com> * Apply suggestions from code review --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: jeswr <63333554+jeswr@users.noreply.github.com> --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com> Co-authored-by: Samu Lang <langsamu@users.noreply.github.com>
1 parent 57ba61e commit e1f8c32

2 files changed

Lines changed: 149 additions & 1 deletion

File tree

‎docs/guides/authenticating_with_a_script.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# Authenticating with a Node.js Script
2+
3+
Many Solid use cases — automated data pipelines, bots, CI/CD tasks, and server-to-server integrations — require authentication **without a browser**. This guide walks you through authenticating a Node.js script against a Solid server using **Client Credentials**.
4+
5+
The approach works with any Solid server that supports the Client Credentials grant type, including the [Community Solid Server (CSS)](https://communitysolidserver.github.io/CommunitySolidServer/) and Inrupt's [Enterprise Solid Server (ESS)](https://docs.inrupt.com/).
6+
7+
## Prerequisites
8+
9+
- [Node.js](https://nodejs.org/) v18 or later (for built-in `fetch`)
10+
- A Solid account with a Pod on a server that supports Client Credentials
11+
- Basic familiarity with JavaScript
12+
13+
## Overview
14+
15+
The flow has three stages:
16+
17+
1. **Generate a Client Credentials token** — obtain a `client_id` / `client_secret` pair linked to your WebID. This only needs to be done **once**.
18+
2. **Log in with the credentials** — use the `client_id` and `client_secret` to start an authenticated session.
19+
3. **Make authenticated requests** — use the session's `fetch` to read and write resources on your Pod.
20+
21+
## 1. Set Up the Project
22+
23+
Create a new directory and initialize it:
24+
25+
```bash
26+
mkdir solid-script && cd solid-script
27+
npm init -y
28+
```
29+
30+
Set the project to use ES modules and install the required library:
31+
32+
```bash
33+
npm pkg set type=module
34+
npm install @inrupt/solid-client-authn-node
35+
```
36+
37+
Create a file called `index.js` — all the code below goes into this file.
38+
39+
## 2. Generate Client Credentials (One-Time Setup)
40+
41+
Before your script can log in, you need a `client_id` / `client_secret` pair. There are two ways to get one:
42+
43+
### Option A: Via the Account Page (easiest)
44+
45+
If your Solid server has an account management UI, you can create a token there:
46+
47+
1. Navigate to your account page:
48+
- **Community Solid Server (local)**: [http://localhost:3000/.account/](http://localhost:3000/.account/)
49+
- **solidcommunity.net**: [https://solidcommunity.net/.account/](https://solidcommunity.net/.account/)
50+
- **Inrupt PodSpaces**: [https://login.inrupt.com/registration.html](https://login.inrupt.com/registration.html)
51+
2. Create a new Client Credentials token, giving it a name and selecting your WebID.
52+
3. Copy the `id` and `secret` values shown. **Store the secret safely** — it cannot be retrieved again.
53+
54+
Skip ahead to [Step 3](#3-log-in-and-make-authenticated-requests) if you use this approach.
55+
56+
### Option B: Via the API (programmatic)
57+
58+
Some Solid servers also allow you to generate credentials programmatically. This is useful for automation or when you don't have browser access. The process is server-specific — for example, the Community Solid Server provides a dedicated API for this:
59+
60+
- [CSS — Generating a token via the API](https://communitysolidserver.github.io/CommunitySolidServer/latest/usage/client-credentials/#via-the-api)
61+
62+
## 3. Log In and Make Authenticated Requests
63+
64+
Once you have a `client_id` and `client_secret`, you can authenticate using the [`Session`](https://inrupt.github.io/solid-client-authn-js/node/classes/Session.html) class from `@inrupt/solid-client-authn-node`.
65+
66+
Replace the contents of `index.js` (or create a new file) with:
67+
68+
```javascript
69+
import { Session } from '@inrupt/solid-client-authn-node';
70+
71+
// These values come from Step 2 (or from your account page).
72+
// In production, load these from environment variables.
73+
const CLIENT_ID = process.env.SOLID_CLIENT_ID;
74+
const CLIENT_SECRET = process.env.SOLID_CLIENT_SECRET;
75+
const OIDC_ISSUER = process.env.SOLID_OIDC_ISSUER; // Your authorization server URL (sometimes called IdP, sometimes same as your Solid server URL)
76+
const RESOURCE_URL = process.env.SOLID_RESOURCE_URL; // URL of the protected resource to fetch (optional)
77+
78+
async function main() {
79+
// Create a new session and log in
80+
const session = new Session();
81+
await session.login({
82+
clientId: CLIENT_ID,
83+
clientSecret: CLIENT_SECRET,
84+
oidcIssuer: OIDC_ISSUER,
85+
});
86+
87+
if (!session.info.isLoggedIn) {
88+
throw new Error('Login failed');
89+
}
90+
console.log(`Logged in as ${session.info.webId}`);
91+
92+
// session.fetch works just like the standard fetch API,
93+
// but automatically includes authentication headers.
94+
const resourceUrl = RESOURCE_URL ?? session.info.webId;
95+
const response = await session.fetch(resourceUrl);
96+
console.log(`GET ${resourceUrl} — ${response.status}`);
97+
console.log(await response.text());
98+
99+
// Always log out when done
100+
await session.logout();
101+
console.log('Logged out.');
102+
}
103+
104+
main().catch(console.error);
105+
```
106+
107+
Run the script, passing your credentials, authorization server URL (sometimes same as Solid server URL), and optionally the URL of the protected resource you want to fetch as environment variables.
108+
109+
On **Linux / macOS** (Bash):
110+
111+
```bash
112+
SOLID_CLIENT_ID="your-client-id" \
113+
SOLID_CLIENT_SECRET="your-client-secret" \
114+
SOLID_OIDC_ISSUER="http://localhost:3000" \
115+
SOLID_RESOURCE_URL="http://localhost:3000/your-pod/private-resource" \
116+
node index.js
117+
```
118+
119+
On **Windows** (PowerShell):
120+
121+
```powershell
122+
$env:SOLID_CLIENT_ID="your-client-id"
123+
$env:SOLID_CLIENT_SECRET="your-client-secret"
124+
$env:SOLID_OIDC_ISSUER="http://localhost:3000"
125+
$env:SOLID_RESOURCE_URL="http://localhost:3000/your-pod/private-resource"
126+
node index.js
127+
```
128+
129+
Replace `http://localhost:3000` with the URL of your authorization server (for example, `https://solidcommunity.net` or `https://login.inrupt.com`), and set `SOLID_RESOURCE_URL` to the URL of the private resource you want to access. If `SOLID_RESOURCE_URL` is omitted, the script falls back to fetching your WebID profile document.
130+
131+
You should see the contents of the resource printed to the console.
132+
133+
## Tips
134+
135+
- **Token reuse**: The `client_id` / `client_secret` pair does not expire. Generate it once and reuse it across runs. Only the access tokens obtained during `session.login()` are short-lived — the library handles refreshing them automatically.
136+
- **Session keep-alive**: By default, the `Session` refreshes its tokens in the background. Pass `{ keepAlive: false }` to the `Session` constructor if you want a one-shot script that exits cleanly.
137+
- **Security**: Never hard-code secrets in source code. Use environment variables or a secrets manager.
138+
- **Multiple WebIDs**: You can generate multiple client credentials tokens, each linked to a different WebID on your account.
139+
140+
## Further Reading
141+
142+
- [Community Solid Server — Client Credentials documentation](https://communitysolidserver.github.io/CommunitySolidServer/latest/usage/client-credentials/)
143+
- [Inrupt — Authentication for Single-User Applications](https://docs.inrupt.com/developer-tools/javascript/client-libraries/tutorial/authenticate-nodejs-script/)
144+
- [`@inrupt/solid-client-authn-node` API reference](https://inrupt.github.io/solid-client-authn-js/node/classes/Session.html)
145+
- [Solid-OIDC specification](https://solid.github.io/solid-oidc/)

‎docs/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
1-
# Home
1+
# Welcome to Solid Developer Documentation
2+
3+
Welcome! This site provides guides and resources to help you start building applications with [Solid](https://solidproject.org/) — the open standard that gives people control over their data. Whether you're creating your first Solid app or integrating Solid into an existing project, you'll find step-by-step tutorials to get you going.
24

35
## Guides
46

57
- [Building your first Solid App with LDO & React](guides/building_your_first_solid_app_with_ldo_and_react)
8+
- [Authenticating with a Node.js Script](guides/authenticating_with_a_script)
69
- [Demo Application using Solid + Next.js + LDO](guides/solid_nextjs_ldo_demo_application)
710
- [Hosting the Community Solid Server in an Azure App Service](guides/hosting_the_community_solid_server_in_an_azure_app_service)

0 commit comments

Comments
 (0)