API Keys service | Urbi On-Prem | 2GIS Documentation

On-Premise API Keys service

This service allows issuing and managing API keys via an admin web application. End-users of On-Premise services will use these keys to access the deployed On-Premise services.

Administrator issues one or more API keys to a partner. It is a named entity used to store a group of API keys. For example, you can create separate partners for Android and iOS developer teams, independently managing keys for both teams.

When issuing an API key, the administrator can set the usage policies for the key. They can:

  • Grant access to a certain set of deployed services (several, all, or none).
  • Restrict access based on:
    • IP range (in CIDR notation).
    • Value of the HTTP headers:
      • Referer.
      • Origin.
      • User-Agent.

On-Premise services that require an end user to supply an API key to operate:

  • Maintain a list of the issued API keys for an end user, and update the list and the corresponding usage policies by communicating with the API Keys service.
  • Determine whether to allow or deny an end user's request by evaluating all the information received from the API Keys service.
  • Send the request's metadata to the API Keys service.
On-Premise API Keys service architecture

The On-Premise API Keys service comprises the API Keys Admin web service for managing and issuing API keys and API Keys RESTful API backend service for interacting with other services.

When preparing to execute an end-user's request, each On-Premise service sends the metadata of the request to the API Keys service (including the API key). The API Keys service logs events related to API keys and stores them in the Apache Kafka data storage. Additionally, API Keys usage counters are stored in Redis. The Tasker service fetches the data about events from API Keys backend, and then takes appropriate administrative actions on keys based on the events: for example. it may block or unblock the certain API key. This allows the API Keys service to control the usage of API keys and to enforce quota-based access rules: for example, if an end-user with a certain API key makes more than 100 requests per minute to the On-Premise Maps services, the API Keys server will block access to the service for that user's API key until the next hour.

Note:

Support for Apache Kafka data storage is under active development and will be added in a future release.

Current service version operates without Apache Kafka. No metrics that allow to enforce quota are available.

For detailed overview of the On-Premise solution architecture, see the Overview document.

Shared infrastructure:

  • LDAP server for authenticating Admin Panel users. For example, Microsoft Active Directory can act as the LDAP server.
  • Apache Kafka data storage for storing events, related to API keys.
  • Redis data storage for storing API keys usage counters.
  • PostgreSQL data storage for storing API keys and related data. It is required to deploy PostgreSQL v11.

Detailed requirements for each service are listed in the System requirements document.

What's next?