@passwordless-id/connect
v1.2.1
Published
A simple library to "Sign in with passwordless.id" and to fetch the user's profile and "id_token"
Downloads
256
Maintainers
Readme
@passwordless-id/connect
A simple library to "Sign in with passwordless.id" and to fetch the user's profile and "id_token"
NPM: npm install @passwordless-id/connect
CDN: https://unpkg.com/@passwordless-id/[email protected]/dist/connect.min.js
Github: https://github.com/passwordless-id/connect/
Demos
Default usage
import passwordless from 'https://unpkg.com/@passwordless-id/connect'
const scope = 'openid avatar email'
const user = await passwordless.id({scope})
console.log(user)
if(user.signedIn && user.scopeGranted) {
window.alert(`Hello ${user.profile.nickname}`)
}
else {
// the following line will perform a redirect and come back to the same page once done
passwordless.auth({scope})
}
Scope
The scope
determines the properties you want to read from the user profile. The lesser the scope you require, the more likely it will be granted by the user. It is good practice to request only what you need.
openid
: this is the default scope. It will provide thesub
value, which is an anonymized user ID.avatar
: Providesnickname
,picture
(as url) andpreferred_username
email
: Providesemail
andemail_verified
phone
: Providesphone
andphone_verified
profile
: Provides personal information like real name, birthdate and genderaddress
: Provides the postal address
Cache
Setting this value will cache the data in the sessionStorage
, so that further calls to passwordless.id()
will first check the cache and return the user data if present. However, if the id_token
is expired, it will re-perform a redirect or http request in order to fetch a "fresh" id_token
. Once the user closes the browser tab, the user data will be cleared.
The id_token
The id_token
is a JWT (Json Web Token) that contains both the user's ID and a signature. This can be sent to your server as proof of the user's identity and it's authenticity can be verified by the server.
In order to validate the id_token
server side, it is sufficient to use:
GET https://api.passwordless.id/openapi/validate?token=...
Advanced usage
Sign in/up
In order to let the user authenticate (sign in or create an account) and authorize your app to read the profile, you must call auth
as follows.
// the following line will perform a redirect and come back to the same page once done
passwordless.auth({
scope: "openid avatar email"
})
This has no response. The user will be redirected to the Passwordless.ID UI in order to sign in/up and authorize your app to read the profile.
Once done, the user will be redirected back to the original url, to your web page/app.
Fetching profile
and id_token
Unlike OAuth2/OpenID which always require redirects, Passwordless.ID contains an extension to fetch the profile and id_token
directly: the request
method. Of course, this only works if the user is currently signed it and has granted the requested profile scope.
const scope = 'openid avatar email'
await passwordless.request({scope})
Results in the following.
{
"signedIn": true,
"scopeGranted": true,
"profile": {
"sub": "U1NdanBNalQ6JTI2...",
"nickname": "Johny",
...
},
"id_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}
If this fails, the flags signedIn
and scopeGranted
inform you why the user information could not be accessed. Either the user is not signed in or it has not yet authorized your application to read your profile scope.
Options
The auth(...)
method can be customized further for OAuth2/OpenID flows with the following parameters.
passwordless.auth({
scope: "openid",
response_type: "code id_token token",
redirect_uri: "https://optional-url-when-login-successful", // optional, if omitted, it will return to the current URL
nonce: "optional nonce to be present in the id_token",
state: "optional hash value added to the redirect when using the `code` response_type flow"
})
The response_type
is optional, and mainly used in other OAuth2/OpenID flows. It is there for the sake of completeness and only necessary to integrate with other OAuth2/OpenID libraries.
The redirect_uri
is optional and used to navigate to another page upon successful authentication and authorization.
The nonce
is optional and can be used for increased security, like verifying that your server triggered the sign in.
Development
testing locally
npm install --global http-server
npx http-server
Open http://localhost:8080/demo.html