AWS provider
A provider is an identity on an AWS account that local-cert uses to read and write in Route53. You create one per account — aws-prod, aws-lab — then declare your domains on it.
The model
Three objects on the AWS side, each with a precise role:
| Object | Role | What it carries |
|---|---|---|
| IAM user | local-cert's identity | a key pair, and nothing else |
| IAM role | what local-cert is allowed to do | the Route53 policy, which you extend over time |
| Role policy | the list of allowed zones | generated by local-cert, pasted by you |
The key stored in local-cert therefore grants no permission by itself: it only lets you assume the role. Adding a zone means editing the role's policy; the key never changes.
The wizard on the Providers page walks through these steps and generates each document with your real identifiers. This guide explains them in detail.
1. Create the IAM user
- AWS console → IAM → Users → Create user.
- Name:
local-cert. Leave Provide user access to the AWS Management Console unchecked. - On the permissions step, attach nothing. Finish creating the user.
- Open the user → Security credentials → Create access key → use case Application running outside AWS.
- Note the Access key ID and the Secret access key: the latter can't be viewed again afterwards.
2. Enter the key in local-cert
- Providers → + New provider.
- Give it a name (
aws-prod) and paste the key pair. - Check the key: local-cert calls
sts:GetCallerIdentity, which needs no permission, and displays the user's ARN. That ARN is used to generate what follows.
The secret key is encrypted in the database (AES-256-GCM with MASTER_KEY) and is never displayed again or returned by the API.
3. Create the role
- IAM → Roles → Create role → Custom trust policy.
- Paste the trust policy shown by the wizard. It lets only your user assume the role:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LocalCertAssume",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:user/local-cert"
},
"Action": "sts:AssumeRole"
}
]
}- On the permissions step, don't add any managed policy.
- Role name:
local-cert-dns. Create it. - Open the role → Permissions → Add permissions → Create inline policy → JSON tab, and paste the wizard's permissions policy. At this point it only contains what is needed to list zones:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LocalCertListZones",
"Effect": "Allow",
"Action": "route53:ListHostedZones",
"Resource": "*"
},
{
"Sid": "LocalCertPollChange",
"Effect": "Allow",
"Action": "route53:GetChange",
"Resource": "*"
},
{
"Sid": "LocalCertRemoveUser",
"Effect": "Allow",
"Action": [
"iam:ListAccessKeys",
"iam:DeleteAccessKey",
"iam:ListUserPolicies",
"iam:DeleteUserPolicy",
"iam:DeleteUser"
],
"Resource": "arn:aws:iam::123456789012:user/local-cert"
},
{
"Sid": "LocalCertRemoveOwnPolicy",
"Effect": "Allow",
"Action": [
"iam:ListRolePolicies",
"iam:DeleteRolePolicy"
],
"Resource": "arn:aws:iam::123456789012:role/local-cert-dns"
}
]
}- Name the policy (
local-cert-route53), save it, then copy the role ARN into the wizard.
4. Test and save
Test connection runs three checks in sequence, each depending on the previous one:
| Check | If it fails |
|---|---|
| Key pair | unknown, disabled or mistyped key |
| Role (AssumeRole) | wrong role ARN, or a trust policy that doesn't name the right user |
| Zones (ListHostedZones) | permissions policy missing from the role, or not yet propagated |
IAM applies a change within a few seconds: a test run right after pasting may fail once. When all three lines show OK, click Save.
5. Add domains
The provider can now list your zones, but is not yet allowed to write to any of them. Those permissions are added zone by zone: Add a domain. Once a few zones are declared, the role's policy looks like this:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LocalCertListZones",
"Effect": "Allow",
"Action": "route53:ListHostedZones",
"Resource": "*"
},
{
"Sid": "LocalCertPollChange",
"Effect": "Allow",
"Action": "route53:GetChange",
"Resource": "*"
},
{
"Sid": "LocalCertReadZone",
"Effect": "Allow",
"Action": [
"route53:GetHostedZone",
"route53:ListResourceRecordSets"
],
"Resource": [
"arn:aws:route53:::hostedzone/Z0123456ABCDEFGHIJK",
"arn:aws:route53:::hostedzone/Z0987654ZYXWVUTSRQP"
]
},
{
"Sid": "LocalCertWriteRecords",
"Effect": "Allow",
"Action": "route53:ChangeResourceRecordSets",
"Resource": [
"arn:aws:route53:::hostedzone/Z0123456ABCDEFGHIJK",
"arn:aws:route53:::hostedzone/Z0987654ZYXWVUTSRQP"
],
"Condition": {
"ForAllValues:StringEquals": {
"route53:ChangeResourceRecordSetsRecordTypes": [
"TXT",
"A",
"AAAA"
],
"route53:ChangeResourceRecordSetsActions": [
"UPSERT",
"DELETE"
]
}
}
},
{
"Sid": "LocalCertRemoveUser",
"Effect": "Allow",
"Action": [
"iam:ListAccessKeys",
"iam:DeleteAccessKey",
"iam:ListUserPolicies",
"iam:DeleteUserPolicy",
"iam:DeleteUser"
],
"Resource": "arn:aws:iam::123456789012:user/local-cert"
},
{
"Sid": "LocalCertRemoveOwnPolicy",
"Effect": "Allow",
"Action": [
"iam:ListRolePolicies",
"iam:DeleteRolePolicy"
],
"Resource": "arn:aws:iam::123456789012:role/local-cert-dns"
}
]
}Each provider's policy button regenerates this document at any time from the domains actually declared.
What the policy allows
| Action | Scope | Why |
|---|---|---|
ListHostedZones | account | offer the list of zones; AWS doesn't allow restricting it |
GetChange | account | wait until a write has propagated |
GetHostedZone, ListResourceRecordSets | declared zones | find the name servers to query, list records |
ChangeResourceRecordSets | declared zones, TXT / A / AAAA types, UPSERT / DELETE actions | write the validation TXT; publish a host's address if you ask for it |
iam:ListAccessKeys, DeleteAccessKey, ListUserPolicies, DeleteUserPolicy, DeleteUser | the provider's IAM user, and only that user | optional: delete it when the provider is removed (cleanup) |
iam:ListRolePolicies, DeleteRolePolicy | the provider's role, and only that role | optional: empty the role when the provider is removed |
Multiple AWS accounts
Two ways to cover a second account, depending on what you want to isolate.
One provider per account
Repeat steps 1 to 4 in the other account and name the provider accordingly. Each account has its own key; revoking one doesn't affect the other. This is the easiest setup to reason about.
One key, one role per account
The user stays in account A; the role is created in account B, with the same trust policy (account A's user ARN). Across accounts, the user must also be allowed to assume that role. Attach this inline policy to it:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "LocalCertAssumeDnsRole",
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::123456789012:role/local-cert-dns"
}
]
}Then create a second provider with the same key pair and the ARN of account B's role.
Variants
Without a role
Uncheck Use an IAM role in the wizard: the permissions policy is then pasted directly onto the user. That is one step fewer, at the cost of a key that carries the permissions itself.
Without a key
If local-cert runs inside AWS or in a cluster with IRSA, check No key: the provider uses the process credentials (instance role, pod role, environment variables). A role to assume is still possible on top of that.
Declaring a provider with environment variables
When credentials must come from the deployment rather than the database — secrets managed by the orchestrator, infrastructure described as code — a provider can be declared with variables. Everything is optional: with no variables at all, providers are managed from the console only.
PROVIDER_AWS_DEFAULT_NAME="Default AWS"
PROVIDER_AWS_DEFAULT_ACCESS_KEY_ID=AKIA…
PROVIDER_AWS_DEFAULT_SECRET_ACCESS_KEY=…
PROVIDER_AWS_DEFAULT_ROLE_ARN=arn:aws:iam::123456789012:role/local-cert-dns
# a second account: same block, different label
PROVIDER_AWS_PROD_NAME="aws-prod"
PROVIDER_AWS_PROD_ACCESS_KEY_ID=AKIA…
PROVIDER_AWS_PROD_SECRET_ACCESS_KEY=…_NAMEdeclares the provider; it is the only mandatory variable in the block. The label (DEFAULT,PROD…) is free.- Without a key pair, the provider uses the process credentials.
_ROLE_ARNand_REGIONare optional. - These providers appear in the console with an environment tag. They can be tested and their policy generated, but not edited or removed: that is done in the variables, followed by a restart. Their secret key is never written to the database.
- The
DEFAULTlabel is special: domains declared before providers existed are attached to it at startup.
Removing a provider and cleaning up AWS
Providers → Remove deletes the provider from local-cert. If you check Also clean up on AWS, the provider first undoes what the wizard had you create:
- the role session deletes the IAM user: its access keys, its inline policies, then the user itself;
- it then deletes the role's own policy.
IAM doesn't let an identity delete itself entirely: a role can only be deleted once its policies are gone, and the permission to do so comes from those policies. The local-cert-dns role therefore remains, with no permissions and nobody able to assume it. The console shows the command to delete it with an administrator account:
aws iam delete-role --role-name local-cert-dns- Without a role, the provider can only delete its own access key; the user remains, with no credentials.
- The matching permissions are the
LocalCertRemove…blocks of the generated policy. They target only the provider's user and role and only allow deletion: a stolen key could shut local-cert down, not extend its permissions. Remove them from the document if you don't want this option. - A provider created before this option existed must first receive the updated policy (policy button). If AWS refuses before anything is deleted, the provider is kept.
- The option isn't offered when another provider uses the same user or the same role, nor for providers declared with environment variables.
- If the user has managed policies attached or belongs to a group, IAM refuses to delete it: the cleanup stops there and lists what is left to do.
Key rotation
- In IAM, create a second access key on the user.
- Providers → Edit → Replace the key pair → Test, then Save.
- In IAM, deactivate the old key, then delete it.
The role and its policy are not affected.