FreeIPA
Draft version. Content is hallucinated. Do not use!
security

Password Vault

Securely store and retrieve passwords, keys, and other secrets with encryption. Vaults provide encrypted storage with three security types: standard (transport encryption), symmetric (password-encrypted), and asymmetric (public key encrypted). Features include user, service, and shared vault ownership models, secret archival and retrieval, vault membership for access control, escrow for recovery, and integration with KRA (Key Recovery Authority) for secure secrets management.

12 commands
security
vault secrets encryption

Overview

FreeIPA vaults provide secure, encrypted storage for passwords, keys, certificates, and other sensitive secrets. Integrated with Dogtag’s Key Recovery Authority (KRA), vaults offer encrypted secret archival and retrieval with multiple encryption models to balance security and operational requirements. Each vault stores a single secret which can be archived and retrieved by authorized users, services, or groups based on vault membership and ownership.

Vaults address common secrets management challenges: eliminating unencrypted password storage in configuration files, enabling secure password sharing between team members, providing audit trails for secret access, and establishing escrow mechanisms for secret recovery. Secrets stored in vaults remain encrypted both in transit and at rest, with encryption keys managed by the KRA to prevent unauthorized access even by FreeIPA administrators.

The vault system operates on a container model where vaults are organized under vault containers associated with users, services, or shared access. Each vault within a container has an owner (who controls vault configuration) and members (who can archive and retrieve secrets). This access control model enables flexible secrets sharing while maintaining clear ownership and accountability.

Ownership Models

User Vaults

User vaults belong to specific IPA users and are stored in that user’s vault container. The owning user has full control over their vaults, can designate other users as owners or members, and determines the vault’s encryption type. User vaults support personal secrets management like storing personal passwords, SSH keys, or API tokens.

Private vaults are a special case of user vaults where the vault owner is the currently authenticated user. When commands omit the --user parameter, they operate on the current user’s vault container, creating or accessing private vaults.

User vault containers are created automatically when a user creates their first vault. Container ownership follows user ownership, enabling users to manage their own secret storage infrastructure.

Service Vaults

Service vaults belong to IPA service principals (HTTP/, LDAP/, etc.) and store secrets associated with services rather than users. Service vaults enable applications to securely store configuration secrets, database passwords, API keys, or encryption keys that services need for operation.

Service authentication to vaults uses service Kerberos credentials. Services must obtain service tickets to archive or retrieve secrets from their vaults. This ensures only the legitimate service (with valid Kerberos credentials) can access its secrets.

Service vaults support secrets sharing between services or granting service administrators access to service secrets. Service vault members can include users (for administrative access) or other services (for service-to-service secret sharing).

Shared Vaults

Shared vaults enable team-based secrets management where multiple users need access to common secrets. Shared vaults are owned by administrators but can have multiple users, groups, or services as members with archive/retrieve privileges.

Common shared vault use cases include team passwords (shared database credentials, service account passwords), shared certificates, shared encryption keys, or project-specific API tokens. Shared vaults provide controlled access to team secrets without distributing copies or storing secrets insecurely.

Shared vault containers require explicit creation and ownership assignment. Unlike user vault containers (created automatically), shared containers must be established before creating vaults within them.

Encryption Types

Standard Vaults

Standard vaults use transport encryption (TLS) to protect secrets in transit and KRA encryption for storage. Secrets are encrypted automatically by the KRA using its internal keys. Authorized vault members can retrieve secrets without providing additional credentials beyond their IPA authentication.

Standard vaults balance security and convenience: secrets remain encrypted at rest and in transit, but members don’t need to manage separate vault passwords or keys. This model suits secrets requiring access control but not additional encryption layers.

The KRA master key encrypts all standard vault secrets. While this provides strong encryption, it means KRA compromise (or administrator access to KRA keys) could theoretically decrypt vault contents. Organizations requiring defense against administrator access should use symmetric or asymmetric vaults.

Symmetric Vaults

