Gravitee lexicon and diagram

Documentation

Source

Version in use

3.17.0

Official

• Documentation
  • API management
  • Access management
  • Alert Engine
  • Cockpit
• Source code
  • API Management source code
  • Access Management source code
  • Alert Engine API
  • Cockpit API
  • Gateway
  • Documentation
  • Plugin - Core Framework
  • Policies
• API management swagger

Global architecture

Lexicon

API Management (aka APIM)

Gravitee.io API Management (APIM) is a flexible, lightweight, and blazing-fast open source API management solution that gives your organization full control over who accesses your API — when and how. APIM is both simple to use and powerful, acting as a global solution for API management. Gravitee.io APIM is composed of four main components:

• APIM Gateway.
• APIM API.
• APIM Console.
• APIM Portal.

We'll dive into these components in detail in their respective sections.

APIM Gateway

APIM Gateway is the core component of the APIM platform. You can think of it like a smart proxy.

Unlike a traditional HTTP proxy, APIM Gateway has the capability to apply policies (i.e., rules) to both HTTP requests and responses according to your needs. With these policies, you can enhance request and response processing by adding transformations, security, and many other exciting features.

APIM API

This RESTful API exposes services to manage and configure the APIM Console and APIM Portal web UIs. All exposed services are restricted by authentication and authorization rules. For more information, see the API Reference section.

APIM Console

This web UI gives easy access to some key APIM API services. API Publishers can use it to publish APIs. Administrators can also configure global platform settings and specific portal settings.

APIM Portal

This web UI gives easy access to some key APIM API services. API Consumers can use it to search for, view, try out and subscribe to a published API. They can also use it to manage their applications.

Portal can be accessed even if you're not connected (anonymous user). But if you want to play with an API, a user account is required to subscribe to plans.

Default view in portal shows all the API accessible to the authenticated user (or only public API for anonymous user).

What are the rules for API accessibility:

• Public API
• Private API: if user is a member of the API (user, owner, primary_owner)

Access Management (aka AM)

API access management ensures that only authenticated and authorized clients can successfully complete a call to an API. One goal of API access management is to separate mapping roles to users or groups from enforcing policies, which allows the separation of responsibilities for management tasks.

Gravitee.io Access Management allows you to manage users, groups and roles to ensure the proper information and authorization is given for the right people.

Tools like user/group provisioning, user registration, roles mapping and custom HTML templates will help you perform end-to-end identity management flows.

Gravitee.io Access Management (AM) is a flexible, lightweight and easy to use open source Identity and Access Management solution. It offers a centralized authentication and authorization service to deliver secure access for authorized users to your applications and APIs from any device

Security domains

A security domain is a series of security policies applied to a set of clients that share common security mechanisms for authentication, authorization and identity management. A security domain manage a set of clients, users and identity providers.

Identity Providers

An identity provider is usually a service used to authenticate and communicate authorization and user information. It can be social providers like Facebook, Google or Twitter, enterprise provider such as an Active Directory or custom providers like Databases.

Client

Clients are applications that act on behalf of the user to request tokens, user identity information and retrieve protected resources from remote services and APIs.

Login Page

Gravitee.io Access Management provides a default login page used by clients whenever a user wants to sign in to a Gravitee.io AM. You can override this default login page to suit your needs.

Certificate

Cryptographic algorithms such as KeyStore (private/public key) used to sign using JSON-based data structures (JWT) tokens. Certificates are used as part of the OpenID Connect protocol to sign ID tokens and ensure the integrity of the ID tokens' payload.

Logging

Gravitee.io Access Management provides an Audit Trail feature to record a set of events which occur when users interact with Gravitee.io AM.

Sign-in/Sign-off, User Management and all admin actions are stored in database or on remote systems (via plugins) and can be reviewed from the Portal UI or the Management API of Gravitee.io AM.

Account

The top level entity, your company. One user can have multiple accounts.

Organization

A logical part of your company in the way that makes most sense in your setup, for example a region or business unit. In the context of an AM installation it is the level at which shared configurations for environments are managed, such as:

• User permissions to access the AM console
• Roles
• Identity providers to access the AM console

Environment

An environment in an IT infrastructure, such as development or production. There can be multiple environments linked to one organization. In the context of an AM installation, it is the workspace in which users can manage their security domains and applications.

Examples of environments:

• technical environments such as DEV / TEST / PRODUCTION
• functional environments such as PRIVATE DOMAINS / PUBLIC DOMAINS / PARTNERSHIP

An environment belongs to one organization.

Installation node

APIM and AM installations, linked to environments in Cockpit. Each linked APIM and AM installation automatically reports its REST API and Gateway nodes to Cockpit.

Gravitee Cockpit (aka Cockpit)

Gravitee Cockpit is a centralized, multi-environment tool for managing all your Gravitee API Management and Access Management installations in a single place.

Cockpit is based on a hierarchy of the following entity types:

User

No Gravitee documentation found

Permission

A permission is a list of actions allowed on a resource. The actions are

• Create
• Read
• Update
• Delete

Some permissions can be assigned to multiple types of resources.

