4 releases (2 breaking)
|0.3.0||Sep 30, 2022|
|0.2.0||Sep 29, 2022|
|0.1.1||Sep 29, 2022|
|0.1.0||Sep 29, 2022|
#335 in Authentication
Needroleshere - Yet Another AWS IAM Roles Anywhere helper
This tool is a helper program for AWS IAM Roles Anywhere to obtain credentials using a X.509 ceritificate and corresponding private key. It works well as a drop-in replacement of the official rolesanywhere-credential-helper with some advantages including:
- Support loading a fullchain certificate PEM file that contains both an end entity certificate and its intermediate CA certificates.
- Support ECS container credentials provider for SDKs and libraries without process credentials provider support.
cargo install needroleshere
yay -Sy needroleshere[AUR]
- Debian/Ubuntu: https://github.com/nkmideb/needroleshere/releases (nekomit-originals repo)
Needroleshere offers the following modes:
process-credentials: Process credentials provider mode
ecs-full: Container credentials provider mode using
ecs-full-query: Container credentials provider mode using
ecs-relative: Container credentials provider mode using
ecs-relative-query: Container credentials provider mode using
Comparisons explained later.
Process credentials provider mode (
Needroleshere acts as a credentials helper program for process credentials provider defined in AWS SDK.
This can be used a drop-in replacement for the official and original rolesanywhere-credential-helper because this supports the same parameters and usage:
[profile myrole] credential_process = needroleshere credential-process --certificate /path/to/certificate.pem --private-key /path/to/private-key.pem --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID --role-arn arn:aws:iam::account:role/role-name-with-path
The advantage of Needroleshere than the original is a certificate PEM file passed to
--certificate can contain multiple certificates so you don't have to use
--intermediates if you have intermediate CAs and put such certificates in a single file (
Server mode (
Server mode runs a HTTP server to act as other AWS SDK credential providers to enable using IAM Roles Anywhere for SDKs and libraries don't support process credentials provider. Currently ECS container credentials provider is implemented.
Run a server
Needroleshere supports (only) launching through systemd socket activation. Configure systemd units like as follows:
# /etc/systemd/system/needroleshere.service [Unit] Wants=needroleshere.socket [Service] Type=simple ExecStart=/usr/bin/needroleshere serve --region AWS_REGION RuntimeDirectory=needroleshere
# /etc/systemd/system/needroleshere.socket [Socket] ListenStream=127.0.0.1:7224 FreeBind=yes IPAddressAllow=localhost IPAddressDeny=any [Install] WantedBy=sockets.target
Group= as needed. The example unit files in full (which listens on
126.96.36.199:80) is available under ./contrib/systemd.
Use as ECS container credentials provider
Server mode supports ECS container credentials provider. To use this provider, you first need to generate a binding configuration and environment variables file using a helper command.
This provider supports using multiple roles on a single server process.
needroleshere bind myrole \ --mode ecs-full \ --url http://127.0.0.1:7224 \ --certificate /path/to/certificate.pem \ --private-key /path/to/private-key.pem \ --trust-anchor-arn arn:aws:rolesanywhere:region:account:trust-anchor/TA_ID \ --profile-arn arn:aws:rolesanywhere:region:account:profile/PROFILE_ID \ --role-arn arn:aws:iam::account:role/myrole \ --configuration-directory /path/to/etc/needroleshere
This will generate a configuration at
/path/to/etc/needroleshere/bindings/myrole and a environment file at
/path/to/etc/needroleshere/env/myrole. Treat a environment file as a secret as it includes a shared secret between Needroleshere and credentials consumer.
--configuration-directoryis default to
$RUNTIME_DIRECTORYif not specified.
- Mode variants can be specified by
--mode. For instance specify
--mode ecs-relative-queryto activate a mode uses
Running this through systemd unit is a recommended way:
# /etc/systemd/system/needroleshere-bind-somethingawesome.service [Unit] Before=somethingawesome.service After=needroleshere.socket PartOf=somethingawesome.service Wants=needroleshere.socket needroleshere.service [Service] Type=oneshot RemainAfterExit=yes # use of --no-validate is recommended if you run `bind` in a systemd unit ExecStart=/usr/bin/needroleshere bind somethingawesome --no-validate ... ExecStop=/usr/bin/needroleshere unbind somethingawesome # Can't use RuntimeDirectory here # https://github.com/systemd/systemd/issues/5394 Environment=RUNTIME_DIRECTORY=/run/needsrolehere [Install] WantedBy=somethingawesome.service # and run systemctl enable needroleshere-bind-somethingawesome.service, or specify Wants= in somethingawesome.service
Load environment file and use
# /etc/systemd/system/somethingawesome.service [Unit] # You can specify Wants= here instead of systemctl enable: # Wants=needroleshere-bind-somethingawesome.service [Service] Type=simple EnvironmentFile=/run/needroleshere/env/somethingawesome ExecStart=...
needroleshere.socket will be started before
somethingawesome.service automatically. If you restart
needroleshere bind will automatically re-run to rotate a shared shared secret (thanks to
Comparison between modes
|AWS CLI v2||✅||✅||✅||✅||✅|
|AWS SDK for C++||✅||✅||✅||✅||✅|
|AWS SDK for Go V2 (1.x)||✅||✅||✅||✅||✅|
|AWS SDK for Go 1.x (V1)||✅||✅||✅||✅||✅|
|AWS SDK for Java 2.x||✅||✅||✅||✅||✅|
|AWS SDK for Java 1.x||✅||✅||✅||✅||✅|
|AWS SDK for .NET 3.x||✅||✅||✅||✅||✅|
|AWS SDK for PHP 3.x||✅||✅||✅||✅||✅|
|AWS SDK for Python (Boto3)||✅||✅||✅||✅||✅|
|AWS SDK for Ruby 3.x||✅||✅|
|AWS SDK for Rust (preview)||✅||✅||✅||✅||✅|
process-credentials is most preferred and easy way, and use
ecs-relative-query as a last resort option.
-queryvariants to prevent using
AWS_CONTAINER_AUTHORIZATION_TOKENas some SDKs don't support. Note that -query variants don't provide SSRF protection.
ecs-relative*mode requires a special server process setup to listen on
- In the server mode, the server process has to be able to read private keys on behalf of credentials consumers. Plus,
needroleshere bindcommand also needs to be able to read keys unless
- To allow a certificate renewal with key rotation, the server process reads and parses certificates and key files in every request.
- In the ECS container credentials provider mode, an endpoint uses an access token to distinguish a role binding and authenticates its consumer. Access tokens are based on shared secret generated during
- a SHA-384 digest of secret is stored to a role binding data file and read from the server process, and a secret in cleartext is stored to a environment file.
- So consider an environment file as a secret and protect it accordingly.
needroleshere bindpreserves file mode and owner of a environment file in subsequent runs for a existing role binding.
-querymode variants use HTTP URL query string to pass an access token instead of using
AWS_CONTAINER_AUTHORIZATION_TOKENwhere turns into HTTP
AWS_CONTAINER_CREDENTIALS_*_URIis not considered a secret, it might have leaked into logs in case of request failure. And as the endpoint works on HTTP GET method, it is exploitable through SSRF attacks.
- As a protection measure, for role bindings using
AWS_CONTAINER_AUTHORIZATION_TOKEN, the endpoint rejects requests with an access token in HTTP query string.
- Only keys in RSA, P-256, P-384 are supported.
- Signer implementation of AWS4-X509-*-SHA256 algorithm uses crates from RustCrypto. Refer to their security warning if you use EC keys with this tool.
- For EC keys of curves other than P-256, its primitive implementation gated behind
hazmatfeature will be used; because AWS4-X509-ECDSA-SHA256 requires SHA-256 hash function to be used in ECDSA regardless of a curve's fields size, but
ecdsacrate restricts hash function to use with ECDSA to match the same length of curve, so we have to use primitives to force using SHA-256 for curves other than P-256...
- For EC keys of curves other than P-256, its primitive implementation gated behind
- Server mode is designed and intended to be primarily used on servers and with systemd. Supporting this mode for non-server usage is out of scope for this project.
- Especially, ECS relative URI mode requires a privilege to listen :80. We don't have a plan to implement easy-to-use implicit helper to support launching from non-root user like in aws-vault.
- Server mode can use a single AWS region per process.
needroleshere binddoes take
--regionargument, but it is only used for configuration validation happens on it.
- Server mode reads certificates and a key per request. This allows certificate renewal without reloading/restarting the server process.
- Note that systemd.exec states that using EnvironmentFile= for credentials is discouraged.
Example configurations of systemd units
See ./contrib/systemd/ for full example confiugration of systemd units.
run with systemfd and cargo-watch. the following is a shorthand to start on 127.0.0.1:3000:
To test credentials provider is working, use the following script; it run
needroleshere bind with the given argument and pass to
aws sts get-caller-identity.
./dev/roundtrip-gci.sh --region ap-northeast-1 \ --trust-anchor-arn TA_ARN \ --profile-arn PROFILE_ARN \ --role-arn ROLE_ARN \ --private-key path/to/key.pem \ --certificate path/to/fullchain.pem \ --no-validate \ --mode ecs-full
This project is licensed under the Apache-2.0 License.
Copyright 2022 Sorah Fukumori
- src/sign.rs contains a source code originally from aws-sigv4 crate, which is also available under Apache License 2.0.
- Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
- src/ecdsa_sha256.rs contains a source code originally from ecdsa crate, which is also available under Apache License 2.0.
- Copyright 2018-2022 RustCrypto Developers