Skip to content
local-cert
Browse the documentation

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:

ObjectRoleWhat it carries
IAM userlocal-cert's identitya key pair, and nothing else
IAM rolewhat local-cert is allowed to dothe Route53 policy, which you extend over time
Role policythe list of allowed zonesgenerated 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

  1. AWS console → IAM → Users → Create user.
  2. Name: local-cert. Leave Provide user access to the AWS Management Console unchecked.
  3. On the permissions step, attach nothing. Finish creating the user.
  4. Open the user → Security credentials → Create access key → use case Application running outside AWS.
  5. 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

  1. Providers → + New provider.
  2. Give it a name (aws-prod) and paste the key pair.
  3. 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

  1. IAM → Roles → Create role → Custom trust policy.
  2. Paste the trust policy shown by the wizard. It lets only your user assume the role:
Trust policy (example)
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "LocalCertAssume",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::123456789012:user/local-cert"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
  1. On the permissions step, don't add any managed policy.
  2. Role name: local-cert-dns. Create it.
  3. 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:
Initial permissions policy
{
  "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"
    }
  ]
}
  1. 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:

CheckIf it fails
Key pairunknown, 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:

Permissions policy with two zones (example)
{
  "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

ActionScopeWhy
ListHostedZonesaccountoffer the list of zones; AWS doesn't allow restricting it
GetChangeaccountwait until a write has propagated
GetHostedZone, ListResourceRecordSetsdeclared zonesfind the name servers to query, list records
ChangeResourceRecordSetsdeclared zones, TXT / A / AAAA types, UPSERT / DELETE actionswrite the validation TXT; publish a host's address if you ask for it
iam:ListAccessKeys, DeleteAccessKey, ListUserPolicies, DeleteUserPolicy, DeleteUserthe provider's IAM user, and only that useroptional: delete it when the provider is removed (cleanup)
iam:ListRolePolicies, DeleteRolePolicythe provider's role, and only that roleoptional: 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:

User policy, cross-account case
{
  "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.

.env
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=…
  • _NAME declares 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_ARN and _REGION are 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 DEFAULT label 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:

  1. the role session deletes the IAM user: its access keys, its inline policies, then the user itself;
  2. 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 CLI
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

  1. In IAM, create a second access key on the user.
  2. Providers → Edit → Replace the key pair → Test, then Save.
  3. In IAM, deactivate the old key, then delete it.

The role and its policy are not affected.