Akeyless Security Guide: Auth Methods, Gateway Hardening, Secrets and Audit

An Akeyless account holds the credentials that machines, pipelines and AI agents use everywhere else, so a long-lived access key, an over-broad access role or an unmonitored Gateway turns the secrets platform into the most valuable target in the estate. This guide explains how to run Akeyless securely, using Akeyless's own documentation as the source for every product detail. It covers the SaaS and customer Gateway architecture, Distributed Fragments Cryptography as Akeyless describes it, authentication methods for workloads and agents, access roles and sub-claims, static, dynamic and rotated secrets, just-in-time access, audit logs, Gateway hardening and what to do when an access key leaks. It is written for platform engineers, security engineers and identity teams who already run Akeyless or are taking over an account. For the general discipline see the Secrets Management Guide.

Key takeaways

• Every action resolves to an auth method plus an access role. Akeyless states that users have no permissions unless explicitly granted, and an auth method can do nothing until a role is associated with it, so role design is where access is really decided.
• Use platform identity, not access keys, for workloads. Cloud IAM, Kubernetes, certificate and OIDC methods let a workload prove who it is; Akeyless's own page on the API Key method says it is not recommended for production use.
• Sub-claims are what make a shared auth method safe. Without them, every pod in a cluster or every principal in an AWS account that can authenticate gets the same role; with them, a role applies only to tokens carrying matching namespace, service account or group values.
• The Gateway is part of your attack surface. It runs in your network, holds dynamic and rotated secret configuration and can cache secrets, so it needs the same hardening, least privilege and monitoring as any privileged service.
• Prefer dynamic and rotated secrets over static ones. Short-lived credentials generated on access, and target passwords the platform rotates on a schedule, shrink the value of anything an attacker copies.

How Akeyless is put together

Akeyless is delivered as a SaaS platform with a customer-hosted component, the Akeyless Gateway. The documentation describes the Gateway as a stateless service that sits between internal workloads and Akeyless SaaS: it receives application requests, authenticates and authorises them, brokers access to Akeyless services and enforces local controls such as TLS, caching and forwarding rules. It runs in a self-managed runtime, on a managed Kubernetes platform or on a serverless platform, and talks to SaaS over outbound connectivity, so internal resources are not exposed to the public network.

Several capabilities are consumed through the Gateway, including dynamic secrets, rotated secrets, KMIP and classic keys. Akeyless states that the configuration for producing dynamic secrets is part of your private network and is stored on the Gateway. In practice that makes the Gateway the component that reaches your databases, cloud accounts and servers with administrative credentials.

Distributed Fragments Cryptography, as Akeyless describes it

Akeyless calls its key protection scheme Distributed Fragments Cryptography (DFC). According to its DFC overview, key material is divided into multiple independent fragments generated separately in isolated environments; the fragments are said never to combine into a full key at any stage, the original key is described as never reconstructed, transmitted or stored, and each operation uses a one-time derived key that is then discarded, with the page referring to NIST-approved derivation operations. Akeyless presents DFC as the basis of what it calls a zero-knowledge architecture. NHI Mgmt Group has not assessed these claims; treat them as the vendor's description and validate them against your own assurance requirements.

The design decision that matters most for operators is the optional customer fragment. A customer can hold one fragment, and Akeyless states that operations cannot complete, and Akeyless cannot reconstruct the key, without it. The Gateway zero-knowledge page is explicit that encryption keys created with a customer fragment cannot be reconstructed without it. That is a real availability risk: the fragment is generated with akeyless gen-customer-fragment, delivered to the Gateway as a mounted customer_fragments.json file, a Kubernetes Secret referenced by globalConfig.customerFragmentsExistingSecret, or a serverless deployment parameter, and it must have a defined, tested backup process before any key depends on it.

Authenticating machines and AI agents

Akeyless lists machine authentication methods for cloud IAM (AWS IAM, Azure AD, GCP IAM, OCI IAM), Universal Identity for on-premises systems, Kubernetes, certificates, OAuth 2.0/JWT, API keys and Kerberos, and human methods including LDAP, SAML, OIDC and email. Each method has an Access ID. The choice follows where the workload runs: let it present an identity its platform already issues, which is the pattern the Secrets Zero Problem Guide describes in general terms.