Symmetric vaults require a password to encrypt secrets before archiving and decrypt secrets during retrieval. The vault password never leaves the client; secrets are encrypted client-side before transmission to the KRA. This ensures even KRA administrators cannot decrypt vault contents without the vault password.

Symmetric vault security depends entirely on password strength and protection. Lost passwords permanently render symmetric vault contents irretrievable (unless escrow is configured). Shared symmetric vaults require secure password distribution to all authorized members.

Vault passwords are distinct from user authentication passwords. The vault password specifically protects vault contents and can differ from the user’s IPA login password. This separation enables vault password changes without affecting user authentication.

Asymmetric Vaults

Asymmetric vaults use public key encryption, where secrets are encrypted with a public key during archival and decrypted with the corresponding private key during retrieval. The private key never leaves the client and is not stored in IPA, providing maximum security against server compromise.

Asymmetric vault workflow requires maintaining private keys securely. Public keys are stored with the vault, enabling anyone with vault membership to archive secrets, but only private key holders can retrieve them. This split enables scenarios where many people can contribute secrets but few can access them.

Lost private keys permanently render asymmetric vault contents irretrievable. Organizations using asymmetric vaults should establish private key backup and recovery procedures, potentially including key escrow to trusted administrators.

Vault Members and Owners

Owners

Vault owners control vault configuration including encryption type, vault password, public keys, and access control (adding/removing owners and members). Owners can modify vault metadata, delete vaults, and change encryption parameters. The creator of a vault automatically becomes an owner.

Multiple owners enable shared vault administration. Ownership can transfer to users, groups, or services. Group ownership enables team-based vault management where any team member can administer vaults.

Owner privileges include member privileges; owners can also archive and retrieve secrets in addition to managing vault configuration.

Members

Vault members can archive and retrieve secrets but cannot modify vault configuration, change access control, or delete vaults. Membership is the appropriate privilege level for users who need secret access without vault administration capabilities.

Members can include individual users, groups (enabling team access), or services (enabling automated secret access). Group membership is particularly powerful for team secrets, automatically granting access to all current group members.

Member privileges respect vault encryption types. Symmetric vault members must provide the vault password; asymmetric vault members must provide the private key. Standard vault members only need IPA authentication.

Secret Archival and Retrieval

Archiving a secret stores it in the vault, overwriting any previously archived secret. Vaults can only store one secret at a time; archiving a new secret replaces the old one. This single-secret model ensures clarity about current secret state but requires separate vaults for multiple secrets.

Secrets are arbitrary binary data with no size restrictions beyond practical limits. Common secret types include passwords (plaintext strings), private keys (PEM format), certificates, JSON configuration files, or encrypted data blobs.

Retrieval returns the currently archived secret to the client. For standard vaults, only IPA authentication is required. For symmetric vaults, the vault password must be provided. For asymmetric vaults, the private key must be provided. Retrieval operations are logged for audit purposes.

Best Practices

Use asymmetric vaults for maximum security: When secrets require protection even from FreeIPA administrators, use asymmetric encryption with well-protected private keys.

Leverage shared vaults for team secrets: Rather than sharing passwords insecurely (email, chat), store them in shared vaults with controlled membership.

Document vault purposes: Maintain clear records of what each vault stores and who should have access. This aids auditing and prevents orphaned secrets.

Backup vault passwords and keys: For symmetric and asymmetric vaults, establish secure backup procedures for passwords/keys. Lost credentials mean permanent data loss.

Use meaningful vault names: Name vaults descriptively (database_password, api_key_production) rather than generic names (secret1, vault_a).

Audit vault access regularly: Review vault membership and monitor retrieval logs to detect inappropriate access or unused vaults.

Rotate vault contents: Treat vaults like any other secrets management; rotate stored passwords/keys periodically and update vault contents.

Minimize vault membership: Grant access only to users/services truly requiring it. Overly broad membership weakens secrets protection.

Consider escrow for critical vaults: For vaults containing business-critical secrets, configure escrow enabling trusted administrators to recover contents if owners lose access.

