From ae29e27a1570818fce982cdbafdb4424fa0f6b48 Mon Sep 17 00:00:00 2001 From: "Ismail H. Ayaz" Date: Wed, 20 Mar 2024 18:40:24 +0300 Subject: [PATCH] chore: update readme --- README.md | 290 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 271 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 5359e46..ee06496 100644 --- a/README.md +++ b/README.md @@ -39,46 +39,298 @@ OpenID Connect (OIDC) and OAuth2 library for browser based JavaScript applicatio ### Table of Contents - [Installation](#installation) - [Documentation](#documentation) -- [Api Docs](#api-docs) -- [Examples](#examples) +- [Access Token Refreshing](#automatically-renew-access-token) +- [Use Refresh Token](#use-refresh-tokens-for-access-token-renewal) +- [Login with Popup](#login-with-popup) +- [Additional Methods](#additional-methods) +- [Examples](/examples) +## Installation +From the CDN: -### Installation +```html + +``` -From the CDN: +Using package managers: +```bash +npm install @plusauth/oidc-client-js +yarn add @plusauth/oidc-client-js +pnpm add @plusauth/oidc-client-js +``` + +## Documentation + +### Initialization +Create the `OIDCClient` instance before rendering or initializing your application. + +```js +import { OIDCClient } from '@plusauth/oidc-client-js'; + +const oidcClient = new OIDCClient({ + issuer: 'YOUR_OIDC_PROVIDER', + client_id: 'YOUR_CLIENT_ID', + redirect_uri: 'YOUR_CALLBACK_PAGE_URI' +}); + +oidcClient.initialize().then( function(){ + // client initialized +}) +``` + +Or with create helper method: + +```js +import createOIDCClient from '@plusauth/oidc-client-js'; + +createOIDCClient({ + issuer: 'YOUR_OIDC_PROVIDER', + client_id: 'YOUR_CLIENT_ID', + redirect_uri: 'YOUR_CALLBACK_PAGE_URI' +}).then(oidcClient => { + //... +}); +``` + +Using `createOIDCClient` does a couple of things automatically: + +* It creates an instance of `OIDCClient`. +* It calls `silentLogin` to refresh the user session. +* It suppresses all errors from `silentLogin`. + +### Create callback page +OpenID Connect / OAuth2 authorization flows require a redirect uri to return the authorization result back. Create a +page and register its url to your client's allowed redirect uris. In your page initialize OIDCClient and all you +need to do is call `loginCallback` method. + +```js +oidcClient.loginCallback() +.then( function(localState){ + // successful login + console.log('User successfully logged in') +}) +.catch( function(error) { + console.error('Authorization error:', error) + }) +``` + +### Login and get user info -> **⚠ NOTE:** Although `@plusauth/oidc-client-js` follows semantic versioning, we advise using specific versions in CDN links as they are easy to forget and latest version may break up your application. -> Make sure to check releases and use the specific version. +Create a login button users can click. ```html - + ``` -Using [npm](https://npmjs.org): +In the click event handler of button you created, call login method for redirecting user to provider's login page +. Make sure `redirect_uri` is registered on the provider, and you have created a callback handler as defined in [above +](#create-callback-page). -```sh -npm install @plusauth/oidc-client-js +```js +document.getElementById('login').addEventListener('click', function() { + oidcClient.login({ + redirect_uri: 'http://localhost:8080/' + }); +}); ``` -or [yarn](https://yarnpkg.com): -```sh -yarn add @plusauth/oidc-client-js +### Make authenticated requests to your API + +After user is successfully logged in we can use access_token retrieved from authentication response to call the API. + +```html + +``` + +On the event handler you can get access token and use it like this: + +```js +document.getElementById('makeRequest').addEventListener('click', function () { + oidcClient.getAccessToken().then(accessToken => + fetch('https://any.exampleapi.com/api', { + method: 'GET', + headers: { + Authorization: 'Bearer ' + accessToken + } + }) + ) + .then(result => result.json()) + .then(data => { + console.log(data); + }); +}); ``` -### Documentation -Documentation is served on PlusAuth documentation site. You can reach it from [here](https://docs.plusauth.com/tools/oidc-client-js) +### Logout + +Add a logout button. + +```html + +``` + +In event handler, call equivalent method. +```js +document.getElementById('logout').addEventListener('click', function(){ + oidcClient.logout(); +}); +``` + +## Automatically renew access token +Generally, access tokens have a short lifetime, so it is common to renew the access token before its expiration. +This feature is enabled by default, but you can disable it by passing `autoSilentRenew: false` to client options. + +```js +new OIDCClient({ + autoSilentRenew: false, + ...// other options +}) +``` + +### Use different callback page for silent renew +In silent renew the library performs the flow in a hidden iframe. When you are developing a single page application, +assuming your callback page is handled by the app itself, the iframe will load your whole application after the +oauth2 redirection. + +You can prevent this overhead by creating a different page which will handle silent renew only. To accomplish this you +should pass `silent_redirect_uri` to client options which should have your silent redirect handler page uri. If you don't use +`silent_redirect_uri`, `redirect_uri` will be used instead. Don't forget to include it to your providers redirect uri whitelist. -### Api Docs +Have a look at following snippets for an example: +```js +// auth.js +import { OIDCClient } from '@plusauth/oidc-client-js'; +const oidcClient = new OIDCClient({ + redirect_uri: 'https://YOUR_SITE/callback' + silent_redirect_uri: 'https://YOUR_SITE/silent-renew.html', + ...//other options +}); +``` + + + +```html + + + + + + + + + + + +``` + +## Use Refresh Tokens for access token renewal +Configure the library by passing the setting `useRefreshTokens` to `true` on initialization: + +```js +const oidcClient = new OIDCClient({ + issuer: 'YOUR_OIDC_ISSUER', + client_id: 'YOUR_CLIENT-ID', + useRefreshTokens: true +}); +``` + + +
+
+

