Authorization, Roles, and Permissions

Put simply, authorization and RBAC are ways to control what users can see and do in your product.

Authorization

You can use PropelAuth to authorize access to your product via both your frontend or backend. For example, you can do things display information to your users based on their permissions, or create a backend route that is scoped to users in a certain Organization.

For more information, check out our Frontend Authorization Guide and Backend Authorization Guide.

RBAC (Single Role per User)

PropelAuth comes pre-configured with 3 default roles:

• Owner
• Admin
• Member

Each user can only have one role, and the order of the roles hierarchy dictates that each role has permissions to modify the roles below it.

These roles are scoped to a particular organization, so your users can have the Owner role for one organization and the Member role for another.

These roles also come with a set of permissions related to actions that PropelAuth enables:

• Invite other users
• Change roles for other users
• Remove other users with the roles Owner, Admin, Member, etc
• Manage a SAML / Enterprise SSO connection for their organization
• Manage API keys for their organization. Click here to manage API keys

All of the default roles can be edited, and new roles and permissions can be added.

RBAC (Multiple Roles Per User)

Allow your users to have multiple roles within one organization by converting your project to multi-role.

You can convert your project to allow multiple roles per user by using the Configuration button in the Roles and Permissions page.

Allowing Roles to Manage Other Roles

Instead of the hierarchy of roles that we see with Single Role per User mode, roles can instead be set to manage other roles. For example, let's say we have three roles:

• Mars Admin
• Mars Member
• Earth Member

We can set Mars Admin to manage itself as well as Mars Member.

This allows you to then assign permissions to the Mars Admin role to:

• Send invitations for the Mars Member and Mars Admin roles.
• Provision/deprovision the Mars Member and Mars Admin roles.
• Remove other users with the Mars Member and Mars Admin roles.

However, they will not have any of these permissions for the Earth Member role.

Managing Roles & Permissions within PropelAuth

All roles and permissions can be managed from the Roles and Permissions page within the PropelAuth admin dashboard.

When you change your roles, if the change is backwards incompatible (removing a role, for example), we’ll automatically migrate existing users/invitations with that role.

Internal Roles

Internal roles allow you to add yourself or your employees to organizations without appearing to your users in the hosted pages. This allows for secure internal operations while maintaining a clean user experience for your users.

Create an internal role by navigating to the Roles and Permissions page and clicking on Add Role. Then toggle the Internal Role option.

Here are some key features regarding internal roles:

• Members with internal roles are hidden to your users but are visible on the organization pages within the dashboard.
• The option to assign internal roles are not available to your users via the hosted pages and can only be assigned in your PropelAuth dashboard.
• Internal Users do not contribute to the overall Active Organizations in the User Insights page.

Permissions

Permissions are arbitrary strings associated with a role. For example, can_view_billing, ProductA::CanCreate, and ReadOnly are all valid permissions.

Roles vs. Permissions

Roles are something that your users will see. When your users invite their coworkers to your product, they specify a role for you after you join.

Permissions are something that only you will see. They are optional, but can be helpful if you’d rather write code that says “Show the billing page if this user has the CanViewBilling permission” instead of “Show the billing page for users with the role Admin“.