README.md
# aws-msk-iam-sasl-signer
[](https://rubygems.org/gems/aws-msk-iam-sasl-signer)
[](https://www.ruby-toolbox.com/projects/aws-msk-iam-sasl-signer)
[](https://github.com/bruce-szalwinski-he/aws-msk-iam-sasl-signer-ruby/actions/workflows/ci.yml)
[](https://codeclimate.com/github/bruce-szalwinski-he/aws-msk-iam-sasl-signer-ruby)
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](#quick-start)
- [Support](#support)
- [License](#license)
- [Code of conduct](#code-of-conduct)
- [Contribution guide](#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.
```bash
gem install aws-msk-iam-sasl-signer
```
## Examples
- [rdkafka](examples/rdkafka/README.md) (using rdkafka gem)
In order to use a named profile to generate the token, replace the `generate_auth_token` function with code below:
```ruby
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:
```ruby
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 :
```ruby
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.
```bash
bundle exec rake test
```
To fix lint issues, run `rubocop`.
```bash
bundle exec rubocop -x
```
## Code Climate
This project uses [code climate](https://github.com/marketplace/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.
```bash
bundle exec rake codeclimate
```
## CLI
You can generate a signed url using the CLI.
```bash
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`.
```ruby
MSKAuthTokenProvider.generate_auth_token(aws_debug: true)
```
`generate_auth_token` will return a third value, the caller identity:
```ruby
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](https://github.com/bruce-szalwinski-he/aws-msk-iam-sasl-signer-ruby/issues/new) 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](LICENSE.txt).
## 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](CODE_OF_CONDUCT.md).
## 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
```bash
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}
```