From 6bcdefac1e49e50c2f82476cc6fd6b76b19dd1a3 Mon Sep 17 00:00:00 2001 From: Tamas Mak Date: Mon, 26 Jun 2023 09:00:01 +0200 Subject: [PATCH] chore: Update README files according to the latest changes (#114) --- README.md | 88 ++------------------------------ sso-kit-client/README.md | 19 +++++-- sso-kit-client/core/package.json | 2 +- sso-kit-client/lit/README.md | 6 +-- sso-kit-client/lit/package.json | 2 +- sso-kit-client/react/README.md | 8 +-- 6 files changed, 28 insertions(+), 97 deletions(-) diff --git a/README.md b/README.md index 3e4941d..ae509d4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# Vaadin SSO Kit +# SSO Kit -SSO Kit is an add-on for Vaadin Flow that provides all the configuration you need to add single sign-on capabilities to your applications. +SSO Kit is an add-on for **Vaadin Flow** and **Hilla** frameworks that provides all the configuration you need to add single sign-on capabilities to your applications. SSO Kit is built upon the [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) specification and it comes with a [Spring Boot](https://spring.io/projects/spring-boot) starter module that takes care of configuring the security settings you need to authenticate against your identity provider. @@ -12,86 +12,8 @@ These are the currently supported identity providers: SSO Kit is compatible with [Vaadin Platform](https://vaadin.com/) starting from version [23.2.0](https://github.com/vaadin/platform/releases/tag/23.2.0). -## Getting Started - -To get started with SSO Kit you just need to add the `sso-kit-starter` module as a dependency to your Vaadin application, e.g. in your `pom.xml`: - -```xml - - com.vaadin - sso-kit-starter - -``` - -### Setting Client Credentials and Login Route - -Then you need to set your identity provider client credentials in your `application.yml`, e.g. for Keycloak: - -```yaml -spring: - security: - oauth2: - client: - provider: - keycloak: # This is the registration-id, can be any value - issuer-uri: https://my-keycloak.io/realms/my-realm - registration: - keycloak: # This should be the same as the registration-id - client-id: my-client - client-secret: verySecretValue - scope: - - profile - - openid - - email - - roles -vaadin: - sso: - login-route: /oauth2/authorization/keycloak # /oauth2/authorization/ -``` - -This configuration will redirect to the provider's login page any unauthorized request. - -### Protecting Your Views - -You can set which views require authentication annotating them as described in [Annotating the View Classes](https://vaadin.com/docs/latest/security/enabling-security/#annotating-the-view-classes). For example: +SSO Kit is compatible with [Hilla](https://hilla.dev/) starting from version [2.0.0](https://github.com/vaadin/hilla/releases/tag/2.0.0). -```java -@PermitAll -@Route(value = "private") -public class PrivateView extends VerticalLayout { - // ... -} -``` - -### Get the Authenticated User - -The SSO Kit starter provides the `AuthenticationContext` bean that you can inject into your views to get the currently authenticated user: - -```java -@PermitAll -@Route(value = "private") -public class PrivateView extends VerticalLayout { - - public PrivateView(AuthenticationContext authContext) { - authContext.getAuthenticatedUser().ifPresent(user -> { - var fullName = user.getFullName(); - Notification.show("Hello, " + fullName + "!"); - }); - } -} -``` - -### Logging the User Out - -The same `AuthenticationContext` bean provides the `logout()` method to terminate both the local user session and the provider's session: - -```java -@PermitAll -@Route(value = "private") -public class PrivateView extends VerticalLayout { +## Getting Started - public PrivateView(AuthenticationContext authContext) { - add(new Button("Logout", e -> authContext.logout())); - } -} -``` +Getting started tutorials are available for [Vaadin Flow](https://vaadin.com/docs/latest/tools/sso/getting-started), for [Hilla with Lit](https://hilla.dev/docs/lit/acceleration-kits/sso-kit/getting-started) and for [Hilla with React](https://hilla.dev/docs/react/acceleration-kits/sso-kit/getting-started). diff --git a/sso-kit-client/README.md b/sso-kit-client/README.md index b5da27d..9080a54 100644 --- a/sso-kit-client/README.md +++ b/sso-kit-client/README.md @@ -2,27 +2,36 @@ The **SSO Kit Client** is the client side library for the **[SSO Kit for Hilla](https://github.com/vaadin/sso-kit/tree/main/sso-kit-starter-hilla)** and depends on it. -Getting Started with the **SSO Kit for Hilla** using Lit [documentation](https://hilla.dev/docs/lit/acceleration-kits/sso-kit/getting-started/#frontend). +Getting Started with the **SSO Kit for Hilla** with Lit [documentation](https://hilla.dev/docs/lit/acceleration-kits/sso-kit/getting-started/#frontend). -Getting Started with the **SSO Kit for Hilla** using React [documentation](https://hilla.dev/docs/react/acceleration-kits/sso-kit/getting-started/#frontend). +Getting Started with the **SSO Kit for Hilla** with React [documentation](https://hilla.dev/docs/react/acceleration-kits/sso-kit/getting-started/#frontend). The library consists three packages. The **[SSO Kit Client Lit](lit)**, **[SSO Kit Client React](react)** and **[SSO Kit Client Core](core)** which is private, so it is not published into public registry. However, its sources are included into other two libraries during building, packaging and publishing. ## Installation -Install one of the libraries for Hilla using Lit or Hilla using React: +### Install the library for Hilla with Lit: ```sh npm i @hilla/sso-kit-client-lit ``` + +Once installed, you can import the `SingleSignOnContext` class in your application: + +```js +import ssoContext from "@hilla/sso-kit-client-lit"; +``` + +### Install the library for Hilla with React: + ```sh npm i @hilla/sso-kit-client-react ``` -Once installed, you can import the `SingleSignOnContext` class in your application: +Once installed, you can import the `useSsoContext` hook in your application: ```js -import singleSignOnContext from "@hilla/sso-kit-client/SingleSignOnContext.js"; +import { useSsoContext } from "@hilla/sso-kit-client-react"; ``` ## Development diff --git a/sso-kit-client/core/package.json b/sso-kit-client/core/package.json index 7ccd230..d4b03f7 100644 --- a/sso-kit-client/core/package.json +++ b/sso-kit-client/core/package.json @@ -23,7 +23,7 @@ "build": "npm run build:transpile", "build:transpile": "tsc -b", "lint": "eslint **/*.ts", - "test": "karma start ../karma.config.cjs --port 9878", + "test": "karma start ../karma.config.cjs --port 9876", "test:coverage": "npm run test -- --coverage", "test:watch": "npm run test -- --watch", "typecheck": "tsc --noEmit" diff --git a/sso-kit-client/lit/README.md b/sso-kit-client/lit/README.md index 9bd2e67..d0e22dd 100644 --- a/sso-kit-client/lit/README.md +++ b/sso-kit-client/lit/README.md @@ -2,11 +2,11 @@ The **SSO Kit Client Lit** is the client side library for the **[SSO Kit for Hilla](https://github.com/vaadin/sso-kit/tree/main/sso-kit-starter-hilla)** and depends on it. -Getting Started with the **SSO Kit for Hilla** using Lit [documentation](https://hilla.dev/docs/lit/acceleration-kits/sso-kit/getting-started/#frontend). +Getting Started with the **SSO Kit for Hilla** with Lit [documentation](https://hilla.dev/docs/lit/acceleration-kits/sso-kit/getting-started/#frontend). ## Installation -Install the library for Hilla using Lit: +Install the library for Hilla with Lit: ```sh npm i @hilla/sso-kit-client-lit @@ -15,7 +15,7 @@ npm i @hilla/sso-kit-client-lit Once installed, you can import the `SingleSignOnContext` class in your application: ```js -import singleSignOnContext from "@hilla/sso-kit-client-lit/SingleSignOnContext.js"; +import ssoContext from "@hilla/sso-kit-client-lit"; ``` ## Development diff --git a/sso-kit-client/lit/package.json b/sso-kit-client/lit/package.json index 81a7f8c..163f48c 100644 --- a/sso-kit-client/lit/package.json +++ b/sso-kit-client/lit/package.json @@ -26,7 +26,7 @@ "prepack": "npm run build", "postpack": "npm run clean:build && rimraf ../core/src/*.{d.ts.map,js.map,js} ../core/src/index.d.ts ../core/src/EndpointImportError.d.ts ../core/tsconfig.tsbuildinfo", "lint": "eslint **/*.ts", - "test": "karma start ../karma.config.cjs --port 9878", + "test": "karma start ../karma.config.cjs --port 9877", "test:coverage": "npm run test -- --coverage", "test:watch": "npm run test -- --watch", "typecheck": "tsc --noEmit" diff --git a/sso-kit-client/react/README.md b/sso-kit-client/react/README.md index 3fd0b76..a247586 100644 --- a/sso-kit-client/react/README.md +++ b/sso-kit-client/react/README.md @@ -2,20 +2,20 @@ The **SSO Kit Client React** is the client side library for the **[SSO Kit for Hilla](https://github.com/vaadin/sso-kit/tree/main/sso-kit-starter-hilla)** and depends on it. -Getting Started with the **SSO Kit for Hilla** using React [documentation](https://hilla.dev/docs/react/acceleration-kits/sso-kit/getting-started/#frontend). +Getting Started with the **SSO Kit for Hilla** with React [documentation](https://hilla.dev/docs/react/acceleration-kits/sso-kit/getting-started/#frontend). ## Installation -Install the library for Hilla using React: +Install the library for Hilla with React: ```sh npm i @hilla/sso-kit-client-react ``` -Once installed, you can import the `SingleSignOnContext` class in your application: +Once installed, you can import the `useSsoContext` hook in your application: ```js -import singleSignOnContext from "@hilla/sso-kit-client-react/SingleSignOnContext.js"; +import { useSsoContext } from "@hilla/sso-kit-client-react"; ``` ## Development