Demo
Demo

Knowledge base

PMTA knowledge base›Block <vault>›Directive§ 3.3.23.2

access-token

<vault>

The token the node uses to identify itself to the secrets vault
in the configuration this is a lineaccess-tokeninside the block <vault>
One secret instead of many — but there still is one

The line sets the token the node uses to authenticate with the vault. The token is created manually in Vault itself; PowerMTA neither requests nor renews it.

Almost everything that works through the vault needs it: reading signing keys, the receiving certificate and its password, checking a submission password via LDAP.

And it sits in the configuration in plain text. That is the essence of the trade-off: instead of a dozen secrets in the node’s files, one remains — but it gives access to all the others.

The main trap is assuming the vault removed secrets from the node. It removed many secrets and left one, the most valuable. The token in the configuration and in its backup opens access to everything in the vault — and permissions on the configuration file mean more after the vault is connected than before.
What the Hub does. It does not write it: signing keys are put on the node as files, and the receiving certificate is self-signed and has no password. A vault is worth considering once there are many nodes: its main benefit there is revocation in one place, not the absence of secrets on the node.
Recommended values

The value is the token string. What to provide for along with it:

What Why
limited token rights in Vault the node needs to read specific paths, not the whole vault
expiration and renewal an expired token = the node cannot read secrets, and so does not start
permissions on the configuration file the token is in it in plain text
a separate token per node otherwise revocation hits the whole fleet at once
The requirement to create the token manually and the fact that most capabilities need it come from the manual (§ 3.3.23.2). The advice about rights, expiration and a separate token is ours.
Example configuration
# the token sits in the configuration in the clear — it is the only secret left
<vault>
    server-url https://myvault:4500
    access-token akhdfasdhf786282684734kjsdhf</vault>
An example from the manual. After the vault is connected, permissions on the configuration file matter more than before: one line from here opens everything in the vault.
yellow — — directive names, blue — blocks. They are highlighted the same way in the text of the card.
▲

Common mistakes and problems

what people get wrong and how it ends2 mistakes▶

Giving the token more rights than needed

our experience

What it costsThe node needs to read a few paths. A token with broad rights that leaks from the configuration or its backup gives away the whole vault — including things that have nothing to do with mail.
How to spot itIt is discovered during an access review, not in operation.
How to do it rightIssue a token with a policy for specific paths and create a separate token for each node.

Not tracking the token's expiration

our experience

What it costsAn expired token means the node cannot read keys and the certificate. It breaks not at the moment of expiration but on the next configuration read — that is, at an inconvenient moment.
How to spot itConfiguration reloads stop going through with no edits to the configuration.
How to do it rightKnow the expiration date and renew in advance; check the token with the command from the reference before every configuration apply.
Compatibility
PowerMTA 6.0
described in the manual of this version · platform: any
The vendor does not state the first version for every directive — there is no note here. The name also appears in the 5.0 edition of the manual.
Reference data
Syntax
access-token <string>
Values
the string of a token created on the Vault side
Applying
reload, no restart needed
Queue
will not touch what is already queued
Where to write it
<vault>
How many times
once in the block
Everything here comes from the manual, with the section.
Inheritance
The line has no inheritance: there is one <vault> block per node, and one token in it. The secrets read through it are inherited each by its own rules — domain-key by sending address blocks, smtp-server-tls-certificate at the node level.
⇄

Related directives

2 relations

Works together with

domain-keyGlobalSigning keys are the main reason a vault is connected at all. § 3.3.23.2Lock down permissions on configuration filesThe token sits in the configuration in plain text: permissions on the file must be as narrow as on any secret. § 3.3.23.2

How to check on the node
Checked from outside — with the same token that is in the configuration:
curl -s -H 'X-Vault-Token: TOKEN' https://myvault:4500/v1/sys/health
A response with the vault status means the token is valid. An authorization error means the node will be able to read neither the signing keys nor the certificate, and this will come out on the next configuration read.
◇

What else to read

3 articles

◇Secrets in an external vaultSigning keys can be kept in HashiCorp Vault: the configuration keeps a path, and the engine fetches the key over HTTP and keeps it in memory without writing it to disk.◇Who is allowed to submit mail and for whom to accept itOut of the box, the node accepts submission only from the machine itself; two different questions — “who can send through us” and “for whose addresses we accept mail” — are answered by different directives.◇The group that grants management rightsMembership in the pmta group gives an unprivileged user the right to call the node’s commands and use submission.

In the Hub
Cost of a mistake
reversible: harms only while it is set
Scenarios
Key rotation · Node security
Neighboring settings of the block <vault>:cache-ttlserver-urlAll 3 directives of the block →