Merge pull request #159 from devforth/keycloack-oauth-adapter

docs: Add Keycloak and GitHub OAuth adapters to documentation

Author: ivictbor

adminforth/documentation/docs/tutorial/05-Plugins/11-oauth.md

@@ -174,6 +174,116 @@ plugins: [
 ]
 ```
 
+### GitHub Adapter
+
+Install Adapter:
+
+```
+npm install @adminforth/github-oauth-adapter --save
+```
+
+
+1. Go to the [GitHub Apps](https://github.com/settings/apps)
+2. Create a new app or select an existing one
+3. Go to the `Permisiions & events` -> `Account permissions` -> `Email addresses` and change to `Read-only`
+3. Go to the `General` and click to `Generate a new client secret` button and copy secret
+4. Add the credentials to your `.env` file:
+
+```bash
+GITHUB_OAUTH_CLIENT_ID=your_facebook_client_id
+GITHUB_OAUTH_CLIENT_SECRET=your_facebook_client_secret
+```
+
+Add the adapter to your plugin configuration:
+
+```typescript title="./resources/adminuser.ts"
+import AdminForthAdapterGithubOauth2 from '@adminforth/github-oauth-adapter';
+
+// ... existing resource configuration ...
+plugins: [
+  new OAuthPlugin({
+    adapters: [
+      ...
+      new AdminForthAdapterGithubOauth2({
+        clientID: process.env.GITHUB_OAUTH_CLIENT_ID,
+        clientSecret: process.env.GITHUB_OAUTH_CLIENT_SECRET,
+      }),
+    ],
+  }),
+]
+```
+
+### Kaycloack Adapter
+
+Install Adapter:
+
+```
+npm install @adminforth/keycloak-oauth-adapter --save
+```
+
+1. Update your .env file with the following Keycloak configuration:
+
+```bash
+KEYCLOAK_CLIENT_ID=adminforth-client
+KEYCLOAK_CLIENT_SECRET=1234567890
+KEYCLOAK_URL=http://localhost:8080
+KEYCLOAK_REALM=AdminforthRealm
+```
+
+2. Start Keycloak with Docker:
+
+```bash
+docker compose -p af-dev-demo -f inventory.yml up -d --build --remove-orphans --wait
+```
+
+3. Create a new user from the back office with the same email as the test user (by default:   ```testuser@example.com```)
+
+Add the adapter to your plugin configuration:
+
+```typescript title="./resources/adminuser.ts"
+import AdminForthAdapterKeycloakOauth2 from '@adminforth/keycloak-oauth-adapter';
+
+// ... existing resource configuration ...
+plugins: [
+  new OAuthPlugin({
+    adapters: [
+      ...
+      new AdminForthAdapterKeycloakOauth2({
+          clientID: process.env.KEYCLOAK_CLIENT_ID,
+          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
+          keycloakUrl: process.env.KEYCLOAK_URL,
+          realm: process.env.KEYCLOAK_REALM,
+          useOpenID: true,
+      }),
+    ],
+  }),
+]
+```
+
+If you want to create a new user:
+
+1. Access Keycloak Admin Panel
+Open a browser and go to: http://localhost:8080
+Log in with the default Keycloak admin credentials:
+Username: admin
+Password: admin
+
+2. Navigate to the "Users" Section
+Click on "Users" in the left-hand menu.
+Click "Add user" in the top-right corner.
+
+3. Enter User Information
+Username: username
+Email: username@example.com
+Email Verified: ✅ (Check this box)
+Enabled: ✅ (Check this box)
+Click "Save"
+
+4. Set a Password for the User
+Go to the "Credentials" tab.
+Enter a password (e.g., testpassword).
+Uncheck "Temporary" (so the user doesn't have to reset the password).
+Click "Set Password".
 
 ### Microsoft Adapter
 
@@ -224,4 +334,11 @@ Just fork any existing adapter e.g. [Google](https://github.com/devforth/adminfo
 
 This is really easy, you have to change several then 10 lines of code in this [file](https://github.com/devforth/adminforth-google-oauth-adapter/blob/main/index.ts)
 
-Then just publish it to npm and install it in your project.
+Then just publish it to npm and install it in your project.
+
+
+Links to adapters:
+[Google](https://github.com/devforth/adminforth-google-oauth-adapter)
+[GitHub](https://github.com/devforth/adminforth-github-oauth-adapter)
+[Facebook](https://github.com/devforth/adminforth-facebook-oauth-adapter)
+[Keycloak](https://github.com/devforth/adminforth-keycloak-oauth-adapter)

dev-demo/inventory.yml

@@ -55,8 +55,34 @@ services:
     volumes:
       - mysql-data:/var/lib/mysql
 
+  keycloak:
+    image: quay.io/keycloak/keycloak:latest
+    command: start-dev --import-realm
+    environment:
+      - KEYCLOAK_ADMIN=admin
+      - KEYCLOAK_ADMIN_PASSWORD=admin
+      - DB_VENDOR=postgres
+      - DB_ADDR=pg
+      - DB_DATABASE=demo
+      - DB_USER=demo
+      - DB_PASSWORD=demo
+      - KEYCLOAK_IMPORT=/opt/keycloak/data/import/keycloak-realm.json
+      - KEYCLOAK_CLIENT_ID=${KEYCLOAK_CLIENT_ID}
+      - KEYCLOAK_CLIENT_SECRET=${KEYCLOAK_CLIENT_SECRET}
+      - KEYCLOAK_URL=${KEYCLOAK_URL}
+      - KEYCLOAK_REALM=${KEYCLOAK_REALM}
+    ports:
+      - "8080:8080"
+    depends_on:
+      - pg
+    volumes:
+      - keycloak-data:/opt/keycloak/data
+      - ./keycloak-realm.json:/opt/keycloak/data/import/keycloak-realm.json
+
+
 volumes:
   clickhouse-data:
   pg-data:
   mongo-data1:
-  mysql-data:
+  mysql-data:
+  keycloak-data:

dev-demo/keycloak-realm.json

@@ -0,0 +1,29 @@
+{
+    "id": "AdminforthRealm",
+    "realm": "AdminforthRealm",
+    "enabled": true,
+    "users": [
+      {
+        "username": "testuser",
+        "enabled": true,
+        "credentials": [
+          {
+            "type": "password",
+            "value": "testpassword"
+          }
+        ],
+        "email": "testuser@example.com",
+        "emailVerified": true
+      }
+    ],
+    "clients": [
+        {
+        "clientId": "adminforth-client",
+        "enabled": true,
+        "publicClient": true,
+        "redirectUris": ["*"],
+        "defaultClientScopes": ["openid", "email", "profile"]
+        }
+    ]
+  }
+  

dev-demo/resources/users.ts

@@ -17,7 +17,9 @@ import AdminForthAdapterGoogleOauth2 from "../../adapters/adminforth-google-oaut
 import AdminForthAdapterGithubOauth2 from  "../../adapters/adminforth-github-oauth-adapter";
 
 import AdminForthAdapterFacebookOauth2 from "../../adapters/adminforth-facebook-oauth-adapter";
+import AdminForthAdapterKeycloakOauth2 from "../../adapters/adminforth-keycloak-oauth-adapter";
 import AdminForthAdapterMicrosoftOauth2 from "../../adapters/adminforth-microsoft-oauth-adapter";
+
 export default {
   dataSource: "maindb",
   table: "users",
@@ -103,6 +105,12 @@ export default {
           clientID: process.env.FACEBOOK_CLIENT_ID,
           clientSecret: process.env.FACEBOOK_CLIENT_SECRET,
         }),
+        new AdminForthAdapterKeycloakOauth2({
+          clientID: process.env.KEYCLOAK_CLIENT_ID,
+          clientSecret: process.env.KEYCLOAK_CLIENT_SECRET,
+          keycloakUrl: process.env.KEYCLOAK_URL,
+          realm: process.env.KEYCLOAK_REALM,
+        }),
         new AdminForthAdapterMicrosoftOauth2({
           clientID: process.env.MICROSOFT_CLIENT_ID,
           clientSecret: process.env.MICROSOFT_CLIENT_SECRET,