gofr-dev · goginenibhavani2000 · Jul 17, 2025 · Aug 10, 2025 · Aug 10, 2025 · Aug 10, 2025
diff --git a/docs/advanced-guide/rbac-permissions/page.md b/docs/advanced-guide/rbac-permissions/page.md
diff --git a/docs/advanced-guide/rbac/page.md b/docs/advanced-guide/rbac/page.md
diff --git a/docs/navigation.js b/docs/navigation.js
@@ -83,6 +83,16 @@ export const navigation = [
                 href: '/docs/advanced-guide/http-authentication',
                 desc: "Implement various HTTP authentication methods to secure your GoFR application and protect sensitive endpoints."
             },
+            {
+                title: 'Role-Based Access Control (RBAC)',
+                href: '/docs/advanced-guide/rbac',
+                desc: "Implement comprehensive Role-Based Access Control with support for roles, permissions, hierarchy, JWT integration, and database-based role extraction."
+            },
+            {
+                title: 'Permission-Based Access Control',
+                href: '/docs/advanced-guide/rbac-permissions',
+                desc: "Learn how to implement fine-grained permission-based access control with route-to-permission mapping, role-to-permission assignment, and handler-level permission checks."
+            },
             {
                 title: 'Circuit Breaker Support',
                 href: '/docs/advanced-guide/circuit-breaker',

diff --git a/examples/rbac/jwt/README.md b/examples/rbac/jwt/README.md
@@ -0,0 +1,225 @@
+# JWT RBAC Example
+
+## Overview
+
+This example demonstrates **JWT-based role-based access control (RBAC)**. Roles are extracted from JWT tokens that are validated using OAuth/JWKS endpoints.
+
+## Use Case
+
+**When to use:**
+- Public-facing APIs requiring secure authentication
+- Microservices with JWT-based authentication
+- Applications integrated with OAuth2/OIDC providers
+- Multi-service architectures with centralized authentication
+
+**Not suitable for:**
+- Simple internal APIs (use header-based RBAC)
+- Applications without JWT infrastructure
+- Legacy systems without OAuth support
+
+## How It Works
+
+1. **JWT Validation**: OAuth middleware validates JWT tokens using JWKS endpoint
+2. **Role Extraction**: Role is extracted from JWT claims (e.g., `"role"` claim)
+3. **Route Matching**: Routes are matched against patterns in the config file
+4. **Authorization**: The extracted role is checked against allowed roles
+5. **Audit Logging**: All authorization decisions are automatically logged
+
+## Configuration
+
+### RBAC Config (`configs/rbac.json`)
+
+```json
+{
+  "route": {
+    "/api/users": ["admin", "editor", "viewer"],
+    "/api/admin/*": ["admin"]
+  },
+  "overrides": {
+    "/health": true
+  }
+}
+```
+
+### JWT Token Structure
+
+The JWT token should contain a role claim. Example:
+
+```json
+{
+  "sub": "user123",
+  "role": "admin",
+  "iat": 1234567890,
+  "exp": 1234571490
+}
+```
+
+**JWT Role Claim Parameter (`roleClaim`):**
+
+The `roleClaim` parameter in `WithJWT()` or `rbac.NewJWTRoleExtractor()` specifies the path to the role in JWT claims. It supports multiple formats:
+
+| Format | Example | JWT Claim Structure |
+|--------|---------|---------------------|
+| **Simple Key** | `"role"` | `{"role": "admin"}` |
+| **Array Notation** | `"roles[0]"` | `{"roles": ["admin", "user"]}` - extracts first element |
+| **Array Notation** | `"roles[1]"` | `{"roles": ["admin", "user"]}` - extracts second element |
+| **Dot Notation** | `"permissions.role"` | `{"permissions": {"role": "admin"}}` |
+| **Deeply Nested** | `"user.permissions.role"` | `{"user": {"permissions": {"role": "admin"}}}` |
+
+**Notes:**
+- If `roleClaim` is empty (`""`), it defaults to `"role"`
+- The extracted value is converted to string automatically
+- Array indices must be valid integers (e.g., `[0]`, `[1]`, not `[invalid]`)
+- Array indices must be within bounds (e.g., `roles[5]` fails if array has only 2 elements)
+
+## Setup Instructions
+
+### 1. Configure JWKS Endpoint
+
+Update the JWKS endpoint in `main.go`:
+
+```go
+app.EnableOAuth("https://your-auth-server.com/.well-known/jwks.json", 10)
+```
+
+### 2. Start the Application
+
+```bash
+go run main.go
+```
+
+### 3. Test with JWT Tokens
+
+```bash
+# Get a JWT token from your OAuth provider
+TOKEN="your-jwt-token-here"
+
+# Test endpoints
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/users
+curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/api/admin
+```
+
+### 4. Testing with Mock Server (for development)
+
+For testing, you can use the included `mock_jwks_server.go`:
+
+```go
+// In your test file
+mockJWKS, _ := NewMockJWKSServer()
+defer mockJWKS.Close()
+
+app.EnableOAuth(mockJWKS.JWKSEndpoint(), 10)
+```
+
+## API Endpoints
+
+- `GET /api/users` - Accessible by: admin, editor, viewer
+- `GET /api/admin` - Accessible by: admin only
+
+## Features Demonstrated
+
+1. **JWT Validation**: Automatic token validation via OAuth middleware
+2. **Flexible Role Claims**: Support for various JWT claim structures
+3. **Route-Based Authorization**: Pattern matching for routes
+4. **Secure by Default**: Tokens are cryptographically validated
+
+## JWT Claim Path Examples
+
+### Simple Claim
+```json
+{"role": "admin", "sub": "user123"}
+```
+```go
+app.EnableRBAC(
+	gofr.WithPermissionsFile("configs/rbac.json"),
+	gofr.WithJWT("role"),
+)
+```
+
+### Array Claim (First Element)
+```json
+{"roles": ["admin", "user"], "sub": "user123"}
+```
+```go
+app.EnableRBAC(
+	gofr.WithPermissionsFile("configs/rbac.json"),
+	gofr.WithJWT("roles[0]"),  // Extracts "admin"
+)
+```
+
+### Array Claim (Second Element)
+```json
+{"roles": ["admin", "user"], "sub": "user123"}
+```
+```go
+app.EnableRBAC(
+	gofr.WithPermissionsFile("configs/rbac.json"),
+	gofr.WithJWT("roles[1]"),  // Extracts "user"
+)
+```
+
+### Nested Claim
+```json
+{
+  "permissions": {
+    "role": "admin",
+    "scope": "read:write"
+  },
+  "sub": "user123"
+}
+```
+```go
+app.EnableRBAC(
+	gofr.WithPermissionsFile("configs/rbac.json"),
+	gofr.WithJWT("permissions.role"),
+)
+```
+
+### Deeply Nested Claim
+```json
+{
+  "user": {
+    "permissions": {
+      "role": "admin"
+    }
+  },
+  "sub": "user123"
+}
+```
+```go
+app.EnableRBAC(
+	gofr.WithPermissionsFile("configs/rbac.json"),
+	gofr.WithJWT("user.permissions.role"),
+)
+```
+
+## Security Considerations
+
+✅ **Secure for production** when:
+- JWKS endpoint is properly secured (HTTPS)
+- JWT tokens are signed with RS256/RS512
+- Token expiration is properly validated
+- Issuer and audience claims are validated
+
+⚠️ **Ensure:**
+- JWKS endpoint is accessible from your application
+- Refresh interval is appropriate for your use case
+- OAuth provider is trusted and secure
+
+## Integration with OAuth Providers
+
+### Auth0
+```go
+app.EnableOAuth("https://your-domain.auth0.com/.well-known/jwks.json", 10)
+```
+
+### Keycloak
+```go
+app.EnableOAuth("https://keycloak.example.com/realms/your-realm/protocol/openid-connect/certs", 10)
+```
+
+### AWS Cognito
+```go
+app.EnableOAuth("https://cognito-idp.region.amazonaws.com/userPoolId/.well-known/jwks.json", 10)
+```
+
diff --git a/examples/rbac/jwt/configs/rbac.json b/examples/rbac/jwt/configs/rbac.json
@@ -0,0 +1,10 @@
+{
+  "route": {
+    "/api/users": ["admin", "editor", "viewer"],
+    "/api/admin/*": ["admin"]
+  },
+  "overrides": {
+    "/health": true
+  }
+}
+
diff --git a/examples/rbac/jwt/go.mod b/examples/rbac/jwt/go.mod
@@ -0,0 +1,103 @@
+module gofr.dev/examples/rbac/jwt
+
+go 1.25
+
+require (
+	github.com/golang-jwt/jwt/v5 v5.3.0
+	github.com/stretchr/testify v1.11.1
+	gofr.dev v1.47.0
+)
+
+require (
+	cloud.google.com/go v0.121.6 // indirect
+	cloud.google.com/go/auth v0.17.0 // indirect
+	cloud.google.com/go/auth/oauth2adapt v0.2.8 // indirect
+	cloud.google.com/go/compute/metadata v0.9.0 // indirect
+	cloud.google.com/go/iam v1.5.2 // indirect
+	cloud.google.com/go/longrunning v0.7.0 // indirect
+	cloud.google.com/go/pubsub v1.49.0 // indirect
+	filippo.io/edwards25519 v1.1.0 // indirect
+	github.com/DATA-DOG/go-sqlmock v1.5.2 // indirect
+	github.com/XSAM/otelsql v0.40.0 // indirect
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/cenkalti/backoff/v5 v5.0.3 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
+	github.com/dgraph-io/dgo/v210 v210.0.0-20230328113526-b66f8ae53a2d // indirect
+	github.com/dgryski/go-rendezvous v0.0.0-20200823014737-9f7001d12a5f // indirect
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/eclipse/paho.mqtt.golang v1.5.1 // indirect
+	github.com/felixge/httpsnoop v1.0.4 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/go-logr/stdr v1.2.2 // indirect
+	github.com/go-sql-driver/mysql v1.9.3 // indirect
+	github.com/gogo/protobuf v1.3.2 // indirect
+	github.com/google/s2a-go v0.1.9 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/googleapis/enterprise-certificate-proxy v0.3.7 // indirect
+	github.com/googleapis/gax-go/v2 v2.15.0 // indirect
+	github.com/gorilla/mux v1.8.1 // indirect
+	github.com/gorilla/websocket v1.5.3 // indirect
+	github.com/grpc-ecosystem/go-grpc-middleware/v2 v2.3.3 // indirect
+	github.com/grpc-ecosystem/grpc-gateway/v2 v2.27.2 // indirect
+	github.com/joho/godotenv v1.5.1 // indirect
+	github.com/klauspost/compress v1.18.0 // indirect
+	github.com/lib/pq v1.10.9 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/ncruces/go-strftime v0.1.9 // indirect
+	github.com/openzipkin/zipkin-go v0.4.3 // indirect
+	github.com/pierrec/lz4/v4 v4.1.22 // indirect
+	github.com/pkg/errors v0.9.1 // indirect
+	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
+	github.com/prometheus/client_golang v1.23.2 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.66.1 // indirect
+	github.com/prometheus/otlptranslator v1.0.0 // indirect
+	github.com/prometheus/procfs v0.17.0 // indirect
+	github.com/redis/go-redis/extra/rediscmd/v9 v9.14.0 // indirect
+	github.com/redis/go-redis/extra/redisotel/v9 v9.14.0 // indirect
+	github.com/redis/go-redis/v9 v9.14.1 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/segmentio/kafka-go v0.4.49 // indirect
+	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
+	github.com/xdg-go/scram v1.1.2 // indirect
+	github.com/xdg-go/stringprep v1.0.4 // indirect
+	go.opencensus.io v0.24.0 // indirect
+	go.opentelemetry.io/auto/sdk v1.1.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc v0.62.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/httptrace/otelhttptrace v0.63.0 // indirect
+	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.63.0 // indirect
+	go.opentelemetry.io/otel v1.38.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.38.0 // indirect
+	go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.38.0 // indirect
+	go.opentelemetry.io/otel/exporters/prometheus v0.60.0 // indirect
+	go.opentelemetry.io/otel/exporters/zipkin v1.38.0 // indirect
+	go.opentelemetry.io/otel/metric v1.38.0 // indirect
+	go.opentelemetry.io/otel/sdk v1.38.0 // indirect
+	go.opentelemetry.io/otel/sdk/metric v1.38.0 // indirect
+	go.opentelemetry.io/otel/trace v1.38.0 // indirect
+	go.opentelemetry.io/proto/otlp v1.7.1 // indirect
+	go.uber.org/mock v0.6.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.2 // indirect
+	golang.org/x/crypto v0.45.0 // indirect
+	golang.org/x/exp v0.0.0-20251023183803-a4bb9ffd2546 // indirect
+	golang.org/x/net v0.47.0 // indirect
+	golang.org/x/oauth2 v0.33.0 // indirect
+	golang.org/x/sync v0.18.0 // indirect
+	golang.org/x/sys v0.38.0 // indirect
+	golang.org/x/term v0.37.0 // indirect
+	golang.org/x/text v0.31.0 // indirect
+	golang.org/x/time v0.14.0 // indirect
+	google.golang.org/api v0.256.0 // indirect
+	google.golang.org/genproto v0.0.0-20250603155806-513f23925822 // indirect
+	google.golang.org/genproto/googleapis/api v0.0.0-20250825161204-c5933d9347a5 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20251103181224-f26f9409b101 // indirect
+	google.golang.org/grpc v1.76.0 // indirect
+	google.golang.org/protobuf v1.36.10 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+	modernc.org/libc v1.66.10 // indirect
+	modernc.org/mathutil v1.7.1 // indirect
+	modernc.org/memory v1.11.0 // indirect
+	modernc.org/sqlite v1.40.1 // indirect
+)