chore: add custom idp extension

Author: Pavel910

custom-idp/6.0.0-alpha/README.md

@@ -0,0 +1,56 @@
+# Custom IdP Extension
+
+> [!IMPORTANT]  
+> This extension is designed to work with Webiny `v6.0.0-alpha` exclusively!
+
+This is a reference integration of a custom IdP. The goal of this extension is to demonstrate what Webiny plugins and concepts you need to use to integrate any third pary IdP with Webiny.
+
+> [!WARNING]  
+> This is in no way a final implementation as different IdPs have their own specifics, and every project has different requirements. This extension gives a solid foundation you can tweak and build upon.
+
+There are two extensions that form the full integration: an [api](./api) and an [admin](./admin) extension.
+
+## API Extension
+
+The `api` extension has these responsibilities:
+
+- Verification of the `idToken` JWT, and validation of the claims on every request to the Webiny API.
+- Mapping of token claims to Webiny Identity, which is then used by Webiny for permission checks, etc.
+
+## Admin Extension
+
+The `admin` extension has these responsibilities:
+
+- Interception of the login screen component (no login form, redirects the user to IdP login page)
+- Handling of `idToken` and `refreshToken` via query params
+- Background token refreshing
+- Attaching the `Authorization` header to all API calls
+- Storing tokens in localStorage
+
+## Installation
+
+In your Webiny project, run the following command:
+
+```bash
+yarn webiny extension custom-idp/6.0.0-alpha
+```
+
+## Configuration
+
+### Interaction with Your IdP
+
+Once the extension is installed, you need to provide implementation for `goToLogin`, `onError`, `onLogout`, and `getFreshTokens`.
+In your project, open `extensions/customIdp/admin/src/index.tsx`. Here you'll find a reference implementation which you need to update with the specifics of your IdP (redirects to specific URLs, error code mapping, etc.). This file is also an entrypoint to the extension, and a place to configure the `<CustomIdp/>` component.
+
+> [!TIP]
+> If you need to change how some parts of the `<CustomIdp/>` work, start by opening the `extensions/customIdp/admin/src/CustomIdp.tsx` component, and see how it interacts with Webiny and the external IdP.
+
+### `idToken` Verification
+
+To verify the `idToken` signature, this implementation uses a shared secret key. You should set your shared secret key in your project's `.env` file:
+
+```dotenv
+WEBINY_API_IDP_SHARED_SECRET=my_shared_secret
+```
+
+You can find the verification logic in `extensions/customIdp/api/src/createAuthenticator.ts`. Here you can also implement additional verification of token claims.

custom-idp/6.0.0-alpha/extensions/customIdp/admin/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@demo/custom-idp-admin",
+  "main": "src/index.tsx",
+  "version": "1.0.0",
+  "keywords": [
+    "webiny-extension",
+    "webiny-extension-type:admin"
+  ],
+  "dependencies": {
+    "@apollo/react-hooks": "^3.1.5",
+    "@webiny/admin-ui": "0.0.0",
+    "@webiny/app-admin": "0.0.0",
+    "@webiny/app-security": "0.0.0",
+    "@webiny/app-tenancy": "0.0.0",
+    "graphql-tag": "^2.12.6",
+    "jwt-decode": "^4.0.0",
+    "mobx": "^6.9.0",
+    "mobx-react-lite": "^3.4.3"
+  }
+}

custom-idp/6.0.0-alpha/extensions/customIdp/admin/src/AttachAuthorizationHeader.tsx

@@ -0,0 +1,65 @@
+import { useEffect } from "react";
+import { setContext } from "apollo-link-context";
+import { onError } from "apollo-link-error";
+import { ApolloLinkPlugin } from "@webiny/app";
+import { useSecurity } from "@webiny/app-security";
+import { plugins } from "@webiny/plugins";
+import type { ApiError } from "./types";
+
+interface Props {
+    onError: (error: ApiError) => void;
+}
+
+export const AttachAuthorizationHeader = (props: Props) => {
+    const { getIdToken } = useSecurity();
+
+    useEffect(() => {
+        // Attach Authorization header
+        const authPlugin = new ApolloLinkPlugin(() => {
+            return setContext(async (_, { headers }) => {
+                // If "Authorization" header is already set, don't overwrite it.
+                if (headers && headers.Authorization) {
+                    return { headers };
+                }
+
+                // Get `idToken` from Security context.
+                const idToken = await getIdToken();
+
+                if (!idToken) {
+                    return { headers };
+                }
+
+                return {
+                    headers: {
+                        ...headers,
+                        Authorization: `Bearer ${idToken}`
+                    }
+                };
+            });
+        });
+
+        authPlugin.name = "customIdpAuthorizationHeader";
+
+        plugins.register(authPlugin);
+
+        return () => {
+            plugins.unregister("customIdpAuthorizationHeader");
+        };
+    }, [getIdToken]);
+
+    useEffect(() => {
+        // Catch network errors
+        plugins.register(
+            new ApolloLinkPlugin(() => {
+                return onError(({ networkError }) => {
+                    if (networkError) {
+                        // @ts-expect-error
+                        props.onError(networkError.result);
+                    }
+                });
+            })
+        );
+    }, []);
+
+    return null;
+};

