Skip to main content
User and role management in Halo allows you to control who can access your site’s admin dashboard and what actions they can perform.

​
Understanding users and roles

Users are individual accounts that can log in to your Halo site. Each user has:
  • A unique username and email address
  • Personal profile information
  • One or more assigned roles
Roles define what users can do. They contain:
  • A set of permissions (policy rules)
  • Access to specific resources and actions
  • Can be assigned to multiple users
Halo uses a role-based access control (RBAC) system. Instead of assigning permissions directly to users, you assign roles, and those roles contain the permissions.

​
Managing users

​
Creating a user

1

Navigate to users

From the admin dashboard, click on Users in the sidebar.
2

Create new user

Click the New User button to open the user creation form.
3

Enter user details

Fill in the required information:
  • Username: Unique identifier for login (cannot be changed later)
  • Display Name: The name shown publicly on the site
  • Email: Valid email address for notifications and password recovery
  • Password: Initial password (user can change this later)
4

Configure profile

Add optional profile information:
  • Avatar: Upload a profile picture
  • Phone: Contact phone number
  • Bio: Short biography or description
5

Assign roles

Select one or more roles to assign to the user. Roles determine what the user can do.
6

Set account status

Choose whether the account is:
  • Active: User can log in and access assigned resources
  • Disabled: User cannot log in
7

Save the user

Click Save to create the user account.
New users receive an email notification with their account details. Make sure your email settings are configured correctly in Settings > Email.

​
Editing user information

To update a user’s profile or settings:
1

Find the user

Navigate to Users and locate the user you want to edit. Use the search bar to find users quickly.
2

Open the editor

Click on the user’s name or the Edit button to open the user editor.
3

Make changes

Update profile information, change assigned roles, or modify account settings.
4

Save changes

Click Update to save your changes.

​
Resetting user passwords

If a user forgets their password:
1

Open user editor

Navigate to Users, find the user, and click Edit.
2

Reset password

Look for the Reset Password option or section.
3

Set new password

Enter a new temporary password or send a password reset email to the user.
4

Save and notify

Click Save and inform the user about the password change. They should change it on next login.
Encourage users to set up two-factor authentication (2FA) for enhanced security. Users can enable 2FA in their profile settings.

​
Disabling user accounts

To temporarily prevent a user from logging in:
1

Open user editor

Navigate to Users, find the user, and click Edit.
2

Disable account

Toggle the Disabled option to prevent the user from logging in.
3

Save changes

Click Update to apply the change. The user will be logged out immediately.

​
Deleting users

To permanently remove a user account:
1

Reassign content

Before deleting, reassign the user’s posts, pages, and other content to another user.
2

Locate the user

Navigate to Users and find the user you want to delete.
3

Delete the user

Click the Delete button next to the user’s name.
4

Confirm deletion

Confirm the action when prompted. The user account will be permanently removed.
Deleting a user account cannot be undone. Ensure you’ve backed up any important data and reassigned their content before proceeding.

​
Managing roles

​
Understanding default roles

Halo includes several built-in roles:
  • Super Administrator: Full access to all features and settings
  • Administrator: Can manage content, users, and most settings
  • Editor: Can publish and manage all content
  • Author: Can create and publish their own content
  • Contributor: Can create content but cannot publish
  • Subscriber: Can only manage their own profile and read content
Built-in roles are system-reserved and cannot be deleted, but you can create custom roles with specific permissions tailored to your needs.

​
Creating a custom role

1

Navigate to roles

From the admin dashboard, click on Roles in the sidebar.
2

Create new role

Click the New Role button to open the role creation form.
3

Enter role details

Fill in the required information:
  • Name: Internal identifier for the role (e.g., “marketing-manager”)
  • Display Name: Human-readable name (e.g., “Marketing Manager”)
4

Define permissions

Add policy rules to specify what this role can do:
  • API Groups: Which API groups the role can access
  • Resources: Which resource types (posts, pages, users, etc.)
  • Verbs: What actions (create, read, update, delete, list)
  • Resource Names: (Optional) Specific resource instances
5

Set role dependencies

(Optional) Specify if this role depends on other roles or aggregates permissions from other roles.
6

Save the role

