# 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
```