Opaquely authenticates Solid clients
Solid currently supports two cross-origin authentication protocols, WebID-TLS and WebID-OIDC.
This library abstracts away the implementation details of these specs so that clients don't have to handle different authentication protocols.
If you're building a web app and want to identify users with Solid, or store personal information on your user's Solid account, you'll have to authenticate them. This library provides a simple API for logging in, logging out, and fetching resources with authenticated credentials.
The simplest way to use this library is to install it via npm or yarn.
You can then use the ES6 module (import { login, currentUser, logout } from 'solid-auth-client'), or you can grab the transpiled UMD bundle from
node_modules/solid-auth-client/dist-lib/solid-auth-client.bundle.js.
This API doc uses flow type annotations for clarity. They're just here to show you the types of arguments expected by exported functions. You don't have to know anything about flow.
login (idp: string, {
callbackUri?: string,
storage?: Storage
}): Promise<?session | ?redirectFn>
Authenticates the user with their IDP (identity provider) and promises an object containing the user's session.
When the user is successfully authenticated, the session will be non-null. When
the user is not authenticated by the IDP, the session will be null.
Auth flows like OIDC require the user to give consent on their identity
provider. In such cases, this function will return a function which
redirects the user to their auth provider, so as not to break the promise.
All you have to do is call that function in order to send the user on their
way. Then, call currentSession when the user gives consent and lands back
in your app.
If you're using an auth flow with redirections, and don't want to take the user away from your app, consider using the popup workflow.
If there's an error during the auth handshake, the Promise will reject.
Options:
callbackUri(default current window location): a URI to be redirected back to with credentials for auth flows which involve redirectsstorage: An object implementing the storage interface for persisting credentials.localStorageis the default in the browser.
popupLogin({
popupUri: ?string,
storage: AsyncStorage
}): Promise<?session>
Logs the user in using a popup window so that your app doesn't lose state. See Logging in via the popup app.
currentSession (storage?: Storage): Promise<?session>
Finds the current session, and returns it if it is still active, otherwise
null.
logout (storage?: Storage): Promise<void>
Clears the active user session.
WARNING: this is an unsupported use case in WebID-TLS. Once your browser provides its client cert to a web server, there's no going back! So for WebID-TLS, the only thing this will do is clear the session from the store.
Fetches a resource from the web. Same API as
fetch, but retries with credentials when it
encounters a 401 with a WWW-Authenticate header which matches a recognized
authenticate scheme.
fetch: (url: RequestInfo, options?: Object) => Promise<Response>
type webIdTlsSession = {
authType: WebIdTls,
idp: string,
webId: string
}
type webIdOidcSession = {
authType: WebIdOidc,
idp: string,
webId: string,
accessToken: string,
idToken: string
}
type session = webIdTlsSession | webIdOidcSession
To log in with a popup window, you'll need a popup application running on a trusted domain which authenticates the user, handles redirects, and messages the authenticated session back to your application.
In order to tell the user they're logging into your app, you'll need to build a static popup bound to your application's name.
Keeping this in mind, it's pretty simple to build a popup for your app!
- Make sure you've got the
solid-auth-clientpackage installed locally.
$ npm i solid-auth-client # [--save | --save-dev]- Run the build script!
$ solid-auth-client generate-popup "My App's Name" # [my-app-popup.html]- If your popup is deployed to e.g. 'https://localhost:8080/popup.html',
call
popupLogin({ popupUri: 'https://localhost:8080/popup.html' }).
This library assumes you have node >= v7.10.1 installed. It may work with earlier versions, but that hasn't been tested thus far.
$ git clone https://github.com/solid/solid-auth-client.git
$ cd solid-auth-client
$ npm install
$ npm run test # run the code formatter, linter, and test suite
$ npm run test:dev # just run the tests in watch modeYou can test how solid-auth-client operates within an app by running the demo app.
$ POPUP_URI='http://localhost:8081/popup.html' npm run start:demo$ APP_NAME='solid-auth-client demo' npm run start:popup