Test vault operations before production use: Verify archival and retrieval workflows in test environments before storing production secrets.

Integration with Other IPA Components

Key Recovery Authority (KRA)

Vaults are built on Dogtag’s KRA, which provides encryption, key management, and secure storage infrastructure. KRA must be configured on at least one IPA server for vault functionality.

User and Service Management

Vault ownership and membership reference IPA users (user-* commands) and services (service-* commands), integrating secrets management with identity infrastructure.

Group Management

Groups can be vault members, enabling team-based access control that automatically adapts as group membership changes (group-* commands).

Authentication

Vault access requires Kerberos authentication. Users and services must obtain valid tickets before accessing vaults, ensuring authentication context for all vault operations.

EXAMPLES

List vaults:

ipa vault-find
    [--user <user>|--service <service>|--shared]

Add a standard vault:

ipa vault-add <name>
    [--user <user>|--service <service>|--shared]
    --type standard

Add a symmetric vault:

ipa vault-add <name>
    [--user <user>|--service <service>|--shared]
    --type symmetric --password-file password.txt

Add an asymmetric vault:

ipa vault-add <name>
    [--user <user>|--service <service>|--shared]
    --type asymmetric --public-key-file public.pem

Show a vault:

ipa vault-show <name>
    [--user <user>|--service <service>|--shared]

Modify vault description:

ipa vault-mod <name>
    [--user <user>|--service <service>|--shared]
    --desc <description>

Modify vault type:

ipa vault-mod <name>
    [--user <user>|--service <service>|--shared]
    --type <type>
    [old password/private key]
    [new password/public key]

Modify symmetric vault password:

ipa vault-mod <name>
    [--user <user>|--service <service>|--shared]
    --change-password
ipa vault-mod <name>
    [--user <user>|--service <service>|--shared]
    --old-password <old password>
    --new-password <new password>
ipa vault-mod <name>
    [--user <user>|--service <service>|--shared]
    --old-password-file <old password file>
    --new-password-file <new password file>

Modify asymmetric vault keys:

ipa vault-mod <name>
    [--user <user>|--service <service>|--shared]
    --private-key-file <old private key file>
    --public-key-file <new public key file>

Delete a vault:

ipa vault-del <name>
    [--user <user>|--service <service>|--shared]

Display vault configuration:

ipa vaultconfig-show

Archive data into standard vault:

ipa vault-archive <name>
    [--user <user>|--service <service>|--shared]
    --in <input file>

Archive data into symmetric vault:

ipa vault-archive <name>
    [--user <user>|--service <service>|--shared]
    --in <input file>
    --password-file password.txt

Archive data into asymmetric vault:

ipa vault-archive <name>
    [--user <user>|--service <service>|--shared]
    --in <input file>

Retrieve data from standard vault:

ipa vault-retrieve <name>
    [--user <user>|--service <service>|--shared]
    --out <output file>

Retrieve data from symmetric vault:

ipa vault-retrieve <name>
    [--user <user>|--service <service>|--shared]
    --out <output file>
    --password-file password.txt

Retrieve data from asymmetric vault:

ipa vault-retrieve <name>
    [--user <user>|--service <service>|--shared]
    --out <output file> --private-key-file private.pem

Add vault owners:

ipa vault-add-owner <name>
    [--user <user>|--service <service>|--shared]
    [--users <users>]  [--groups <groups>] [--services <services>]

Delete vault owners:

ipa vault-remove-owner <name>
    [--user <user>|--service <service>|--shared]
    [--users <users>] [--groups <groups>] [--services <services>]

Add vault members:

ipa vault-add-member <name>
    [--user <user>|--service <service>|--shared]
    [--users <users>] [--groups <groups>] [--services <services>]

Delete vault members:

ipa vault-remove-member <name>
    [--user <user>|--service <service>|--shared]
    [--users <users>] [--groups <groups>] [--services <services>]

Commands

Command Description

