sso

sso-permission-integration.md

@@ -0,0 +1,76 @@
+# SSO Permission Integration Guide
+
+## How SSO Permissions Work with Your KMS
+
+### 1. Keycloak Integration (OAuth2/OIDC)
+
+**In Keycloak Admin Console:**
+1. Go to Clients → kms-api → Client Scopes
+2. Create custom scopes for your permissions:
+   - `kms:admin` → Maps to `internal.*`
+   - `kms:app-manager` → Maps to `app.*` + `token.*`
+   - `kms:read-only` → Maps to `*.read`
+
+**In User Attributes:**
+- Add custom attributes to users: `permissions: ["internal.admin", "app.read", "token.create"]`
+- These get included in JWT tokens
+- Your KMS validates these against the `available_permissions` table
+
+### 2. SAML Integration
+
+**In SAML Assertions:**
+```xml
+<saml:Attribute Name="permissions">
+    <saml:AttributeValue>internal.admin</saml:AttributeValue>
+    <saml:AttributeValue>app.read</saml:AttributeValue>
+    <saml:AttributeValue>token.create</saml:AttributeValue>
+</saml:Attribute>
+```
+
+### 3. Code Integration Points
+
+**In your OAuth2 callback handler:**
+```go
+// Extract permissions from token claims
+userInfo, err := oauth2Provider.GetUserInfo(accessToken)
+permissions := userInfo.Claims["permissions"]
+
+// Validate against your permission system
+for _, perm := range permissions {
+    if !isValidPermission(perm) {
+        return errors.New("Invalid permission: " + perm)
+    }
+}
+```
+
+**In your authentication middleware:**
+```go
+// Store user permissions in context
+ctx = context.WithValue(ctx, "user_permissions", userPermissions)
+```
+
+## Permission Validation Examples
+
+### Application Access Control
+```go
+// Check if user can create applications
+if hasPermission(userPermissions, "app.write") {
+    // Allow application creation
+}
+```
+
+### Token Management
+```go
+// Check if user can create tokens for specific app
+if hasPermission(userPermissions, "token.create") && 
+   hasAppAccess(userID, appID) {
+    // Allow token creation
+}
+```
+
+### Hierarchical Permission Checking
+```go
+// internal.* includes all permissions
+// app.* includes app.read, app.write, app.delete
+// token.* includes token.read, token.create, token.revoke
+```