https://github.com/spyoungtech/certbot-route53-hook
Cerbot manual auth hook for satisfying dns challenges via AWS Route 53 / boto3
https://github.com/spyoungtech/certbot-route53-hook
Last synced: about 1 year ago
JSON representation
Cerbot manual auth hook for satisfying dns challenges via AWS Route 53 / boto3
- Host: GitHub
- URL: https://github.com/spyoungtech/certbot-route53-hook
- Owner: spyoungtech
- Created: 2018-01-21T16:42:18.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-04-12T16:53:02.000Z (about 7 years ago)
- Last Synced: 2025-04-11T05:10:02.200Z (about 1 year ago)
- Language: Python
- Homepage:
- Size: 15.6 KB
- Stars: 5
- Watchers: 1
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.rst
Awesome Lists containing this project
README
certbot-route-53-hook v0.2
==========================
A pre-auth and post-auth hook for certbot's manual plugin to satisfy DNS challenges by creating the required recordset
via AWS Route 53 and ``boto3``. When used as cleanup hook, it will delete the previously created record set.
Useful for using certbot to request or renew certs for systems that are not publicly accessible, such as those that may sit on an internal network. It is also suitable for automated non-interactive use.
Prerequisites
-------------
1. A domain name with DNS managed by Route53
2. A set of AWS IAM credentials with Route53 permissions
3. Docker
OR
3. Certbot
4. A Python3 environment with ``boto3`` installed (with AWS credentials configured)
How to use
----------
With Docker
^^^^^^^^^^^
The entrypoint in the dockerfile takes care of most of the arguments you need. You just need to provide AWS credentials, an email, and the domain to certify.
You can run build the image and generate your certificates using docker like so
::
docker build -t certbot-route53-hook:latest .
mkdir letsencrypt
docker run --rm -v $(pwd)/letsencrypt:/etc/letsencrypt/ -e AWS_ACCESS_KEY_ID= -e AWS_SECRET_ACCESS_KEY= certbot-route53-hook --email= -d
Your certificates will appear in the mounted directory.
Manually with certbot and Python
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Simply supply the path to ``certbot_hook.py`` for the ``--manual-auth-hook`` and ``--manual-cleaup-hook`` options to the certbot command. You should also specify ``--preferred-challenges`` as ``dns`` and the plugin as manual by supplying ``--manual``
For example to request a new certificate
::
certbot certonly --preferred-challenges=dns --manual --manual-auth-hook=/path/to/certbot_hook.py --manual-cleanup-hook=/path/to/certbot_hook.py -d secure.example.com
Then to renew, you can simply use ``certbot renew``.
NOTE: the hook is called even on dry-runs.
Other notes
-----------
IAM Policy example
^^^^^^^^^^^^^^^^^^
As a best practice, you may want to use credentials with just minimum access needed to use the hook. An example policy might look like this
::
{
"Version": "2012-10-17",
"Id": "certbot-dns-route53 sample policy",
"Statement": [
{
"Effect": "Allow",
"Action": [
"route53:ListHostedZones",
"route53:GetChange"
],
"Resource": [
"*"
]
},
{
"Effect" : "Allow",
"Action" : [
"route53:ChangeResourceRecordSets"
],
"Resource" : [
"arn:aws:route53:::hostedzone/YOURHOSTEDZONEID"
]
}
]
}
Using the hook noninteractively
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To use the hook noninteractively, you should supply the noninteractive flag ``-n`` and the ``--manual-public-ip-logging-ok`` option.
Specifying the hosted zone ID
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
It's recommended that you specify the zone id(s) you need explicitly. If you do not, the hook will attempt to use the boto3 Route53 client to get the ID.
The hook will attempt to use the following methods in order to get the zone ID:
By Environment Variable
"""""""""""""""""""""""
If you only use one hosted zone with certbot, you can set the ``CERTBOT_ZONE_ID`` environment variable.
::
export CERTBOT_ZONE_ID=ABCD1234567890
By config file
""""""""""""""
Alongside the ``certbot_hook.py`` file place a file named ``config.py`` (example template included in repo). The contents should contain a single variable ``zone_map`` which is a Python dictionary containing a mapping of zone names to zone IDs. This method supports multiple zones. For example
::
zone_map = {
'example.com': 'ABCD1234567890'
}
Automatically via boto3
"""""""""""""""""""""""
If the zone ID is not found with the above methods, the hook will request a list of all your hosted zones and find the zone it needs.
This feature is experimental. Further, there is a known issue where identifying the zone ID might fail if you have more
than 100 hosted zones. If you have more than 100 hosted zones, you may want to use the config file option instead.
Configuring AWS credentials
^^^^^^^^^^^^^^^^^^^^^^^^^^^
In order to connect to AWS resources, you need to supply credentials. You can do this in the form of environment variables or through a credentials file. An easy way to create your credentials file is using the awscli.
Install aws cli
"""""""""""""""
::
pip3 install awscli
Cofigure credentials
""""""""""""""""""""
With awscli installed, simply call the ``configure`` command to get an interactive prompt for setting up your credentials.
::
aws configure
You will be prompted to provide your access ID and secret key.
This portion of the documentation is provided as a convenience. If you have issues with credentials, please see the Amazon docs.
Similar Work
------------
`certbot-route53`_ is a shell script that does pretty much exactly the same thing.
.. _certbot-route53: https://github.com/jed/certbot-route53