For instance, the DOMAIN READ permission has a different meaning depending on whether it is assigned:

• to a domain: the user can read the specified domain
• to an organization: the user can read all the domains of the specified organization

Role

Roles are used to specify system access to authorized users. Each role provides a set of permissions representing operations that user can do on specific services.

A role is a functional group of permissions. There is no limit to the number of roles you can create. They all need to be administered, however.

In order to limit the scope of the roles, scopes are bound to what we call an assignable type:

• ORGANIZATION - role for the whole platform
• ENVIRONMENT - role for an environment
• DOMAIN - role for a security domain
• APPLICATION - role for an application

Some roles are special. The are tagged as System or Default.

System role

The System role is a read-only role (i.e. you cannot change its permissions) used by APIM. It is both an ADMIN role with an ENVIRONMENT and ORGANIZATION scope, and a PRIMARY_OWNER role with an API and APPLICATION scope. The System role gives the user all permissions.

Default role

The Default role is the role used by APIM when a role is not specified. For example, new registered users are assigned the default ENVIRONMENT and ORGANIZATION. The Default role gives the user limited permissions.

You can change the default on each scope.

Application

An application is an intermediate level between a consumer and an API. The consumer uses an application to subscribe to the API before they are able to consume it.

Applications act on behalf of the user to request tokens, user identity information and retrieve protected resources from remote services and APIs.

Application definitions apply at security domain level.

API

API is the root concept defined and used by APIM. Think of this as the starting point through which services are exposed to the gateway.

Publisher

In our platform, we define a publisher (also called API publisher) as the role that declares and manages APIs.

Consumer

In our platform, we define a consumer (also called API consumer) as the role that consumes APIs. PRO-TIP: A consumer can only consume an API after subscribing to it.

Group

You can assign roles to a group in the Roles tab. Each member of this group will automatically have these roles after each authentication.

You can create user groups to which you can add members of the same team/partner and set their role for the API scope and/or APPLICATION scope (see Roles and permissions for details). Once a group is created, you can associate it with an API and/or an application. Users with roles for this scope become members

Plan

A plan provides a service and access layer on your API for the consumer applications. A plan specifies access limits, subscription validation mode and other configurations to meet the specific applications needs.

In API Strategy, we see API as a Product concept which helps us to understand the needs of the customers and make the product compelling to them. Instead of providing only pure technical API resources, APIs plans will offer a business/service perspective to the consumers and in the meantime leverage your API product line.

You can imagine the following scenarios :

• Create an Open API plan with a readonly access and an limited request traffic letting potential customers discover and try your API
• Create a Premium plan with public resources and no limit access for your partners
• Create an internal plan with all access to your internal enterprise applications

All these notions can be hard to code in your API and should be manage in external tool such as an Plan.

To subscribe to a Plan, developers must create an application and choose the Plan they want to subscribe. That will create a subscription associate with the application. This subscription will be verify in order to accept or deny the incoming request.

Identity Providers

An identity provider brokers trust with external user providers, to authenticate and obtain information about your end users.

Out-of-the-box identity providers are:

• MongoDB
• In-memory
• LDAP / Active Directory
• OpenID Connect IdP (Azure AD, Google)

Policies

A policy modifies the behavior of the request or response handled by APIM Gateway. It can be chained by a request policy chain or a response policy chain using a logical order. Policies can be considered like a proxy controller, guaranteeing that a given business rule is fulfilled during request/response processing.

Examples of a policy are:

• Authorization using an API key (see the api-key policy)
• Applying header or query parameter transformations
• Applying rate limiting or quotas to avoid API flooding

Reporters

A reporter is used by an APIM Gateway instance to report many types of event:

• Request/response metrics - for example, response-time, content-length, api-key
• Monitoring metrics - for example, CPU, Heap usage
• Health-check metrics - for example, status, response code

Out of the box reporters are :

• Elasticsearch Reporter
• File Reporter

Repositories

A repository is a pluggable storage component for API configuration, policy configuration, analytics and so on. You can find more information in the Repositories section of the Installation Guide.

Resources

A resource can be added to an API for its whole lifecycle. APIM comes with three default resources:

• Cache
• OAuth2 - Gravitee Access Management
• OAuth2 - Generic Authorization Server

You can find more information in the Resources section of the API Publisher Guide.

Notifiers

A notifier is used to send notifications. Currently, the only notifier available is the email notifier, but others including slack and portal are planned soon.

Alerts

An alert is used to send triggers or events to the Alert Engine which can be processed to send a notification using the configured plugin notifier. Configuring the notifier is the responsibility of the trigger.

Plugin

Plugins are additional components that can be plugged into APIM Gateway or APIM API. They can customize the component's behavior to exactly fit your needs and technical constraints.

For more information about plugins, including how to deploy them and details of their directory structure, see the Plugins Developer Guide.

Types of Plugins

The table below lists the different types of plugins you can use with APIM, with the component(s) they can be plugged into and some examples. For more details of what each plugin type does, see the sections below.

Gravitee API Managemnent (aka APIM Console)

Entity-Relation Diagram

Flowchart diagram