Akeyless Gateway can be deployed using Docker Compose, in which, the configuration process takes place before the actual installation.

Prerequisites

• An Authentication Method. Make sure it has the right access permission to create and manage Secrets, Keys & Targets.
• A Linux or a Windows machine with Docker engine installed with a minimum 1 vCPU available with 2GB RAM.
• Docker compose installed
• Network connection to Akeyless SaaS Core Services from your machine.

🚧

Warning

Make sure that this server is not globally opened to the public network. Akeyless Gateway requires only connections to Akeyless SaaS Core Services.

• Network port 8000 on the cluster must be open only for internal network access, allowing access to the following services using the corresponding endpoints:

Configuration

Clone the repository to your environment:

gh repo clone akeylesslabs/repo-name

Environment Variables

To configure the Gateway, create a file named gateway.env in the same directory the docker-compose.yaml file is.

👍

Note

The following env file uses an API Key for authentication, however, each auth method from the Authentication section can be used.

This gateway.env file will hold the following settings for the Gateway:

GATEWAY_ACCESS_ID="<Access ID>"             
GATEWAY_ACCESS_KEY="<Access Key>"
GATEWAY_ACCESS_TYPE="access_key" 

Where:

• GATEWAY_ACCESS_ID: The admin of the Gateway.
• GATEWAY_ACCESS_KEY: The Access Key.
• GATEWAY_ACCESS_TYPE: The type of the Auth Method being used.

The full list of permissions can be found here.

Profiles

Using profiles, you can declare which service will start when running the configuration file. The available services are:

• Gateway - Will start the Gateway service.
• SRA - Will start the SRA Service (Both SSH and Web).
• Metrics - Will start Prometheus and Grafana services.

Example:

sudo docker compose --profile gateway up -d

The above command will deploy a Gateway.

Authentication

To set your Gateway with a default Authentication Methods to control the level of access your Gateway instance will have inside your Akeyless account.

The following Authentication Methods are supported for Docker deployments:

• API Key

• AWS IAM

• GCP

• Azure Active Directory

• Certificates

👍

Note

Your Gateway Authentication Method should have permission to create and manage both Items along with Targets items only.

API Key Authentication

To set your Gateway default authentication based on API Key, edit the gateway.env file with the relevant Access ID and Access Key using the environment variables:

GATEWAY_ACCESS_ID=<Access ID>
GATEWAY_ACCESS_KEY=<Access Key>
GATEWAY_ACCESS_TYPE=access_key

CSP IAM Authentication

While running your Gateway instance inside your cloud environment, you can use AWS IAM, GCP GCE, or Azure Active Directory, using machine-to-machine authentication between Akeyless and your Cloud Service Provider with a list of allowed users that will be able to manage your Gateway configuration by adding the GATEWAY_AUTHORIZED_ACCESS_ID variable to the .env configuration file.

Set the GATEWAY_ACCESS_ID variable with your IAM Authentication Methods Access ID, where you need to set a list of users that will be able to manage your Gateway configuration using GATEWAY_AUTHORIZED_ACCESS_ID variable with any other Authentication Method like SAML or OIDC or an API Key.

GATEWAY_ACCESS_ID=<Access ID>
GATEWAY_ACCESS_TYPE=aws_iam 
ALLOWED_ACCESS_PERMISSIONS='[{"access_id":"<Access ID>","name":"<Allowed Method Name>", "permissions": ["admin"]}]'

GATEWAY_ACCESS_ID=<Access ID>
GATEWAY_ACCESS_TYPE=gcp_gce
ALLOWED_ACCESS_PERMISSIONS='[{"access_id":"<Access ID>","name":"<Allowed Method Name>", "permissions": ["admin"]}]'

GATEWAY_ACCESS_ID=<Access ID>
GATEWAY_ACCESS_TYPE=azure_ad 
ALLOWED_ACCESS_PERMISSIONS='[{"access_id":"<Access ID>","name":"<Allowed Method Name>", "permissions": ["admin"]}]'

