Deploying Orbital

Enabling role based authorization


In order to use role based authentication, you must have configured authorization with an OpenID Connect provider.

Learn how to enable authorization

Orbital uses role based authorization to control which users can perform which tasks.

First time usage

The first user to log into Orbital through OpenID is automatically assigned the Admin role, allowing them to perform any action across the platform.

At this point, all required config files are also generated (if not already present), and populated with reasonable defaults.


Roles are used to grant authorities to users - which allow users to perform different actions on the Orbital platform.

The roles themselves are configurable. Orbital ships with a set of reasonable default roles - but you may choose to modify these, or build your own.

Roles are configured in a config file, typically found at config/roles.conf.

If the file is not present on startup, a new file is created the first time a user logs in.

// Determines the role assigned to users by default when they first log in.
defaultUserRoleMappings {
  roles = [ "Viewer" ]

// Determines the role assigned to API users the first time they access the platform.
defaultApiClientRoleMappings {
  roles = [ "QueryRunner" ]

// Defines roles, and assigns them authorities.
// Users who are granted these roles will be authorised to perform
// the related activities
grantedAuthorityMappings {
   Admin {
      grantedAuthorities = [   "RunQuery",

   Viewer {
      grantedAuthorities = [ "BrowseCatalog" ]

List of default roles

The following roles are shipped by default:

RoleGranted Authorities

Assigning users to roles

Users are mapped to roles in a config file. By default, this file is located at config/user-role-mappings.conf.

A sample of this file is shown:

userRoleMappings {
    jimmy {
        type=USER // Either USER or API

This file is automatically updated with new entries for users after the first time they log in.

Coming soon

At present, the only way to edit user-to-role mappings is by modifying this file, and subsequently restarting the server.

We’re working on better user mapping tools through the UI, which will be available in a future release.

If this is something you’re interested in, reach out to us on slack


Orbital ships with the following authorities.

In order to perform an activity, users be associated with a role that grants the related authority.

ActivityRequired authority
Issue a query through the UIRunQuery
Issue a query through the APIRunQuery
Cancel a running queryCancelQuery
Browse the query history in the UIViewQueryHistory
View the results of historic queriesViewHistoricQueryResults
Browse the data catalogBrowseCatalog
View the registered schemasBrowseSchema
Modify a catalog entryEditSchema
Import a new schema through the schema importer UIEditSchema
List casksViewCaskDefinitions
Create a new caskEditCaskDefinitions
List pipelinesViewPipelines
Add a new pipelineEditPipelines
Edit an existing pipelineEditPipelines
View authentication tokens Orbital uses in requestsViewAuthenticationTokens
Edit authentication tokens Orbital uses in requestsEditAuthenticationTokens
View configured data sourcesViewConnections
Edit configured data sourcesEditConnections

Authorisation parameters

The following parameters are configurable, by passing values to Orbital on startup. The values all have reasonable defaults, and it’s uncommon to change these. However, they can be configured as required.

ParameterDescriptionDefault value to a file which defines roles and their granted authoritiesconfig/roles.conf to a file which lists users, and their assigned rolesconfig/user-role-mappings.conf name of the role which grants admin privileges.Admin
Authentication to Orbital
Distributing work across a cluster