Security
Authenticate accounts, manage credentials, and understand access tokens and sign-in sessions.
Principals and profiles
A Principal is an account's security identity. It owns credentials, sign-in sessions, and group memberships. A Profile stores social and contact information and has a separate ID. A principal can own multiple profiles.
Authentication methods
- Passwords: stored as Argon2 hashes. Existing Scrypt password credentials are supported.
- OAuth2: configured third-party providers can sign in or link credentials to an account.
- Passkeys: WebAuthn credentials use public keys and authenticator sign counters.
- API tokens: separate programmatic access records, stored as SHA-256 hashes with optional scopes and allowed groups.
Enable OAuth2 providers in the deployment configuration. Query security.thirdPartyProviders for the enabled providers. Email verification and password recovery require a configured mailer.
Password login
Send this operation to /graphql with the account's identifier and password as GraphQL variables. On the local Compose instance, the initial identifier is admin.
The access token is the string at data.security.login.password.token.token. Send it in Authorization: Bearer TOKEN for subsequent programmatic requests. expiresAt is a Unix timestamp in seconds. A refresh token is returned when enabled.
Refresh the session
Refresh tokens are single-use. Store the newly returned refresh token along with the access token; retrying with the consumed token fails. A revoked sign-in cannot refresh.
Sign-in history and sign-out
signOut revokes the current recorded sign-in and clears its session cookie, leaving other recorded sign-ins active. security.principal.revokeLogin(loginId: ...) revokes a selected sign-in owned by the current principal.
JWTs also carry a tver claim checked against Principal.tokenVersion. Password changes, resets, identifier changes, and account deletion can invalidate all sessions. Signing out a token without a recorded login uses account-wide revocation.
Signup and account linking
New clients should use security.signup.passwordV2, thirdpartyV2, and passwordVerifyV2. Their SignupResult can contain a principal, a login response, or a link challenge. If signup encounters an existing verified account, complete the challenge through security.link using password proof or email proof.
Third-party token exchange is available through security.signup.thirdpartyV2; connecting an additional method uses security.connectThirdParty. Browser OAuth2 flows use the configured provider routes.
Programmatic access
Create and manage tokens through Studio, security.apiTokens, or the CLI. The raw token is returned once at creation. Scopes and allowed groups restrict the account's authority; they do not grant access the account does not already hold.
Browser applications
Bosca's Nuxt applications use @bosca/auth-client-browser and the existing same-origin proxy routes. Reuse the auth plugin and middleware for SSR and client navigation. The library manages browser-readable tokens and refresh scheduling; avoid implementing a separate cookie parser or token lifecycle.
Where to look in the workspace
GraphQL fields are defined in bosca-core/security/src/main/resources/graphql/security/. Authentication behavior lives in SecurityServiceImpl; API authorization is covered by Permissions.