Skip to main content
  1. Features
  2. Access, Authentication, & Session Controls
Explanation of Ghostwriter’s role-based access controls
In Ghostwriter <= v3.x, the role-based access controls described on this page apply only to the GraphQL API. In those older versions, user privileges are equivalent to every account having the manager role.

​
Introduction

User roles are the primary authorization mechanism. There are three user roles:
  • User
  • Manager
  • Admin
A Ghostwriter administrator sets a user’s role in the admin panel. All accounts are assigned the user role by default.
If you look in the Hasura GraphQL console, you will also see a public role. Only Hasura uses this role. An unauthenticated request (i.e., any request that lacks a valid token in a request’s Authorization header) is considered to have the public role. Specific webhook endpoints (e.g., login) are accessible to this role.
The roles carry the following privileges:

​
User Role Privileges

The user role can only access project and related client data if they:
  • have been assigned to the project
  • have been invited to access the client
  • have been invited to access the project
Otherwise, this role has the standard permissions you might expect. They can edit or delete their comments, update their profiles, and view the shared information in the various libraries (e.g., findings, domains). When viewing the project history for a domain or server, an account with the user role will only see project details if they can access the project.
A user account can be granted special access to clients and projects via the invite system. Read below for details.

​
Augmenting User Permission

An admin can augment user permissions in the admin console. By default, the user role cannot edit, update, or delete entries in the shared Findings or Observation libraries. If you need to allow a user to maintain these records, grant them the necessary permissions in the admin console under their user record. The Allow Report Template Management augmentation permits a user to create, edit, protect, lint, and delete global report templates without granting the broader client and project visibility of the manager role. This is appropriate for roles such as technical writers who maintain shared report templates. This augmentation does not bypass client authorization. A template manager can manage a client-scoped template only if they already have access to that client. Users without this augmentation may continue creating and editing unprotected templates for clients they can access.

​
Manager Role Privileges

The manager role can view all clients and projects. The role can also:
  • invite others to access client data
  • invite others to access project data
  • assign others to a project
  • create and edit global report templates
  • protect report templates and edit templates flagged as protected
  • delete report templates
If an account is flagged as a Django Superuser that account will automatically inherit the manager role. Users with thr manager role can invite users to have full access to a client or project from the client and project dashboards.

​
Admin Role Privileges

The admin role is only used by the GraphQL API. This role has complete access to everything available via the API. This role can create and manage users and modify fields not exposed to other roles.
Use great care when assigning this role to an account. In general, a user should only ever be a manager or a user.

​
Client and Project Invitations

Someone with the manager or admin role can invite a user to access a client or project via the Invitations tabs on a client dashboard or the People tab on a project dashboard. Invitations help grant access to records without requiring the user be assigned as if they are working on the project. That means invitations are helpful tools for granting access to a client or project without altering the shape of the project team. Client invitations are powerful. A client invite grants access to that client and all of that client’s projects. This is your shortcut for granting someone access to every project for a client, including any future projects. Project invitations grant access to the related client record and the target project, but not the client’s other projects. It’s very similar to a project assignment, but it does not change the shape of the project team. A project assignment and invitation have the same project-level boundary: the user can access the related client record and assigned project, but not the client’s other projects (unless they also have a client invite or another project-specific grant). Invitations can be retracted at any time. The only impact is loss of access for the user.

​
Invitation Case Study

For example, if the ClientA has five projects, Project1-5, and a user is assigned to Project5, they cannot see Project1-4. If you want them to be able to review a previous project to prepare for this new project, you could invite them to Project4. That user would now be able to access ClientA, Project4, and Project5. If you needed them to be able to review all previous projects, a client invitation would be simpler than inviting the user to each individual project. However, it would also grant them access to any future projects under that client. That’s when you may want to retract the client invitation at the end of the project. Client invites are also a good option for regular users who might be managing a specific client and need access to all current and future projects.