Every method also carries account-wide and per-method controls documented on the authentication methods page: minimum, default and maximum token TTL under Authentication Settings, an optional Expiration Date (empty means no expiry), Allowed Client IPs as CIDR blocks (empty means unrestricted), Allowed Trusted Gateway IPs for Gateways allowed to forward the original client IP, Audit Log Sub-Claims to enrich log entries, and Require Sub Claim on role association, which forces any associated role to specify sub-claims.

AI agents

An AI agent is a workload and should authenticate the same way: from the identity of the runtime it executes in (a Kubernetes service account, a cloud role or a signed JWT from the agent platform), with a dedicated auth method or sub-claim per agent so its actions appear separately in the audit log. Akeyless's RBAC documentation lists an ara-rule type for what it calls Agentic Runtime Authority, with an allow_access capability, and its dynamic secret producers include OpenAI, which lets an agent receive a model provider key that is generated on access rather than a shared static key. See the Credential Vaulting for AI Agents Guide and the AI Agent Credential Lifecycle and Rotation Guide for the wider pattern.

Access roles, rules and sub-claims

An access role is a set of rules, each applying capabilities to a path under a rule type. The capabilities for items, roles, auth methods and targets are list, read, create, update, delete and deny. Akeyless documents that deny overrides every other permission (except for Secure Remote Access), that list is included in all other permissions, and that non-admin users cannot grant capabilities beyond their own effective permissions, with any deny rules they are subject to copied onto roles they create.