vault-add-member Add members to a vault.

vault-add-owner Add owners to a vault.

vault-del Delete a vault.

vault-find Search for vaults.

vault-remove-member Remove members from a vault.

vault-remove-owner Remove owners from a vault.

vault-show Display information about a vault.

vaultconfig-show Show vault configuration.

vaultcontainer-add-owner Add owners to a vault container.

vaultcontainer-del Delete a vault container.

vaultcontainer-remove-owner Remove owners from a vault container.

vaultcontainer-show Display information about a vault container.

vault-add-member

Usage: ipa [global-options] vault-add-member NAME [options]

Add members to a vault.

Arguments

Argument Required Description

NAME yes Vault name

Options

Option Description

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to add

--groups GROUPS groups to add

--services SERVICES services to add

vault-add-owner

Usage: ipa [global-options] vault-add-owner NAME [options]

Add owners to a vault.

Arguments

Argument Required Description

NAME yes Vault name

Options

Option Description

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to add

--groups GROUPS groups to add

--services SERVICES services to add

vault-del

Usage: ipa [global-options] vault-del NAME [options]

Delete a vault.

Arguments

Argument Required Description

NAME yes Vault name

Options

Option Description

--continue Continuous mode: Don’t stop on errors.

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

vault-find

Usage: ipa [global-options] vault-find [CRITERIA] [options]

Search for vaults.

Arguments

Argument Required Description

CRITERIA no A string searched in all relevant object attributes

Options

Option Description

--name NAME Vault name

--desc DESC Vault description

--type TYPE Vault type

--timelimit TIMELIMIT Time limit of search in seconds (0 is unlimited)

--sizelimit SIZELIMIT Maximum number of entries returned (0 is unlimited)

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--services List all service vaults

--users List all user vaults

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--pkey-only Results should contain primary key attribute only (“name”)

vault-remove-member

Usage: ipa [global-options] vault-remove-member NAME [options]

Remove members from a vault.

Arguments

Argument Required Description

NAME yes Vault name

Options

Option Description

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to remove

--groups GROUPS groups to remove

--services SERVICES services to remove

vault-remove-owner

Usage: ipa [global-options] vault-remove-owner NAME [options]

Remove owners from a vault.

Arguments

Argument Required Description

NAME yes Vault name

Options

Option Description

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to remove

--groups GROUPS groups to remove

--services SERVICES services to remove

vault-show

Usage: ipa [global-options] vault-show NAME [options]

Display information about a vault.

Arguments

Argument Required Description

NAME yes Vault name

Options

Option Description

--rights Display the access rights of this entry (requires —all). See ipa man page for details.

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

vaultconfig-show

Usage: ipa [global-options] vaultconfig-show [options]

Show vault configuration.

Options

Option Description

--transport-out TRANSPORT-OUT Output file to store the transport certificate

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

vaultcontainer-add-owner

Usage: ipa [global-options] vaultcontainer-add-owner [options]

Add owners to a vault container.

Options

Option Description

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to add

--groups GROUPS groups to add

--services SERVICES services to add

vaultcontainer-del

Usage: ipa [global-options] vaultcontainer-del [options]

Delete a vault container.

Options

Option Description

--continue Continuous mode: Don’t stop on errors.

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

vaultcontainer-remove-owner

Usage: ipa [global-options] vaultcontainer-remove-owner [options]

Remove owners from a vault container.

Options

Option Description

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

--users USERS users to remove

--groups GROUPS groups to remove

--services SERVICES services to remove

vaultcontainer-show

Usage: ipa [global-options] vaultcontainer-show [options]

Display information about a vault container.

Options

Option Description

--rights Display the access rights of this entry (requires —all). See ipa man page for details.

--service SERVICE Service name of the service vault

--shared Shared vault

--user USER Username of the user vault

--all Retrieve and print all attributes from the server. Affects command output.

--raw Print entries as stored on the server. Only affects output format.

--no-members Suppress processing of membership attributes.

Related Topics

user service