Enabling role based authorization

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

​

Roles

Roles are used to grant permissions 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.

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

   Viewer {
      grantedAuthorities = [ "BrowseCatalog" ]
   }
}

​

List of default roles

The following roles are shipped by default:

​

Assigning users to roles

Roles are assigned based on the JWT token presented by your OIDC server.

By default, if your OIDC server does not present any roles, a user who logs in will not be able to do anything, and will see an empty navbar.

In order to grant roles, you’ll need to assign one of the roles to your users within your OIDC platform.

Orbital will work with any OIDC compliant server. Orbital ships with defaults against Keycloak, which is a common OSS OIDC server. However, you can use whichever OIDC server you wish.

​

Configuring specific IDPs

​

Keycloak

The following steps were tested against Keycloak 22. Actual steps may vary depending on your version or configuration - use Keycloak’s docs to configure accordingly.

• Log into the realm admin in Keycloak
• Navigate to your realm, and select Realm roles in the left hand navbar
• Click “Create Role”
• Add a role from above. (eg., Admin), and click Save
• Navigate to Users, and select the user you wish to manage
• Click role Mapping
• Click Assign Role, and select the Admin role, and click Assign

If your user was previously logged in to Orbital, they’ll need to log out & in again to refresh their token.

​

AWS Cognito

AWS uses Groups to populate the cognito:groups claim in the provided JWT. Here’s how to configure this:

​

Create the group / role

1. In AWS Cognito, navigate to the User Pool for Orbital.
2. Click Groups, and create a group. The name of the group should match a role. (eg: Admin)
3. Assign users to the role.

​

Configuring Orbital

To configure Orbital to read the roles from the JWT passed by Cognito, the following params are required:

--vyne.security.openIdp.roles.format=path
--vyne.security.openIdp.roles.path="cognito:groups"

After this, Orbital should now work with authentication and authorization via Cognito

​

Azure

Ensure you’ve first set up Orbital as an AD Application, as described in the Configuring Azure Authentication.

​

Creating roles

1. Inside Azure, navigate to Microsoft Entra ID, then select App registrations from the left navigation bar
2. Select the application you created earlier.
3. Select App roles
4. Select Create App role:
   • The display name and Value should match a configured role (eg: Admin).
   • Set “Allowed member types” to Users/Groups
   • Click Apply

​

Assigning users to roles

1. Inside Azure, navigate to Enterprise Applications
2. Select the application you created earlier.
3. Click Assign users and groups
4. Select the checkbox next to a user, and then click Edit Assignment, and select the role

Repeat to assign roles as required

​

Configuring Orbital

To configure Orbital to read the roles from the JWT passed by Azure, the following params are required:

--vyne.security.openIdp.roles.format=path
--vyne.security.openIdp.roles.path="roles"

After restarting Orbital, users roles will now be passed from Azure to Orbital and read from the JWT.

​

Other IDPs: Reading roles from JWT Tokens

Orbital expects the user’s roles be present in the claims, as list of strings provided under a roles key.

There is no universal standard of how OIDC servers provide roles within JWT tokens, therefore some configuration may be required.

Orbital is configured to work with Keycloak by default, which publishes roles at realm_access.roles.

You can configure a different path by adding the following parameters:

Orbital expects that each part within the token is a Map, except for the last path, which should be a String[].

If you need more complex support for your OIDC, please reach out to us on Slack to discuss your requirements.

​

Permissions

Orbital ships with the following permissions.

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

​

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.