user-management-and-permissions.md

User Management and Permissions

Introduction

This article describes how to set up and manage Gravitee roles, scopes, permissions, users, and user groups.

• Roles
• Permissions
• Users and user groups

Roles

A role is a functional group of permissions and can be defined at the Organization, Environment, API, and/or Application level. Gravitee includes pre-built default roles and also allows you to create an unlimited number of custom user roles. Each role:

• Is associated with a group of permissions
• Has a scope, which encompasses the API Management resources available to the user. Gravitee scopes comprise the Organization, Environment, API, and Application levels.
• Defines what you can do with APIM UI components and the APIM Management API

{% hint style="info" %} By default, only a System Admin (a role created by Gravitee) can create and edit roles, including custom roles. {% endhint %}

The APIM Console allows you to add, see members within, and delete roles in the Organization, Environment, API, and Application scopes. To set up roles:

1. Log in to your APIM Console
2. Select Organization from the left nav
3. Select Roles from the User Management section
4. Click + Add a role at your desired scope
   • Give the role a name
   • Give the role a description (optional)
   • Enable the role as a default role for new users by toggling Default tole ON or OFF
   • Set create, read, update, and delete permissions for the role
5. Click Create

Example: Custom "Writer" role

To create a custom "Writer" role:

1. Log in to the API Management Console
2. Select Organizations from the left-hand nav
3. Click Roles under User Management
4. At the API scope, click + Add a role
5. Enter "Writer" in the Role name text field
6. Give the role a description, such as "These users can create, update, read, and delete API documentation."
7. (Optional) To make this the default role for new users, toggle Default role ON
8. Define the following permissions:
   - Read permissions on DEFINITION and GATEWAY_DEFINITION: Allows the user to see the API in the API list
   - CRUD permissions on DOCUMENTATION: Allows the user to write new API documentation
9. Click Create

The "Writer" role now appears in the API scope section.

Permissions

The set of permissions a role has is defined by its scope. The following tables list permissions per scope.

{% tabs %} {% tab title="Organization" %}

Name	Description
ENTRYPOINT	Manages environment entrypoint configuration
ENVIRONMENT	Manages environments
ROLE	Manages roles
TAG	Manages sharding tags
TENANT	Manages tenants
USER	Manages users

{% endtab %}

{% tab title="Environment" %}

Name	Description
ALERT	Manages environment alerting
API	Manages APIs in general. The CREATE action is used to establish if the user is allowed to create an API or not, and the READ permission is used to allow the user to request the policies and resources lists.
API_HEADERS	Manages environment API headers
APPLICATION	Manages applications in general. CREATE allows the user to create an application, READ allows the user to list applications.
AUDIT	Gets APIM audit. Only READ permission is used.
CATEGORY	Manages categories
CLIENT_REGISTRATION_PROVIDER	Manages environment client registration configuration
DASHBOARD	Manages environment dashboards
DICTIONARY	Manages environment dictionaries
DOCUMENTATION	Manages APIM Dev Portal documentation
GROUP	Manages user groups
IDENTITY_PROVIDER	Manages Identity Providers for authentication
INSTANCE	Access to API Gateway instance information. Only READ permission is used.
MESSAGE	Manages messaging
METADATA	Manages APIM metadata
NOTIFICATION	Manages global notifications
PLATFORM	Gets APIM monitoring metrics. Only READ permission is used.
QUALITY_RULE	Manages environment quality rules
SETTINGS	Manages environment settings
THEME	Manages APIM Portal themes
TOP_APIS	Manages top APIs

{% endtab %}

{% tab title="API" %}

