Security

Bosca's security model is simple to reason about and flexible enough for complex organizations. It's built around four concepts:

• Principals (users)
• Credentials (passwords or OAuth2 providers)
• Groups (roles)
• Permissions (what groups can do)

Authentication options:

• Bearer tokens (JWT), Basic Auth, or cookie-based sessions
• OAuth2 providers are configurable (Google is enabled by default in application.yaml)

How permissions work:

• Assign users (Principals) to Groups
• Grant permissions to Groups (view, edit, manage, delete, execute)
• Apply permissions to Collections, Metadata, and Workflows for fine-grained control

Public content controls:

• Collections can be marked public or publicList to allow unauthenticated access when published
• Metadata can be marked public, publicContent, or publicSupplementary
• Public access is only available when content is in a Published state via Workflows

Why this helps organizations:

• Clear separation of roles and actions reduces mistakes
• Consistent, predictable rules across content types
• Easy to review and audit access

Identity Management

Bosca includes a full-featured identity management system. For complete details, see Identity Management.

Authentication Methods

• Password login — passwords hashed with Argon2id (modern default) or scrypt (migrated accounts), never stored in plain text
• OAuth2 / OpenID Connect — pluggable third-party providers (Google, Facebook, Apple, or any OIDC-compatible provider)
• JWT access tokens — short-lived, HMAC-SHA256-signed tokens with configurable issuer, audience, and expiration
• Refresh tokens — long-lived tokens with automatic expiry cleanup for persistent sessions
• Signup tokens — invitation tokens for joining organizations during registration

User Lifecycle

• Registration — create principals with credentials, profile, and optional signup tokens
• Email verification — token-based confirmation sent via the Messaging layer
• Password recovery — forgot-password and reset-password flows, also delivered through messaging
• Profile management — change identifier (email), password, and primary profile
• Impersonation — administrators can act as other users for troubleshooting

Session & Token Configuration

JWT tokens are configured via application.yaml:

• jwt.secret — HMAC-SHA256 signing key
• jwt.issuer / jwt.audience — token validation claims
• jwt.realm — authentication realm
• jwt.expiration-time — token lifetime in seconds (default: 3600)

OAuth2 providers are configured under oauth2.providers, each specifying clientId, clientSecret, authorizeUrl, accessTokenUrl, userInfoUrl, scopes, and callback URLs.

Technical Reference (for developers)

Principal

type Principal {
    groups: [Group!]!
    id: String!
}

type Group {
    id: String!
    name: String!
}

Credentials

# Supported credential types
enum CredentialType {
    PASSWORD        # Argon2id hashed
    PASSWORD_SCRYPT # scrypt hashed (migrated accounts)
    OAUTH2          # Third-party provider tokens
}

Permissions

enum PermissionAction {
    DELETE
    EDIT
    EXECUTE
    LIST
    MANAGE
    VIEW
}

type Permission {
    action: PermissionAction!
    group: Group!
    groupId: String!
}

Implementation Modules

• backend/framework/core-security — interfaces (SecurityService, PasswordEncoder, ThirdPartyUser)
• backend/framework/security — implementations (Argon2/scrypt encoding, OAuth2 routes, GraphQL controllers, email templates)

See More