Role and Access Control
Overview
The Beneficiary platform supports role-based access control to differentiate between actions available to beneficiaries and admins. Roles are managed primarily in Keycloak and must also be reflected in the application database to ensure consistency.
Default Roles
When a user registers through the Beneficiary UI, they are automatically assigned the beneficiary role.
No admin user can be created from the Beneficiary UI.
Adding an Admin Role
Since admin users cannot be created via the Beneficiary UI, they must be added manually in both Keycloak and the backend database.
1. Add Admin in Keycloak
Log in to the Keycloak Admin Console.
Navigate to Users → Add User.
Fill in required details (e.g., username = admin).
Join group → Select admin →Click Join
Create the user.
Go to Credentials → Add credentials.
Enter Password
Disable Temporary so the password does not need to be reset.
Save credentials.
Save the changes.
2. Add Admin in the Database
The corresponding admin entry must exist in the application’s backend database. Ensure you insert a record in the users table with a UUID and role reference.
Example (PostgreSQL):
-- Ensure uuid-ossp extension is enabled
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
---- Insert an admin user
INSERT INTO public.users (
id, user_id, "firstName", "lastName", email, "phoneNumber", dob,
sso_provider, sso_id, created_at, updated_at, "fieldsVerified"
) VALUES (
DEFAULT, uuid_generate_v4(), 'admin', 'Admin', 'admin@example.com',
'9999999999', '2000-01-01', 'keycloak','<keycloak-user-id>', NOW(), NOW(), false
);
⚠️ Replace <keycloak-user-id> with the id value of the corresponding Keycloak user. ⚠️ Ensure that the backend services are running successfully (Keycloak, Hasura, and Beneficiary backend)..
Role Impact on API Access
Beneficiary Role: Grants access to beneficiary APIs (e.g., profile management, benefits listing, claims).
Admin Role: Grants elevated access, including:
Access to Admin Configuration Panel
APIs for configuring documents, fields, and field mappings.
Last updated