Name	Description
ALERT	Manages API alerting
ANALYTICS	Manages API analytics. Only the READ permission is used.
AUDIT	Manages API audits. Only the READ permission is used.
DEFINITION	Manages the API definition
DISCOVERY	Manages service discovery
DOCUMENTATION	Manages API documentation
EVENT	Manages API events. Only the READ permission is used.
GATEWAY_DEFINITION	A specific permission used to update the context-path (UPDATE) and to give access to sensitive data (READ) such as endpoints and paths.
HEALTH	Manages API health checks
LOG	Manages API logs. Only the READ permission is used.
MEMBER	Manages API members
METADATA	Manages API metadata
MESSAGE	Manages messaging
NOTIFICATION	Manages API notifications
PLAN	Manages API plans
QUALITY_RULE	Manages API quality rules
RATING	Manages API rating
RATING_ANSWERS	Manages API rating answers
RESPONSE_TEMPLATES	Manages API response templates
REVIEWS	Manages API reviews
SUBSCRIPTION	Manages API subscriptions
{% endtab %}

{% tab title="Application" %}

Name	Description
ALERT	Manages application alerting
ANALYTICS	Manages application analytics. Only the READ permission is used.
DEFINITION	Manages the application definition
LOG	Manages application logs. Only the READ permission is used.
MEMBER	Manages application members
NOTIFICATION	Manages application notifications
SUBSCRIPTION	Manages application subscriptions
{% endtab %}
{% endtabs %}

{% hint style="warning" %} Enterprise only

Custom Roles is an Enterprise Edition capability. To learn more about Gravitee Enterprise and what's included in various enterprise packages:

• Refer to the EE vs OSS documentation
• Book a demo
• Check out the pricing page {% endhint %}

Users and user groups

In Gravitee, a user is the profile of an individual who uses the platform. User groups are groupings of users that share the same role(s) for the Environment, Organization, API, and/or Application scopes.

{% tabs %} {% tab title="Create and manage users" %}

Create users

Users are created in one of two ways:

• System Administrators can create users
• Users can self-register via a registration form

System Administrator flow

To pre-register a user:

1. Log in to your APIM Console

2. Select Organization from the left nav

3. Select Users under User Management

4. Click + Add user

5. Select User type: Choose between User and Service Account

   Pre-register a user

   

   Add a User user type

   • Enter the user's info: First Name, Last Name, Email
   • Using the drop-down menu, select the Identity Provider name. See IdP configuration for more details.

   Pre-register a service account: Setting up a user as a service account enables somebody from a Gravitee servicer (e.g., partner, consultant) to subscribe to Gravitee email notifications

   

   Add a Service Account user type

   • Enter a Service Name for the service account
   • Enter the service account's email

6. Click Create

Manage users

To delete a user from your Organization, select the Delete user icon from the table on the Users page:

Delete a user

{% endtab %}

{% tab title="Create and manage user groups" %}

Create user groups

To create a user group:

1. Log in to your APIM Console

2. Select Settings from the left nav

3. Under User Management, select Groups

4. Click the plus icon at the bottom of the page

5. Configure the user group

   

   Create a user group

   • General: Enter a name for the user group
   • Roles & Members: define the maximum number of members and choose whether or not to allow:
     • Invitations via user search
     • Email invitations
     • The group admin to change the API role
     • The group admin to change the application role
     • Notifications when members are added to this group
   • Associations: choose whether or not to associate this group to every new API and/or application
   • Actions: CREATE the user group or RESET to the default settings

Once a user group is created, you will be able to:

• Define a default API role by selecting the role from the Default API Role drop-down menu
• Define a default application roles by selecting the role from the Default Application Role drop-down menu
• Choose to associate the user group with existing APIs or Applications by selecting Associate to existing APIs and/or Associate to existing applications
• View all members, associated APIs, and associated applications in the Dependents section

Manage user groups

To manage a user group:

1. Log in to your APIM Console

2. Select Settings from the left nav

3. Under User Management, select Groups

   

   Manage user groups

   • Edit a user group: Click its hyperlink to make changes, then:
     • Reset the user group settings by selecting RESET under Actions
     • Update the user group to save new settings by selecting UPDATE under Actions
   • Delete a user group: Click the delete icon associated with the user group entry {% endtab %} {% endtabs %}