Skip to main content

Axvero Technical Documentation: Authentication & Authorization Integration

Overview​

Axvero integrates with an external authentication/authorization provider to manage organizations, teams, roles, and permissions. The API is provider-agnostic and does not reference any specific provider (e.g., Keycloak) in its schema or documentation. This document explains the integration approach and how Axvero references external entities for business logic.

Integration Architecture​

  • Organization: Managed by the external provider as an organization entity.
  • Team/Functional Role: Managed as a group under the organization in the external provider.
  • Roles/Permissions: Assigned to groups/subgroups in the external provider. All team membership and role assignment is managed externally.
  • Axvero API: References organizationId and authGroupId only. No provider-specific names or logic are present in the API.

Axvero API Model References​

  • organizationId: Unique identifier for the organization in the external provider.
  • authGroupId: Unique identifier for the group/team in the external provider.

Example Mapping (Provider-Agnostic)​

  • Organization: "Acme Corp" (organizationId)
  • Team: "Acme Corp/Underwriters" (authGroupId)
  • Team: "Acme Corp/CustomerSupport" (authGroupId)
  • Roles: "underwriter", "customer_support" (assigned to groups in the external provider)

Rationale​

  • All team membership and role assignment is managed by the external provider.
  • Axvero does not store or manage team roles/permissions internally.
  • The API is future-proof and can be integrated with any provider supporting organizations, groups, and roles.

Notes​

  • No provider-specific details (e.g., Keycloak) are present in the API or this documentation.
  • Any provider-specific implementation details should be documented separately and not included in the Axvero API specification.

Keycloak Implementation Logic for Axvero​

1. User, Organization, Team, and Role Management​

  • User: Managed in Keycloak. Each user has a single profile in Keycloak (with extensible attributes). Axvero manages multiple user profiles (e.g., resumes, business cards) in its own database.
  • Organization: Managed as a Keycloak Organization. Each organization has a unique organizationId.
  • Team/Functional Role: Managed as a Keycloak group under the organization (e.g., Acme Corp/Underwriters). Each group has a unique authGroupId.
  • Roles/Permissions: Assigned to groups/subgroups in Keycloak. All team membership and role assignment is managed in Keycloak. Axvero does not manage roles or permissions internally.

2. Invitation Workflow​

  • Invitations: Keycloak Organizations support inviting users (by email or userId) to join organizations and groups. Invitation status, history, and custom metadata (e.g., who invited, purpose) can be managed using Keycloak's invitation features and custom attributes.
  • Email Customization: Invitation emails can be customized globally using FreeMarker templates. Organization-specific branding (e.g., logo) can be achieved by adding custom attributes (e.g., logoUrl) to the organization and referencing them in the template.

3. Profile and Document Management​

  • Multiple Profiles per User: Not supported natively in Keycloak. Axvero manages multiple user profiles in its own database using the UserProfile model.
  • Profile/Document Sharing: Sharing of profiles and documents is managed in Axvero using UserProfileShare and DocumentShare models. Permissions for sharing are handled at the application level.

4. Axvero API Model References​

  • organizationId: Unique identifier for the organization in Keycloak.
  • authGroupId: Unique identifier for the group/team in Keycloak.

5. What is NOT in Axvero​

  • No user-to-user links (e.g., parent, partner, member) are modeled in Axvero. All relationships are handled via application-specific entities (e.g., Application.applicantUserIds) and sharing models.
  • No team membership, role, or invitation logic is duplicated in Axvero. All such logic is managed by Keycloak.

6. Implementation Guidance​

  • Always use Keycloak as the source of truth for users, organizations, teams, and roles.
  • Use Axvero only for application-specific metadata, multiple user profiles, and sharing logic.
  • When displaying team or organization names in the UI, use the Team model in Axvero to map authGroupId to a human-readable label if needed.
  • For any advanced invitation or branding requirements, use Keycloak's custom attributes and FreeMarker template logic.

Last updated: 2025-12-11