API Keys | On-Premise | 2GIS Documentation

On-Premise API Keys service

This service allows issuing and managing API keys via the API Keys 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 On-Premise services (several, all, or none).
  • Restrict access based on:
    • IP range (CIDR).
    • 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 Overview document. Additional information can be found in the Deployment considerations section of this document.

Do the following:

  1. Configure the PostgreSQL data storage:

    1. Create a database for use with API Keys service.

    2. Create users (also known as roles) for this database:

      1. A user with read-only privileges.

      2. A user with read-write privileges. The user must be the owner of this database or a superuser.

    3. Alter the default privileges (perform this operation on behalf of either a superuser or a database owner):

      ALTER DEFAULT PRIVILEGES FOR ROLE <read-write user name> IN SCHEMA public GRANT SELECT ON TABLES TO <read-only user name>;
      ALTER DEFAULT PRIVILEGES FOR ROLE <read-write user name> IN SCHEMA public GRANT SELECT ON SEQUENCES TO <read-only user name>;
      
  2. Create the values-keys.yaml configuration file:

    values-keys.yaml

    dgctlDockerRegistry: <Docker Registry hostname and port>/2gis-on-premise
    
    db:
        ro:
            host: <hostname or IP address of PostgreSQL>
            port: <PostgreSQL port>
            name: <database name>
            username: <read-only user name>
            password: <read-only user password>
        rw:
            host: <hostname or IP address of PostgreSQL>
            port: <PostgreSQL port>
            name: <database name>
            username: <read-write user name>
            password: <read-write user password>
    
    ldap:
        host: <hostname or IP address of LDAP server>
        port: <LDAP port>
    
        useStartTLS: <true or false>
        useLDAPS: <true or false>
        skipServerCertificateVerify: <true or false>
        serverName: <server name>
        clientCertificatePath: <path to client certificate>
        clientKeyPath: <path to client key>
        rootCertificateAuthoritiesPath: <path to the root certificate authorities file>
    
        bind:
            dn: <user distinguished name>
            password: <password>
    
        search:
            baseDN: <base distinguished name>
            filter: <filter expression>
    
    tasker:
        resources:
            requests:
                cpu: 10m
                memory: 32Mi
            limits:
                cpu: 100m
                memory: 64Mi
    
        delay: 30s
    
    admin:
        apiUrl: <API Keys service API URL>
        appHost: <API Keys service web UI URL>
    ##
    ## Manually specify the administrator user(s) credentials if no LDAP servers are configured.
    ##
    # api:
    #    adminUsers: username1:password1,username2:password2,...
    

    Where:

    1. dgctlDockerRegistry: your Docker Registry endpoint where On-Premise services' images reside.

    2. db: access settings for the PostgreSQL server.

      The On-Premise API Keys service serves the data in two modes: read-only (ro) and read-write (rw). The service uses a single database for each mode, however, users are configured with different set of permissions (see the step 1 for details). Set the settings in these sections as follows:

      1. Settings that are common for both modes:

        1. host: hostname or IP address of the PostgreSQL server.
        2. port: listening port of the PostgreSQL server. For example, 5432.
        3. name: database name.
      2. Credentials of the read-only user in the ro section.

      3. Credentials of the read-write user in the rw section.

      When installing, the Helm chart uses Kubernetes Secrets to store the password settings in the ro and rw sections.

    3. ldap: access settings for the LDAP server.

      1. host: hostname or IP address of the server.

      2. port: listening port of the LDAP server. For example, 3268.

      3. A group of setting to configure secure access to the LDAP server:

        1. useStartTLS: use StartTLS. Default: false.
        2. useLDAPS: use Secure LDAP. Default: false.
        3. skipServerCertificateVerify: do not verify the server certificate. Default: false.
        4. serverName: string with the server name. Used when verifying the server certificate.
        5. clientCertificatePath: path to client certificate.
        6. clientKeyPath: path to client key.
        7. rootCertificateAuthoritiesPath: path to the root certificate authorities file.
      4. bind: credentials for accessing the LDAP server.

        1. dn: distinguished user name.
        2. password: user password.
      5. search: LDAP search settings.

        1. baseDN: base relative distinguished name. For example, dc=2gis.
        2. filter: LDAP filter used to identify entries in search requests. For example, (&(objectClass=user)(sAMAccountName=%s)).
    4. tasker: settings of the Tasker service, which do administrative actions on API keys.

      1. resources: computational resources settings for service. See the minimal requirements table for the actual information about recommended values.
      2. delay: time interval (in seconds). This setting defines the interval of checking tasks that are related to delayed action items (for example, blocking an API key).
    5. admin: settings of the API Keys Admin web service (Web UI).

      1. apiUrl: URL of the API Keys backend. For example, http://keys-api.svc. This URL should be accessible from all the pods within your Kubernetes cluster.
      2. appHost: URL of the API Keys frontend. For example, https://app.host. This URL should be accessible from the outside of your Kubernetes cluster, so that users in the private network can browse the URL.
    6. api.adminUsers: a list of credentials of administrator users in the username1:password1,username2:password2,... format. Uncomment and use this setting if no LDAP servers are configured.

      When installing, the Helm chart uses Kubernetes Secrets to store the setting.

      Note:

      It is recommended to set up and use LDAP server for user authentication. This setting should be considered as a backup authentication mechanizm.

  3. Deploy the API Keys On-Premise service with Helm using created values-keys.yaml configuration file.

    helm upgrade --install --version=1.0.3 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys
    

    Helm will deploy the service.

  4. Add the administrator users to the deployed service via the keysctl utility. These users will be assigned the API Keys service administrator role.

    Important note:

    Do this step regardless the configured authentication mechanism: either via LDAP or via plaintext credentials list in the api.adminUsers settings.

    When using LDAP, it is sufficient to add a single user. When using credentials list, add all the users form the list.

    To add a user, execute the following command from the inside of any keys-api pod:

    keysctl users add "admin username" "Display Name"
    

Each On-Premise service that integrates with the API Keys service is forced to share information about the end user's API key usage with the API Keys backend by design. To communicate with the backend, the service needs the service API key to be configured during the deployment.

To get a list of the service keys to be used with a certain On-Premise API Keys service deployment, execute the following command from the inside of any keys-api pod:

keysctl services

See the Overview document for details.

To update the service after changing the settings or after updating the Docker image, execute the following command:

helm upgrade --version=1.0.3 --atomic --wait-for-jobs --values ./values-keys.yaml keys 2gis-on-premise/keys

To test the operability of the On-Premise API Keys service, do the following:

  1. Open API Keys Admin in a browser (use the value of the appHost setting from the values-keys.yaml file):

    https://app.host/
    
  2. Log in using the administrator user credentials (the one that was granted administrator role via the keysctl utility). You should see the API Keys service web interface for managing API keys.