aws-msk-iam-sasl-signer

This is an Amazon MSK Library in Ruby. This library provides a function to generates a base 64 encoded signed url to enable authentication/authorization with an MSK Cluster. The signed url is generated by using your IAM credentials.

Features

• Provides a function to generate auth token using IAM credentials from the AWS default credentials chain.
• Provides a function to generate auth token using IAM credentials from the AWS named profile.
• Provides a function to generate auth token using assumed IAM role’s credentials.

---

• Quick start
• Support
• License
• Code of conduct
• Contribution guide

Get Started

Installation

To install aws-msk-iam-sasl-signer-ruby, run this command in your terminal. This is the preferred method to install aws-msk-iam-sasl-signer-ruby, as it will always install the most recent stable release.

gem install aws-msk-iam-sasl-signer

Examples

• rdkafka (using rdkafka gem)

In order to use a named profile to generate the token, replace the generate_auth_token function with code below:

  signer = AwsMskIamSaslSigner::MSKTokenProvider.new(region: 'us-east-1')
  auth_token = signer.generate_auth_token_from_profile(
    aws_profile: 'my-profile'
  )

In order to use a role arn to generate the token, replace the generate_auth_token function with code below:

    signer = AwsMskIamSaslSigner::MSKTokenProvider.new(region: 'us-east-1')
    auth_token = signer.generate_auth_token_from_role_arn(
        role_arn: 'arn:aws:iam::1234567890:role/my-role'
    )

In order to use a custom credentials provider, replace the generate_auth_token function with code below :

    signer = AwsMskIamSaslSigner::MSKTokenProvider.new(region: 'us-east-1')
    auth_token = signer.generate_auth_token_from_credentials_provider(
      'your-credentials-provider'
    )

Running tests

You can run tests in the currently configured Ruby version using rake. By default, it will run all the unit tests.

bundle exec rake test

To fix lint issues, run rubocop.

bundle exec rubocop -x

Code Climate

This project uses code climate to maintain code quality. Code Climate will be run on every pull request and will fail if the code quality is not maintained. Code climate can be run locally using the command below.

bundle exec rake codeclimate

CLI

You can generate a signed url using the CLI.

bundle exec signer --help               
Commands:
  signer generate                                         # Generate a token using credential provider chain
  signer generate-from-profile --aws-profile=AWS_PROFILE  # Generate a token using aws profile
  signer generate-from-role-arn --role-arn=ROLE_ARN       # Generate a token using role arn
  signer help [COMMAND]                                   # Describe available commands or one specific command

TroubleShooting

Finding out which identity is being used

When using the token to authenticate against an MSK cluster, you may receive an Access denied error. There may be some doubt as to which credential is being exactly used. The credential may be sourced from a role ARN, EC2 instance profile, credential profile etc. When calling generate_auth_token, you can set aws_debug argument to true.

MSKAuthTokenProvider.generate_auth_token(aws_debug: true)

generate_auth_token will return a third value, the caller identity:

auth_token = MSKAuthTokenProvider.generate_auth_token(aws_debug: true)
puts "Caller identity: #{auth_token.caller_identity}"

Support

If you want to report a bug, or have ideas, feedback or questions about the gem, let me know via GitHub issues and I will do my best to provide a helpful answer. Happy hacking!

License

The gem is available as open source under the terms of the MIT License.

Code of conduct

Everyone interacting in this project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Contribution guide

Pull requests are welcome!

Releasing

• create PR with version change
• bump version in lib/aws-msk-iam-sasl-signer/version.rb
• approve and merge

git checkout main
git pull origin main
VERSION="v$(grep -o 'VERSION = "[^"]*' lib/aws-msk-iam-sasl-signer/version.rb | grep -o '[^"]*$')"
git tag -a ${VERSION} -m "${VERSION}"
git push origin ${VERSION}