• Rule types: item-rule for secrets and keys, target-rule, auth-method-rule, role-rule, sra-rule (allow_access, request_access, justify_access_only), ara-rule, plus administrative rules (Audit Log, Analytics, Gateways, Usage Reports and others) scoped to Own, Scoped or All.
• Path wildcards: a trailing * matches everything under a folder, a prefix such as /foo/devops-* matches names starting with that string, and + matches one path segment. Prefer explicit folders per application and environment over account-wide wildcards.
• Explicit deny for crown jewels: the RBAC page's own example allows /path/to/folder/* and denies /path/to/folder/topSecret. Use the same pattern for break-glass items, root credentials and customer-fragment-protected keys.
• Sub-claims: set with akeyless assoc-role-am --sub-claims and supported for JWT/OIDC, Kubernetes, SAML and LDAP. Different keys combine with AND, comma-separated values within a key with OR, keys and values are case-sensitive, and ? and * wildcards work. Explicit AND/OR syntax needs Gateway 4.19 or later. Run akeyless describe-sub-claims to see what an auth method actually exposes before writing rules.
• Path templating: sub-claim values can fill rule paths, for example /{{Groups}}/{{Username}}/*, giving each identity its own space without a role per identity.
• Test before trusting: the View As (Impersonate As) feature lets an administrator select an auth method and sub-claims and see the resulting access. Use it in every role review.

For administrators, the Gateway best practices page recommends assigning admin access by group, using separate groups for operations, security and read-only review, and restricting administrators to a controlled list of human Access IDs (SAML or OIDC) with defined sub-claims.

Static, dynamic and rotated secrets

Both dynamic and rotated secrets require the matching permission on the Gateway (Dynamic Secret or Rotated Secret). Rotated secrets also have a separate Rotate Secret Value permission that lets a user trigger rotation without edit rights, provided they also hold read on the item. For dynamic secrets, Akeyless documents that you can revoke all temporary users for a specific target immediately, which is the action to take first when a target account or producer may be compromised. Password policies (length and complexity) can be set for supported producers and rotators. The concepts are covered vendor-neutrally in the Dynamic Secrets and Ephemeral Credentials Guide.

Just-in-time access and break-glass

Akeyless's Request Access feature provides time-bound elevation. An account admin enables it under Settings, Items Settings, Request access. Users can then request read, update or delete on a static secret or target, from the CLI (request-access) or the Console, giving a justification in the description parameter. The requested TTL runs from 1 to 1,440 minutes, defaulting to 60. On approval the platform creates a temporary access role in a dedicated folder named for the requester and request ID, and deletes it when the TTL expires.

• Approver scope: the approver's role needs the Approve Access Request permission set to scoped or all (default none), plus a rule covering the requested path; approvers can only grant capabilities they already hold.
• Visibility: each request raises an Event Center event, which can be forwarded to ServiceNow and other endpoints, so approvals become part of the ticket trail.
• Break-glass: Akeyless recommends a dedicated auth method for break-glass, user and password with MFA, dual control where one person holds the password and another the MFA factor, restriction to a predefined IP range, and alerts on every break-glass attempt by email, Slack or SIEM. Test the procedure on a schedule; the page does not cover testing, so build it into your own runbook.

Hardening the Gateway

The Gateway best practices page is the most detailed hardening source Akeyless publishes. The points that most reduce risk are below.

• Isolation: run the Gateway in a trusted, dedicated environment, restrict and audit access to the host, orchestrator and deployment pipelines, and run as non-root (set runAsNonRoot, runAsUser, runAsGroup and fsGroup in Kubernetes). Enforce Kubernetes Pod Security Standards and network policies.
• Network: allow outbound HTTPS on 443 only to the required US or EU SaaS endpoints; open inbound ports only as the deployment model needs (port 8000 is common for internal clients); terminate TLS at least at the ingress and end to end in strict environments; plan egress to private targets for dynamic and rotated secrets.
• Gateway identity: prefer cloud IAM or workload identity for the Gateway itself; bind its auth method to a dedicated role with only the permissions it needs. The documented minimums are read and list on cached items for caching, read, update and list on items and targets for dynamic or rotated secrets, and read on the target for Universal Secrets Connector. Gateway identity does not override end-user RBAC.
• Cluster identity: a Gateway cluster is the combination of the auth method Access ID and clusterName; changing either creates a new logical cluster, so name it deliberately at the start.
• Caching: enable caching only to the level your continuity needs justify, review cache persistence, encryption and retention first, and monitor Redis separately if IGNORE_REDIS_HEALTH is set, because /health then keeps returning 200 when Redis is down.
• Versions and availability: pin explicit image versions matching GA releases, test upgrades in lower environments, run at least two pods (three to four with proactive cache), and use anti-affinity, topology spread and PodDisruptionBudgets.
• Key protection: use a customer fragment where zero-knowledge handling is required and HSM integration where hardware-backed protection is required, with both backed up before go-live.

Audit logs and detection

Akeyless audit logs record nearly every change or action, with fields that include Timestamp, seq_num, account_id, access_id, component, action, item_type, status (an HTTP code), remote_addr, duration, request_parameters, client_sub_claims, access_type and product. Configure Audit Log Sub-Claims on each auth method so entries name the pod, repository or user rather than only an Access ID.

Gateway log forwarding supports Amazon S3, Azure Log Analytics, Datadog, Elasticsearch, Google Chronicle, Logstash, Logz.io, Splunk, stdout, Sumo Logic and Syslog (text or CEF), in text or JSON. Two documented limits matter for completeness: forwarding can only fetch logs from the previous 24 hours, and for S3 logs not yet uploaded are lost if a pod scales down or restarts. The forwarding auth method needs a role that can view all audit logs; use one dedicated forwarder with scope all, or several with mutually exclusive scopes. Also alert on akeyless.gw.system.saas.connection_status and akeyless.gw.system.healthcheck.status, and use Event Center for failures, expirations and drift.

Metrics that show the programme is working:

• Share of machine auth methods that are platform identity rather than API key (target: API keys only for documented exceptions).
• Number of API key auth methods with no Expiration Date or no Allowed Client IPs (target: zero).
• Share of role associations with sub-claims on shared auth methods (target: all of them).
• Share of database and cloud credentials served as dynamic or rotated secrets rather than static.
• Median and longest age of static secrets.
• Audit log forwarding completeness, checked by seq_num continuity in the SIEM.

Responding to a leaked access key

An API key Access ID and Access Key pair is a bearer credential: whoever holds both can authenticate as that method. Treat a leak as an incident, in this order. The Cloud Access Key Leak Playbook covers the general response pattern.

1. Contain: reset the Access Key (akeyless reset-access-key --name <name> or Reset Access Key in the Console). If you cannot yet identify every legitimate consumer, set an Expiration Date or narrow Allowed Client IPs as an interim step, but do not delay the reset for long.
2. Scope: list every role associated with the method and every path those roles can read. That list is the set of secrets you must assume exposed.
3. Investigate: filter audit logs by the method's Access ID for the exposure window; look at remote_addr, actions and items read.
4. Rotate downstream: rotate every static secret the key could read, trigger rotation on reachable rotated secrets, and revoke temporary users on any dynamic secret target the key could use.
5. Remove the cause: replace the API key with a platform identity method, or if that is impossible, add expiry, IP restriction and automated reset.
6. Verify: confirm no further authentications with the old key and that consumers recovered.

The Toyota T-Connect key exposure shows what an unmonitored long-lived key in public code costs: the key sat on GitHub for nearly five years. The reset step only helps if someone notices the leak.

Rolling out a secure baseline

1. Inventory: export auth methods, roles and associations; flag API key methods, methods without expiry or IP limits, roles with account-wide wildcards and associations without sub-claims.
2. Set account defaults: lower the default and maximum token TTL in Authentication Settings, and turn on Require Sub Claim on role association for shared methods.
3. Pilot platform identity: move one application per environment from an API key to cloud IAM or Kubernetes auth, with sub-claims, and run both in parallel until audit logs show only the new method.
4. Harden and monitor the Gateway: apply the baseline above, enable log forwarding to the SIEM and build the detections in the table before migrating sensitive workloads.
5. Convert secrets: move databases and cloud access to dynamic secrets and service accounts to rotated secrets, one target at a time.
6. Roll back safely: keep the old credential valid but monitored until consumers confirm; to roll back, re-associate the previous role or restore the static value, then retry.

Small and large organisations: a small team may run one Gateway cluster and a handful of roles, and gains most from removing API keys and forwarding logs. A large organisation should give each business unit its own folder tree, sub-admins and Gateway cluster, and invest in sub-claim path templating so roles do not multiply.

Framework mapping

Relevant ATT&CK techniques for detection planning include T1552.001 Credentials In Files (access keys left in code or config), T1528 Steal Application Access Token and T1078.004 Cloud Accounts.

Common failure patterns

• API keys in production. The quick-start method becomes permanent, with no expiry and no IP limits, and ends up in CI variables and configuration files.
• Shared auth methods without sub-claims. One Kubernetes or AWS IAM method is associated with a broad role, so any pod or principal that can authenticate reads everything.
• An over-privileged Gateway identity. The Gateway role is given account-wide rights for convenience, so compromising the Gateway host compromises the account.
• Losing the customer fragment. Keys are bound to a customer fragment with no tested backup, and a rebuilt cluster cannot decrypt.
• Vault credentials kept beside vault backups. In the LastPass breach, cloud access keys and backup decryption keys held in one engineer's vault let an attacker copy customer vault backups. Keep platform admin and break-glass credentials out of everyday reach and alert on their use.
• Silent log loss. Forwarding is set up once and never checked, so gaps from pod restarts or the 24-hour fetch window go unnoticed.

Practitioner checklist

• List every API key auth method; replace each with cloud IAM, Kubernetes, certificate or OIDC auth, or document the exception with expiry and Allowed Client IPs.
• Enable Require Sub Claim on role association for every shared machine auth method and confirm claims with describe-sub-claims.
• Review roles for account-wide wildcards; add explicit deny rules for break-glass, root and fragment-protected items; test with View As.
• Set account minimum, default and maximum token TTLs and per-method Expiration Dates.
• Move databases and cloud access to dynamic secrets and admin accounts to rotated secrets with auto-rotate.
• Bind the Gateway to a dedicated least-privilege role, run it non-root in an isolated environment and pin its version.
• Back up any customer fragment and test restore before creating keys with it.
• Forward audit and Gateway logs to the SIEM, check seq_num continuity, and alert on access key use from new sources, role changes and break-glass logins.
• Enable Request Access with scoped approvers and TTLs no longer than the task needs.
• Write and rehearse the leaked access key runbook.

Standards and references

• Akeyless: Gateway Best Practices
• Akeyless: Authentication Methods
• Akeyless: Role-Based Access Control
• Akeyless: Distributed Fragments Cryptography (DFC)
• Akeyless: Audit Logs
• Akeyless: Request Access
• OWASP: Non-Human Identities Top 10
• NIST: SP 800-53 Rev. 5 Security and Privacy Controls

Related NHI Mgmt Group resources: Secrets Management Guide · Secrets Zero Problem Guide · Dynamic Secrets and Ephemeral Credentials Guide