skybridge/sso-permission-integration.md

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:

<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:

// 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:

// Store user permissions in context
ctx = context.WithValue(ctx, "user_permissions", userPermissions)

Permission Validation Examples

Application Access Control

// Check if user can create applications
if hasPermission(userPermissions, "app.write") {
    // Allow application creation
}

Token Management

// Check if user can create tokens for specific app
if hasPermission(userPermissions, "token.create") && 
   hasAppAccess(userID, appID) {
    // Allow token creation
}

Hierarchical Permission Checking

// internal.* includes all permissions
// app.* includes app.read, app.write, app.delete
// token.* includes token.read, token.create, token.revoke