+ +Don't forget to include `offline_access` in your scope for retrieving refresh tokens. If there is not any refresh +token stored locally, the library will fallback to using silent authorization request. +

+
+
+ +## Login with popup + +Create a button to trigger login. + +```html + +``` + +Attach event listener and call `loginWithPopup` method of your initialized oidc client. + +```js +document.getElementById('loginWithPopup').click(async () => { + await oidcClient.loginWithPopup(); +}); +``` + +
+
+

+Most browsers block popups if they are not happened as a result of user actions. In order to display +login popup you must call `loginWithPopup` in an event handler listening for a user action like button click. +

+
+
+ +## Additional methods +You can access user, access token, refresh token, id token and scopes with followings. Using getter methods are always the +safe bet as they will read from store. Direct access of those variables may result unexpectedly if you modify them in your app. +Direct variables are created by listening the `user_login` and `user_logout` events. + +### Get User + +```js + const user = await oidcClient.getUser(); + // or + const user = oidcClient.user +``` + +### Get Access Token + +```js + const accessToken = await oidcClient.getAccessToken(); + // or + const accessToken = oidcClient.accessToken +``` + +### Get ID Token + +```js + const idToken = await oidcClient.getIdToken(); + // or + const idToken = oidcClient.idToken +``` + +### Get Refresh Token + +```js + const refreshToken = await oidcClient.getRefreshToken(); + // or + const refreshToken = oidcClient.refreshToken +``` + +### Get Scopes + +```js + const scopes = await oidcClient.getScopes(); + // or + const scopes = oidcClient.scopes +``` + + +## Api Docs Please visit [here](https://plusauth.github.io/oidc-client-js/classes/OIDCClient.html) +## Examples +Have a look at [examples directory](/examples) for various examples + ### Browser Support [Browserlist Coverage](https://browsersl.ist/#q=defaults) This library uses global fetch api. If your app requires to be working in environment that does not have `fetch` you must use a polyfill like [whatwg-fetch](https://github.com/github/fetch). -### Examples - -Have a look at [examples directory](/examples) for various examples