Advanced Configuration
Standalone Gateway
The structure of the Gateway installation command when using environment variables should be the following:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ENV_VARIABLE_1="value1" -e ENV_VARIABLE_2="value2" -v /HOST/PATH/TO/FILE:/GATEWAY/PATH/TO/FILE --name akeyless-gw akeyless/base:latest-akeyless
Note
To update an existing Gateway, use the same Admin Access ID and Cluster Name for the new Gateway in order to retrieve the latest settings and data from the previously removed Docker instance.
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:
-
Email\Password
Note
Your Gateway Authentication Method should have permission to create and manage both Items along with Targets items only.
While working with Cloud Service Providers Authentication Methods you can provide a list of allowed users that will be able to log in and manage your Gateway configuration.
Email Authentication
To set your Gateway default authentication based on your email\password which you used to create your Akeyless account:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="email" -e ADMIN_PASSWORD="password" --name akeyless-gw akeyless/base:latest-akeyless
Warning
Using your default account credentials is not recommended for production environments and can not work with MFA.
API Key Authentication
To set your Gateway default authentication based on API Key provide the relevant Access ID
and Access Key
using those variables:
ADMIN_ACCESS_ID="your-access-id"
, ADMIN_ACCESS_KEY="matching-access-key"
.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxx" -e ADMIN_ACCESS_KEY="62Hu...xxx....qlg=" --name akeyless-gw akeyless/base:latest-akeyless
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.
Set the ADMIN_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 ALLOWED_ACCESS_PERMISSIONS
variable with any other Authentication Method like SAML or OIDC or an API Key.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless
Certificates Authentication
To set your Gateway default authentication based on Certificates provide the relevant Access ID
, Certificate
, and Certificate Key
using those variables:
ADMIN_ACCESS_ID="your-access-id"
, ADMIN_CERTIFICATE="Certificate base64 encoded"
and ADMIN_CERTIFICATE_KEY="Certificate Key base64"
.
With a list of users that will be able to manage your Gateway configuration using ALLOWED_ACCESS_PERMISSIONS
variable with any other Authentication Method like SAML or OIDC or an API Key.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ADMIN_CERTIFICATE="base64-cert" -e ADMIN_CERTIFICATE_KEY="base64-cert-key" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless
Alternatively, you can mount the certificate and key directly into the docker image:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -v $PWD/key.pem:/home/akeyless/.akeyless/akeyless-admin-cert.key -v $PWD/cert.crt:/home/akeyless/.akeyless/akeyless-admin-cert.crt -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless
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
.
e.g.
ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "sub_claims": {"email": ["[email protected]", "[email protected]"], "group": ["Devops"]}, "permissions": ["admin"]}]'
Run the following:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "sub_claims": {"email": ["[email protected]", "[email protected]"], "group": ["Devops"]}, "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-csp-access-id" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "access1", "access_id": "p-xxxxxxx", "sub_claims": {"username": ["username1", "username2"], "group": ["IT"]}, "permissions": ["admin"]},\n {"name": "access2", "access_id": "p-yyyyyy", "sub_claims": {"username": ["username1"], "group": ["rnd"]}, "permissions": ["targets", "defaults"]}, {"name": "access3", "access_id": "p-zzzzzzz", "sub_claims": {"email": ["[email protected]", "[email protected]"]}, "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless
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 ALLOWED_ACCESS_PERMISSIONS
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:
ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "sub_claims": {"email": ["[email protected]", "[email protected]"], "group": ["Devops"]}, "permissions": ["admin"]},\\n {"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:
Permission | Description |
---|---|
defaults | Management of the defaults settings of your Gateway Including Defualt Encryption Key & Defualt AccessID for login. |
targets | Management of all Targets items that were created using your Gateway |
classic_keys | Management of Classic Keys |
automatic_migration | Management of Dynamic Secrets settings |
dynamic_secret | Management of Dynamic Secrets |
rotated_secret | Management of Rotated Secrets |
log_forwarding | Management of Log Forwarding settings |
zero_knowledge_encryption | Management of Zero-Knowledge |
caching | Management of Gateway Cache settings |
event_forwarding | Management of Event Forwarding settings |
ldap_auth | Management of LDAP Auth Gateway configuration. |
k8s_auth | Management of Kubernetes Auth Gateway configuration |
kmip | Management of KMIP Servers |
general | Management of Gateway General settings including GatewayUrl ,TLS |
admin | Admin permission can manage all Gateway components, including Access 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.
Cluster Name & URL
Each Gateway instance is uniquely identified by combining the Admin Access ID Authentication Method and the Cluster Name.
It means that changing the Admin Access ID or the Cluster Name of your Gateway instance will create an entirely new Gateway instance, and it will not retrieve the settings and data from the previous Gateway instance.
That’s why we recommend setting up a meaningful Cluster Name for your Gateway instance from the very beginning. By default, your cluster name is defaultCluster.
To do that, you can set the CLUSTER_NAME="meaningful-cluster-name"
variable. In addition, to set in advance the *Cluster URL**, you can set the CLUSTER_URL
variable as part of the Gateway Installation command.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e CLUSTER_NAME="meaningful-cluster-name" -e INITIAL_DISPLAY_NAME="display-name" -e CLUSTER_URL="https://<GW_URL>" --name akeyless-gw akeyless/base:latest-akeyless
You can also provide a custom display name for the Gateway Instance using the INITIAL_DISPLAY_NAME
variable, but this is arbitrary. This name can be changed in the Akeyless Console after the Gateway is installed.
Encryption Key
While the Secret Encryption section discusses the secrets created when using the Gateway, this section discusses the encryption of the configuration file.
To choose an Encryption Key to encrypt your Gateway configuration, you can choose an existing key using the following variable CONFIG_PROTECTION_KEY_NAME
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxxxxxxx" -e ADMIN_ACCESS_KEY="62Hu...xxx....qlg=" -e CONFIG_PROTECTION_KEY_NAME="My-Encryption-Key" --name akeyless-gw akeyless/base:latest-akeyless
By default, the Gateway configuration is encrypted with your account's default encryption key.
Customer Fragment
If your Encryption Key works with Zero Knowledge, provide the full path to a local JSON containing your Customer Fragment:
Note: When adding multiple Customer Fragments to the Gateway, make sure they are in the same JSON file.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -v {full-path-to}/customer_fragments.json:/home/akeyless/.akeyless/customer_fragments.json -e CLUSTER_NAME="test-cluster" -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ADMIN_ACCESS_KEY="<YourAccessKey" -e CONFIG_PROTECTION_KEY_NAME="My-Encryption-Key" --name akeyless-gw akeyless/base:latest-akeyless
Alternatively, you can use the environment variable to pass the customer fragment value using the CUSTOMER_FRAGMENTS
variable:
export CUSTOMER_FRAGMENTS=$(cat customer_fragments.json)
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e CUSTOMER_FRAGMENTS="$CUSTOMER_FRAGMENTS" -e CLUSTER_NAME="test-cluster" -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ADMIN_ACCESS_KEY="<YourAccessKey" -e CONFIG_PROTECTION_KEY_NAME="My-Encryption-Key" --name akeyless-gw akeyless/base:latest-akeyless
Version Selection
To work with a specific Gateway version use the VERSION
variable to install a specific version of the Akeyless Gateway.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e VERSION="gw-app-version" --name akeyless-gw akeyless/base:latest-akeyless
TLS Configuration
We strongly recommend using Akeyless Gateway with TLS to ensure all traffic is encrypted at transit.
Please note that when you're enabling TLS, you must provide a TLS certificate and a TLS Private Key in PEM format.
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e ENABLE_TLS="true" -e ENABLE_TLS_CONFIGURE="true" -e ENABLE_TLS_CURL="true" -e ENABLE_TLS_HVP="true" -e MIN_TLS_VERSION="TLSv1.2" -v $PWD/cert.crt:/home/akeyless/.akeyless/akeyless-api-cert.crt -v $PWD/key.pem:/home/akeyless/.akeyless/akeyless-api-cert.key --name akeyless-gw akeyless/base:latest-akeyless
In the example above,
-
The
ENABLE_TLS
variable enables TLS for the Gateway Console. -
The
ENABLE_TLS_CONFIGURE
variable enables TLS for the Gateway Configuration Manager. -
The
ENABLE_TLS_HVP
variable enables TLS for the HVP service. -
The
ENABLE_TLS_CURL
variable enables TLS for the Akeyless API Services. -
The
MIN_TLS_VERSION
variable sets the minimum TLS version that will be supported supporting<TLSv1/TLSv1.1/TLSv1.2/TLSv1.3>
.
In addition to exclude specific cipher suites use this variable EXCLUDE_CIPHER_SUITES
with the relevant suites, you wish to exclude comma-separated.
With the following attributes, you can mount the TLS certificate and the TLS Private Key from the Present Working Directory to the Gateway target directory:
-
-v $PWD/cert.crt:/home/akeyless/.akeyless/akeyless-api-cert.crt
-
-v $PWD/key.pem:/home/akeyless/.akeyless/akeyless-api-cert.key
It is also possible to Set up TLS in the Gateway Configuration Manager after the Gateway is installed.
Cache Configuration
You can enable caching of secrets and periodic backup of cached secrets
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxxxxxxx" -e ADMIN_ACCESS_KEY="62Hu...xxx....qlg=" -e CACHE_ENABLE="true" -e PROACTIVE_CACHE_ENABLE="true" -e CACHE_TTL="60" -e PROACTIVE_CACHE_MINIMUM_FETCHING_TIME="5" -e PROACTIVE_CACHE_DUMP_INTERVAL="1" --name akeyless-gw akeyless/base:latest-akeyless
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e CACHE_ENABLE="true" -e PROACTIVE_CACHE_ENABLE="true" -e CACHE_TTL="number-of-minutes" -e PROACTIVE_CACHE_MINIMUM_FETCHING_TIME="number-of-minutes" -e PROACTIVE_CACHE_DUMP_INTERVAL="number-of-minutes" --name akeyless-gw akeyless/base
In the example above,
-
CACHE_TTL
variable allows setting the time (in minutes) during which a secret should be kept in the cache. -
PROACTIVE_CACHE_MINIMUM_FETCHING_TIME
variable instructs the system to update secrets in the cache if they are older than the specified value. -
PROACTIVE_CACHE_DUMP_INTERVAL
variable allows setting the time (in minutes) between the two consecutive backups.
It is also possible to configure caching in the Gateway Configuration Manager after the Gateway is installed.
Restrict Gateway Access
To restrict access to Gateway services, you can specify exactly which AccessIDs
will be authorized and will be served by the Gateway. For example, if you want to achieve complete segregation using Zero-Knowledge Encryption across different teams or applications, you can also set their AccessIDs
to ensure only they will be able to get service from the Gateway that holds their Fragment. To set the list of users the Gateway services will serve, set the RESTRICT_SERVICE_TO_ACCESS_IDS
variable with a comma-separated list of AccessIDs
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="aws-iam-access-id" -e RESTRICT_SERVICE_TO_ACCESS_IDS="comma separated list of access-ids" --name akeyless-gw akeyless/base:latest-akeyless
In the above example, in addition to your Gateway admin lists, you are limiting the audience of users that your Gateway will serve. Other AccessIDs
will not be able to get service from your Gateway. Alternatively to block specific AccessIDs
you can use the BLOCKLIST_ACCESS_IDS
variable instead.
Default Secret Encryption
While the Encryption Key section discusses the encryption of the configuration file, this section discusses the secrets created when using the Gateway.
To set a default existing key that will be used to encrypt any secret created through the gateway, add the parameter DEFAULT_ENCRYPTION_KEY
in the following way:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e DEFAULT_ENCRYPTION_KEY="existing encryption key name" --name akeyless-gw akeyless/base:latest-akeyless
Default Secret Location
To set a default location to which any secret created through the gateway will be saved in your Akeyless account, add the parameter DEFAULT_SECRET_LOCATION
in the following way:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e DEFAULT_SECRET_LOCATION="path to relevant folder" --name akeyless-gw akeyless/base:latest-akeyless
Setting a Default Login
When using OIDC or SAML authentication to connect to the Gateway's web UI on port 18888, a user would usually be asked to supply an access ID, before being transferred to a login screen. This can also be done from the gateway UI as described in Gateway SAML & OIDC.
When configuring your gateway, you may supply a default value for either OIDC, SAML, or both, using the following parameters:
-e DEFAULT_SAML_ACCESS_ID=<SAML Access ID>
-e DEFAULT_OIDC_ACCESS_ID=<OIDC Access ID>
-e AKEYLESS_OIDC_GW_AUTH=true
Optional, to authenticate directly against your Gateway.- In the following way:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e DEFAULT_SAML_ACCESS_ID="p-xxxxx" --name akeyless-gw akeyless/base:latest-akeyless
To work with CBA flow for users' login, first set your users' DNS records with the cert authentication subdomain auth-cert.akeyless.io
to point to your Gateway IP address.
Set your deployment with the following parameters:
-e DEFAULT_CERTIFICATE_ACCESS_ID=<Cert Auth Method Access ID>
-e ENABLE_SNI_PROXY="true"
In the following way:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="aws-iam-access-id" -e DEFAULT_CERTIFICATE_ACCESS_ID="access-id" -e ENABLE_SNI_PROXY="true" --name akeyless-gw akeyless/base:latest-akeyless
Fixed Artifact Repository
In some environments where an IP address must be whitelisted, to pull Akeyless official artifacts as part of your Gateway deployment, you can pass the ARTIFACTS_REPO="artifacts.site2.akeyless.io"
environment variable as part of the docker run command:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ARTIFACTS_REPO="artifacts.site2.akeyless.io" --name akeyless-gw akeyless/base:latest-akeyless
Rate Limit
To set a local rate limit on your Gateway instance you can add the GW_RATE_LIMIT
environment variable where the value will set the maximum calls per minute. When a client reaches that threshold, this will be logged and any additional requests during that minute will be discarded on the Gateway:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e GW_RATE_LIMIT=4000 --name akeyless-gw akeyless/base:latest-akeyless
RHEL Image
To work with a fully compatible image based on the RedHat Universal Image base 8 set the repository source at the end of the docker run
command with akeyless/base-rhel
for example:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 --name akeyless-gateway akeyless/base-rhel:latest-akeyless
gRPC
To enable gRPC on your Gateway set the following environment variable ENABLE_GRPC=true
, the service will be exposed on port 8085
:
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 8085:8085 -p 5696:5696 -e ENABLE_GRPC=true --name akeyless-gw akeyless/base:latest-akeyless
Updated 2 months ago