Certificates Authentication

To set your Gateway default authentication based on Certificates provide the relevant Access ID, Certificate, and Certificate Key, where you need to set a list of users that will be able to manage your Gateway configuration using GATEWAY_AUTHORIZED_ACCESS_IDvariable with any other Authentication Method like SAML or OIDC or an API Key.

GATEWAY_ACCESS_ID=<AccessID>
GATEWAY_CERTIFICATE=<certificate.pem base 64>
GATEWAY_CERTIFICATE_KEY=<private key base 64>
ALLOWED_ACCESS_PERMISSIONS='[{"access_id":"<Access ID>","name":"<Allowed Method Name>", "permissions": ["admin"]}]'

Gateway Admins

To support local management of your Gateway configuration, you can set a list of Access ID that will be able to log in and manage your Gateway. This setting can also work with Sub-Claims (when a shared authentication method is used), where for each entry you need to define a unique name which should describe the Access Permission object, with an access-id, sub_claims when applicable, and a list of permissions.

Add the GATEWAY_AUTHORIZED_ACCESS_ID environment variable to the gateway.env file, specifying a JSON list of allowed Access IDs:

ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "sub_claims": {"email": ["[email protected]", "[email protected]"], "group": ["Devops"]}, "permissions": ["admin"]}]'

Add the environment variable to the docker-compose.yaml file:

ALLOWED_ACCESS_PERMISSIONS: $ALLOWED_ACCESS_PERMISSIONS

In this case, the above will create an Access Permission object named Administrators, associated with an Auth method p-yyyyyy which for example is your SAML or OIDC Access ID, where a user that at least matches one Sub-Claims attribute, will be authorized to access the Gateway with Admin permissions:

In our example, [email protected] and test02@testhost will be authorized, and any member of group=Devops will also be authorized.

In this case, the Access ID belongs to the authentication method created for the certain Identity Provider.
If you don't specify the sub-claims, every user authenticated by this IdP will be able to log in to the Gateway with admin privileges.

To work with API Key as an GATEWAY_AUTHORIZED_ACCESS_ID simply provide your API Key Access ID with a name for the Access Permission object, with a set of permissions.

Access Permissions

To delegate the exact permissions users will have on your Gateway components you can explicitly grant permissions, for example, to grant permissions to a user to manage only your Gateway Log Forwarding settings:

[{"name": "Administrators", "access_id": "p-yyyyyy", "sub_claims": {"email": ["[email protected]", "[email protected]"], "group": ["Devops"]}, "permissions": ["admin"]}, {"name": "LogForwarding", "access_id": "p-xxxxxx", "sub_claims": {"email": ["[email protected]"]}, "permissions": ["log_forwarding"]}]

In the above example, your Gateway Admins are [email protected],[email protected] or any user which is part of your Devops group in your IdP, where [email protected] have permission to manage only your Gateway Log Forwarding settings.

Full list of available permissions:

👍

Note

Only Gateway Admins can delegate permissions to additional users. Any pre-provisioned settings will not be editable from the Akeyless Console.

You may also edit this parameter on your console, by going to the Gateways tab and selecting the desired Gateway. On the right of the screen, you will see the Gateway details, including Access Permissions.

Installation

From the directory where the docker-compose.yaml and the .env file are located, run:

docker compose up -d

Check if the containers are up and running:

docker ps

CONTAINER ID   IMAGE                                                             COMMAND                  CREATED          STATUS                    PORTS                                                                                        NAMES
c913bebbeed5   docker.registry-2.akeyless.io/base:latest                                            "/bin/bash /akeyless…"   20 minutes ago   Up 20 minutes (healthy)   0.0.0.0:8000->8000/tcp, :::8000->8000/tcp, 0.0.0.0:8080->8080/tcp, :::8080->8080/tcp         akeyless-gateway