antaeus.keycloak.react 1.0.6 → 1.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +163 -3
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -624,6 +624,165 @@ For complete security guidelines, see [Keycloak Setup Guide - Security](../../KE
624
624
 
625
625
  ---
626
626
 
627
+ ## Architecture
628
+
629
+ ### How It Works
630
+
631
+ ```
632
+ ┌──────────────────┐ ┌─────────────────┐ ┌─────────────────┐
633
+ │ React App │◄───────┤ Keycloak │────────►│ Backend API │
634
+ │ (Your Frontend) │ OIDC │ Auth Server │ OIDC │ (Your Service) │
635
+ └──────────────────┘ └─────────────────┘ └─────────────────┘
636
+ │ │ │
637
+ │ 1. User clicks login │ │
638
+ ├──────────────────────────►│ │
639
+ │ │ │
640
+ │ 2. Redirects to Keycloak │ │
641
+ │ login page │ │
642
+ │ │ │
643
+ │ 3. User enters │ │
644
+ │ credentials │ │
645
+ │ │ │
646
+ │ 4. Redirect back with │ │
647
+ │◄──────────────────────────┤ │
648
+ │ auth code │ │
649
+ │ │ │
650
+ │ 5. Exchange code for │ │
651
+ ├──────────────────────────►│ │
652
+ │ tokens (PKCE) │ │
653
+ │ │ │
654
+ │ 6. Access + ID + Refresh │ │
655
+ │◄──────────────────────────┤ │
656
+ │ tokens (JWT) │ │
657
+ │ │ │
658
+ │ 7. API call with Bearer token │
659
+ ├──────────────────────────────────────────────────────►│
660
+ │ │ │
661
+ │ │ 8. API validates token │
662
+ │ │◄──────────────────────────┤
663
+ │ │ │
664
+ │ 9. Protected data │ │
665
+ │◄──────────────────────────────────────────────────────┤
666
+ ```
667
+
668
+ ### Device Flow (for TVs/IoT)
669
+
670
+ ```
671
+ TV/Device App Keycloak User Browser Backend
672
+ │ │ │ │
673
+ │ 1. Request device code │ │ │
674
+ ├────────────────────────►│ │ │
675
+ │ │ │ │
676
+ │ 2. Device code + │ │ │
677
+ │ user code + URL │ │ │
678
+ │◄────────────────────────┤ │ │
679
+ │ │ │ │
680
+ │ 3. Display QR code │ │ │
681
+ │ with user code │ │ │
682
+ │ (ABCD-EFGH) │ │ │
683
+ │ │ │ │
684
+ │ │ 4. User scans QR │ │
685
+ │ │ or visits URL │ │
686
+ │ │◄────────────────────┤ │
687
+ │ │ │ │
688
+ │ │ 5. User enters │ │
689
+ │ │ device code │ │
690
+ │ │◄────────────────────┤ │
691
+ │ │ │ │
692
+ │ │ 6. User logs in │ │
693
+ │ │◄────────────────────┤ │
694
+ │ │ │ │
695
+ │ 7. Poll for token │ │ │
696
+ │ (every 5 seconds) │ │ │
697
+ ├────────────────────────►│ │ │
698
+ │ │ │ │
699
+ │ 8. Access token │ │ │
700
+ │◄────────────────────────┤ │ │
701
+ │ │ │ │
702
+ │ 9. API call with token │ │ │
703
+ ├───────────────────────────────────────────────────────────────────►│
704
+ ```
705
+
706
+ ### Component Hierarchy
707
+
708
+ ```
709
+ <KeycloakProvider>
710
+ │
711
+ ├─ Manages OIDC client
712
+ ├─ Handles token storage
713
+ ├─ Provides auth context
714
+ │
715
+ ├─ <App>
716
+ │ │
717
+ │ ├─ <SessionMonitor /> (monitors token expiration)
718
+ │ │
719
+ │ ├─ <Router>
720
+ │ │ │
721
+ │ │ ├─ <Route path="/" element={<Home />} />
722
+ │ │ │
723
+ │ │ ├─ <Route path="/dashboard">
724
+ │ │ │ <ProtectedRoute>
725
+ │ │ │ <Dashboard />
726
+ │ │ │ </ProtectedRoute>
727
+ │ │ │ </Route>
728
+ │ │ │
729
+ │ │ └─ <Route path="/admin">
730
+ │ │ <ProtectedRoute requiredRoles={["admin"]}>
731
+ │ │ <AdminPanel />
732
+ │ │ </ProtectedRoute>
733
+ │ │ </Route>
734
+ │ │
735
+ │ └─ <UserProfile /> (displays user info)
736
+ ```
737
+
738
+ ---
739
+
740
+ ## Official Keycloak Documentation
741
+
742
+ Quick links to relevant Keycloak documentation for deeper understanding.
743
+
744
+ ### Getting Started
745
+ - [Keycloak Documentation](https://www.keycloak.org/docs/latest/) - Official docs home
746
+ - [Getting Started Guide](https://www.keycloak.org/guides#getting-started) - Install and basics
747
+ - [Server Administration Guide](https://www.keycloak.org/docs/latest/server_admin/) - Configure realms, clients, users
748
+
749
+ ### JavaScript/React Integration
750
+ - [Securing Applications - JavaScript](https://www.keycloak.org/docs/latest/securing_apps/#_javascript_adapter) - Official JS adapter (we use oidc-client-ts instead)
751
+ - [OpenID Connect](https://www.keycloak.org/docs/latest/securing_apps/#_oidc) - OIDC flows explained
752
+
753
+ ### Client Configuration
754
+ - [Public Clients](https://www.keycloak.org/docs/latest/server_admin/#_clients) - Configure browser-based apps
755
+ - [Client Scopes](https://www.keycloak.org/docs/latest/server_admin/#_client_scopes) - Manage OAuth scopes
756
+ - [Protocol Mappers](https://www.keycloak.org/docs/latest/server_admin/#_protocol-mappers) - Customize token claims
757
+ - [Valid Redirect URIs](https://www.keycloak.org/docs/latest/server_admin/#_redirect-uris) - Configure allowed redirect URLs
758
+
759
+ ### Security Features
760
+ - [PKCE (Proof Key for Code Exchange)](https://www.keycloak.org/docs/latest/securing_apps/#_javascript_implicit_flow) - Enhanced security for SPAs
761
+ - [Token Refresh](https://www.keycloak.org/docs/latest/securing_apps/#_refresh_token) - Silent token renewal
762
+ - [CORS Configuration](https://www.keycloak.org/docs/latest/server_admin/#_cors) - Cross-origin requests
763
+
764
+ ### Advanced Topics
765
+ - [Device Authorization Grant](https://www.keycloak.org/docs/latest/securing_apps/#_device_authorization_grant) - OAuth 2.0 device flow for TVs/IoT
766
+ - [Session Management](https://www.keycloak.org/docs/latest/securing_apps/#_session_iframe) - Session timeout and renewal
767
+ - [Logout](https://www.keycloak.org/docs/latest/securing_apps/#_logout) - Single logout configuration
768
+ - [Identity Brokering](https://www.keycloak.org/docs/latest/server_admin/#_identity_broker) - Social login (Google, GitHub, etc.)
769
+ - [User Federation](https://www.keycloak.org/docs/latest/server_admin/#_user-storage-federation) - LDAP, Active Directory
770
+
771
+ ### Role-Based Access Control
772
+ - [Realm Roles](https://www.keycloak.org/docs/latest/server_admin/#realm-roles) - Define and assign roles
773
+ - [Client Roles](https://www.keycloak.org/docs/latest/server_admin/#client-roles) - Application-specific roles
774
+ - [Composite Roles](https://www.keycloak.org/docs/latest/server_admin/#composite-roles) - Role hierarchies
775
+
776
+ ### REST API & Endpoints
777
+ - [OpenID Connect Endpoints](https://www.keycloak.org/docs/latest/securing_apps/#_oidc_endpoints) - Token, auth, userinfo endpoints
778
+ - [Admin REST API](https://www.keycloak.org/docs-api/latest/rest-api/index.html) - Manage Keycloak programmatically
779
+
780
+ ### Troubleshooting
781
+ - [Common Issues](https://www.keycloak.org/docs/latest/securing_apps/#_troubleshooting) - Fix common problems
782
+ - [Debugging](https://www.keycloak.org/docs/latest/server_admin/#_auditing) - Enable audit logging
783
+
784
+ ---
785
+
627
786
  ## Requirements
628
787
 
629
788
  - React 18+
@@ -645,8 +804,9 @@ MIT
645
804
 
646
805
  For issues and feature requests, please visit [GitHub Issues](https://github.com/sso/keycloak-react/issues).
647
806
 
648
- ### Useful Resources
807
+ ### Additional Resources
649
808
 
650
- - [Keycloak Official Documentation](https://www.keycloak.org/docs/latest/)
651
809
  - [OAuth 2.0 / OpenID Connect Explained](https://www.oauth.com/)
652
- - [oidc-client-ts Documentation](https://github.com/authts/oidc-client-ts)
810
+ - [oidc-client-ts Documentation](https://github.com/authts/oidc-client-ts) - Underlying OIDC library
811
+ - [React Router v6 Docs](https://reactrouter.com/) - For routing integration
812
+ - [JWT.io](https://jwt.io/) - Decode and inspect JWT tokens
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "antaeus.keycloak.react",
3
- "version": "1.0.6",
3
+ "version": "1.0.7",
4
4
  "description": "Complete Keycloak integration for React with device flow, M2M, and session management",
5
5
  "main": "./dist/index.js",
6
6
  "module": "./dist/index.mjs",