custom-idp/6.0.0-alpha/extensions/customIdp/admin/src/Authenticator.ts

@@ -0,0 +1,158 @@
+import { makeAutoObservable, runInAction } from "mobx";
+import { TokenManager } from "./TokenManager";
+import { JwtService } from "./JwtService";
+import type { GoToLogin, GetFreshTokens, Tokens, OnLogout, LogoutReason } from "./types";
+
+export class Authenticator {
+    private readonly goToLogin: GoToLogin;
+    private readonly getFreshTokens: GetFreshTokens;
+    private readonly refreshInterval: number;
+    private tokenManager = new TokenManager();
+    private jwtService = new JwtService();
+    private intervalId: ReturnType<typeof setInterval> | null = null;
+    private isAuthenticated = false;
+    private refreshing = false;
+    private onLogout: OnLogout;
+
+    constructor(
+        goToLogin: GoToLogin,
+        getFreshTokens: GetFreshTokens,
+        onLogout: OnLogout,
+        refreshIntervalInSeconds: number
+    ) {
+        this.goToLogin = goToLogin;
+        this.getFreshTokens = getFreshTokens;
+        this.onLogout = onLogout;
+        this.refreshInterval = refreshIntervalInSeconds * 1000;
+        makeAutoObservable(this);
+    }
+
+    get vm() {
+        return {
+            isAuthenticated: this.isAuthenticated,
+            isRefreshing: this.refreshing
+        };
+    }
+
+    getIdToken() {
+        const tokens = this.tokenManager.getTokens();
+
+        return tokens?.idToken;
+    }
+
+    public init(tokens?: Tokens) {
+        this.log("Authenticator.init", tokens);
+        if (tokens) {
+            this.tokenManager.setTokens(tokens);
+        }
+
+        this.initialize();
+    }
+
+    public destroy() {
+        if (this.intervalId) {
+            clearInterval(this.intervalId);
+        }
+    }
+
+    // Initialize authentication check and start refresh loop.
+    private async initialize(): Promise<void> {
+        const tokens = this.tokenManager.getTokens();
+
+        if (!tokens) {
+            this.setUnauthenticated();
+            this.goToLogin();
+            return;
+        }
+
+        const { idToken, refreshToken } = tokens;
+
+        if (this.jwtService.isExpired(idToken)) {
+            if (refreshToken) {
+                await this.refreshTokens();
+            } else {
+                this.logout("noRefreshToken");
+                return;
+            }
+        }
+
+        this.setAuthenticated();
+
+        this.startTokenRefreshLoop();
+    }
+
+    // Refresh tokens on a regular interval.
+    private startTokenRefreshLoop(): void {
+        this.log("Authenticator.startTokenRefreshLoop");
+        this.intervalId = setInterval(() => {
+            this.refreshTokens();
+        }, this.refreshInterval);
+    }
+
+    // Refresh the tokens and update state accordingly.
+    private async refreshTokens(): Promise<void> {
+        if (this.refreshing) {
+            return;
+        }
+
+        const tokens = this.tokenManager.getTokens();
+
+        if (!tokens) {
+            this.logout("noTokens");
+            return;
+        }
+
+        try {
+            this.log("Authenticator.refreshTokens");
+            this.setRefreshing(true);
+            const freshTokens = await this.getFreshTokens(tokens.refreshToken);
+            this.tokenManager.setTokens(freshTokens);
+            this.setAuthenticated();
+        } catch (err) {
+            this.log("Authenticator.refreshTokens.error", err);
+            runInAction(() => {
+                this.logout("tokenRefreshError");
+            });
+        } finally {
+            this.setRefreshing(false);
+        }
+    }
+
+    // Force logout the user and redirect.
+    public logout(reason?: LogoutReason): void {
+        this.log("Authenticator.logout");
+        this.tokenManager.clearTokens();
+        this.setUnauthenticated();
+
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+
+        this.onLogout(reason);
+    }
+
+    private setAuthenticated(): void {
+        runInAction(() => {
+            this.isAuthenticated = true;
+        });
+    }
+
+    private setUnauthenticated(): void {
+        runInAction(() => {
+            this.isAuthenticated = false;
+        });
+    }
+
+    private setRefreshing(flag: boolean): void {
+        runInAction(() => {
+            this.refreshing = flag;
+        });
+    }
+
+    private log(...msg: any[]): void {
+        if (process.env.NODE_ENV === "development") {
+            console.log(...msg);
+        }
+    }
+}