Identity Management

Bosca provides a complete identity management system covering user registration, authentication, credential management, and session handling. It is built on top of the Security layer and integrates with Profiles and Messaging for a seamless user experience.

Core Concepts

Principals

A Principal is a user identity in Bosca. Every principal has a unique ID, a verification status, and an optional link to a primary profile.

Key attributes:

• verified — whether the principal's email has been confirmed
• anonymous — whether the principal is an unauthenticated guest
• primaryProfileId — links the principal to their default Profile
• attributes — optional JSON metadata attached to the identity

Credentials

Each principal authenticates using one or more credentials. Bosca supports three credential types:

• PASSWORD — passwords hashed with Argon2id (the modern default)
• PASSWORD_SCRYPT — passwords hashed with scrypt (for migrated accounts)
• OAUTH2 — third-party provider tokens (Google, Facebook, Apple, or any OpenID Connect provider)

A single principal can have multiple credentials—for example, a password and a linked Google account.

Groups & Permissions

Principals are assigned to Groups, and groups receive Permissions on specific entities. See Security for full details on the permission model.

Groups have two types:

• PRINCIPAL — created and managed by users or organizations
• SYSTEM — managed internally by Bosca (e.g., Administrators)

Authentication Methods

Bosca supports several ways to authenticate:

Password Login

Users sign up with an identifier (typically an email) and a password. Passwords are hashed with Argon2id using BouncyCastle and are never stored in plain text.

mutation {
  security {
    login {
      password(identifier: "user@example.com", password: "secret") {
        token { token expiresAt }
        principal { id verified }
        refreshToken
      }
    }
  }
}

OAuth2 / OpenID Connect

Bosca has built-in support for third-party authentication via OAuth2. Providers are configured in application.yaml and each provider specifies:

• clientId and clientSecret
• authorizeUrl and accessTokenUrl
• userInfoUrl for fetching the user's profile
• scopes for the requested permissions
• callback URLs for redirect handling

Built-in provider adapters include:

• Google / Generic OIDC — uses the standard DefaultOauth2User model (parses given_name, family_name, picture, email)
• Facebook — uses a dedicated FacebookUser adapter that extracts the profile picture from Facebook's nested picture object

During OAuth2 login, Bosca:

1. Redirects the user to the provider's authorize URL with a state token (cached for verification)
2. Receives the callback with an authorization code
3. Exchanges the code for an access token
4. Fetches user info from the provider
5. Creates or links the principal and issues a JWT session

OAuth2 flows also support signup tokens, allowing users who authenticate via a provider to simultaneously join an Organization.

Refresh Tokens

Login responses can include a refreshToken for long-lived sessions. Use it to obtain a new JWT without re-entering credentials:

mutation {
  security {
    login {
      refreshToken(refreshToken: "...") {
        token { token expiresAt }
      }
    }
  }
}

Expired refresh tokens are automatically cleaned up by the system.

JWT Tokens

All authenticated sessions use JWT tokens signed with HMAC-SHA256. Token configuration includes:

• issuer and audience — validated on every request
• realm — the authentication realm
• expirationTimeInSeconds — configurable token lifetime (default: 3600s)

Bosca accepts tokens via:

• Authorization: Bearer <token> header
• Basic Auth (identifier and password)
• Cookie-based sessions (for browser flows)

Signup & Verification

Password Signup

New users register with an identifier, password, and profile information:

mutation {
  security {
    signup {
      password(
        identifier: "user@example.com"
        password: "secret"
        profile: { 
          name: "Jane Doe" 
          attributes: [] 
          visibility: PUBLIC 
        }
        tokens: [{ type: ORGANIZATION, token: "invite-token" }]
      ) {
        id
        verified
      }
    }
  }
}

Signup tokens allow new users to automatically join an Organization during registration. The supported token type is:

• ORGANIZATION — joins the user to an organization

Email Verification

After signup, Bosca sends a verification email through the Messaging system. The email contains a unique verification token that confirms ownership of the email address.

mutation {
  security {
    signup {
      passwordVerify(verificationToken: "...") 
    }
  }
}

If the original email is missed, users can request it again:

mutation {
  security {
    signup {
      resendPasswordVerification(identifier: "user@example.com")
    }
  }
}

Password Recovery

Bosca includes a complete forgot-password flow that integrates with Messaging:

1. Request reset — triggers an email with a reset token:

   mutation {
     security {
       login {
         forgotPassword(identifier: "user@example.com")
       }
     }
   }
   

2. Reset password — uses the token from the email to set a new password:

   mutation {
     security {
       login {
         resetPassword(token: "...", password: "newSecret")
       }
     }
   }
   

Principal Management

Authenticated users can manage their own identity:

• Change password — requires the old password for verification:

  mutation { security { principal { password(oldPassword: "old", newPassword: "new") } } }
  

• Change identifier — update the login identifier (email):

  mutation { security { principal { identifier(identifier: "new@example.com", password: "current") } } }
  

• Set primary profile — choose which profile is the default:

  mutation { security { principal { setPrimaryProfile(profileId: "...") } } }
  

Administrators can also manage other principals:

• Add or remove group memberships
• List and search principals
• Expire all refresh tokens system-wide

How It Fits Together

• Profiles: Every principal can have one or more Profiles for personalization and display.
• Organizations: Signup tokens and email-domain auto-join integrate identity with Organizations.
• Messaging: Verification emails and password-reset emails are sent through the Messaging layer.
• Security: Identity management builds on top of the Security group and permission model.

For Developers

The identity system is implemented across two modules:

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

Key extension points:

• Add an OAuth2 provider: Add a new entry to the oauth2.providers list in configuration and, if the provider's user-info response differs from the standard OIDC format, create a new ThirdPartyUser adapter (see FacebookUser for an example).
• Custom email templates: Implement EmailTemplate to provide custom HTML/text content for verification or password-reset emails.
• Custom password encoding: Implement PasswordEncoder<T> for alternative hashing strategies.