Click Save to create the custom role.
Creating custom roles requires understanding Halo’s permission model. Incorrectly configured roles can lead to security issues or prevent users from accessing needed features.

​
Understanding policy rules

Policy rules define permissions in Halo. Each rule specifies:
  • API Groups: The API group containing the resources (e.g., “content.halo.run”, "")
  • Resources: The resource types (e.g., “posts”, “pages”, “users”)
  • Verbs: Allowed actions (e.g., “get”, “list”, “create”, “update”, “delete”)
  • Resource Names: (Optional) Specific resource instances to restrict access to
Example policy rule: 
{
  "apiGroups": ["content.halo.run"],
  "resources": ["posts"],
  "verbs": ["get", "list", "create", "update"]
}
This rule allows getting, listing, creating, and updating posts in the “content.halo.run” API group.

​
Editing roles

To modify an existing custom role:
1

Find the role

Navigate to Roles and locate the role you want to edit.
2

Open the editor

Click on the role name or the Edit button.
3

Modify permissions

Add, remove, or modify policy rules to change what the role can do.
4

Save changes

Click Update to apply the changes. Users with this role will immediately have updated permissions.
Changing role permissions affects all users assigned to that role. Test permission changes carefully to avoid accidentally granting or removing critical access.

​
Deleting custom roles

To remove a custom role:
1

Unassign users

Before deleting, reassign users to different roles or they will lose access.
2

Navigate to roles

Go to Roles in the admin dashboard.
3

Delete the role

Click the Delete button next to the role name.
4

Confirm deletion

Confirm the action when prompted. The role will be permanently removed.
System-reserved roles (built-in roles) cannot be deleted. You can only delete custom roles you’ve created.

​
Assigning roles to users

You can assign multiple roles to a single user:
1

Edit the user

Navigate to Users, find the user, and click Edit.
2

Manage role assignments

In the Roles section, select or deselect roles to assign or remove them.
3

Save changes

Click Update to apply the role assignments.
When a user has multiple roles, they receive the combined permissions of all assigned roles. Halo automatically aggregates permissions from all roles.

​
Understanding role aggregation

Halo supports role aggregation, where roles can inherit permissions from other roles:
  • Aggregate roles: Automatically include permissions from roles with specific labels
  • Role dependencies: Explicitly specify which roles this role depends on
This allows you to create modular permission sets and compose complex roles from simpler ones.

​
Email verification

Users can be required to verify their email addresses:
1

User registration

When a user registers or has their email changed, they receive a verification email.
2

Click verification link

The user clicks the link in the email to verify their address.
3

Email verified

Once verified, the user’s account is marked as email-verified, and they can access features requiring verification.
You can configure email verification requirements in Settings > Security. Some features may require verified email addresses for access.

​
Two-factor authentication (2FA)

Users can enable 2FA for enhanced security:
1

Access user profile

The user logs in and navigates to their profile settings.
2

Enable 2FA

The user toggles the Two-Factor Authentication option.
3

Scan QR code

Using an authenticator app (Google Authenticator, Authy, etc.), the user scans the displayed QR code.
4

Enter verification code

The user enters a code from their authenticator app to confirm setup.
5

Save backup codes

The user saves the provided backup codes in a secure location for account recovery.
Encourage all users with administrative access to enable 2FA for improved account security.

​
Hidden users

Some users may be marked as hidden:
  • Hidden users don’t appear in public author lists or contributor pages
  • They can still log in and perform their assigned tasks
  • This is useful for service accounts or internal users
To mark a user as hidden, add the appropriate label in the user’s metadata settings.

​
Best practices for user and role management

  • Follow principle of least privilege: Give users only the permissions they need
  • Use roles, not direct permissions: Always assign permissions through roles, not directly to users
  • Regular audits: Periodically review user accounts and role assignments
  • Remove inactive accounts: Disable or delete accounts that are no longer needed
  • Document custom roles: Keep notes about what each custom role is for
  • Test new roles: Create test users to verify role permissions before assigning to real users
  • Require strong passwords: Enforce password complexity requirements
  • Enable 2FA for admins: Require two-factor authentication for users with administrative access
  • Monitor user activity: Regularly review logs for suspicious user activity
  • Maintain role hierarchy: Keep your role structure simple and easy to understand

Build docs developers (and LLMs) love

Get started for freeTalk to us