Mairu

Mairu is a AWS credentials manager to securely grant AWS access to command-line tools and scripts providing a right fine-grained IAM role access to scripts and commands, per-project.

Mairu can retrieve credentials from AWS SSO (AWS IAM Identity Center), or a credential vending server implements the Mairu API.

Key features

• Grant credentials explicitly via mairu exec command - instead of implicit global configuration or AWS profiles
• In-memory credentials storage - No credentials left on disk
• AWS SSO support (and you can bring your own server)
• Automatic role switching - per-workspace configuration .mairu.json instructs a correct IAM role to assume

Installation

• Cargo: cargo install --locked mairu ^[crate]
• Mise: mise use -g github:sorah/mairu
• Aqua: sorah/mairu ^[source]
• Homebrew Tap: brew install sorah/sorah/mairu ^[tap]
• Arch Linux AUR: mairu, mairu-bin
• Binary: Binaries for Linux and macOS are available at https://github.com/sorah/mairu/releases

Get started

Mairu can be used like the following cases. In any case, Mairu automatically retrieves a AWS credential for specified role and prompts user to login when server token is expired or doesn't exist yet.

1. Configure Mairu for your AWS SSO instance

$ mairu setup-sso contoso --region ${aws_sso_region} --start-url https://my-aws-sso-domain.awsapps.com/start

2. Use as a executor

$ mairu exec --server=contoso 123456789999/AmazingAppDevelopment rails server

or, utilize Mairu's auto role feature like as follows:

$ echo '{"role": "123456789999/AmazingAppDevelopment", "server": "https://my-aws-sso-domain.awsapps.com/start"}' > my-project/.mairu.json
$ cd my-project
$ mairu exec auto rails server

3. Use as a credential process provider

# ~/.aws/config
[profile mairu_amazing_app]
credential_process = mairu credential-process contoso 123456789999/AmazingAppDevelopment

then

$ AWS_PROFILE=mairu_amazing_app rails server

Configuration

Mairu reads ~/.config/mairu/servers.d/*.json for a credential server information:

AWS IAM Identity Center (AWS SSO)

To quickly generate:

$ mairu setup-sso ${choose_server_id} --region ${aws_sso_region} --start-url https://...awsapps.com/start

Or create by hand:

{
    "url": "https://...awsapps.com/start",
    "id": "server_id", // Optional, default to {url}
    "aws_sso": {
      "region": "us-east-1"
    }
}

Mairu Assume Role Credentials API

{
    "url": "https://cred-server.example.com/", // Trailing slash is important https://docs.rs/url/latest/url/struct.Url.html#method.join
    "id": "my-credential-server", // Optional, default to {url}

    "oauth": {
        "client_id": "...",
        "client_secret": "...", // Optional

        "token_endpoint": "...", // Optional if token_endpoint is at ${url}/oauth/token
        "scope": [], // Optional, default to ["profile"]

        // Either device_grant or code_grant is required.
        // Even if configuration is empty, an empty object (e.g. "code_grant": {}) must be present to denote a support of grant type.
        "device_grant": {
            "device_authorization_endpoint": "...", // Omit if it is at ${url}/oauth/device
        },
        "code_grant": {
            "authorization_endpoint": "...", // Omit if it is at ${url}/oauth/authorize
            "local_port": 16624, // Optional. default to ephemeral port.
            "use_localhost": false, // Optional, default to false (http://127.0.0.1). Use http://localhost for redirect_uri. Has to be true for some issuers, i.e. Microsoft (public client).
        },
        "default_grant_type": "code_grant", // Optional
    }
}

How to choose a Server ID

It is recommended to use the same id for your entire organisation. Personal preferences can be stored in other location, so it is safe to distribute the servers.d file with MDM or something else.

To learn how to prepare your credential server, continue reading at Credential Server section.

Local port for callback URL

Mairu uses ephemeral port number for OAuth 2.0 callback URLs. Otherwise, you can specify --local-port (or .oauth.local_port, .aws_sso.local_port) to use fixed port number.

Usage in detail

auto role

Mairu treats auto role as a special mode. It reads closest .mairu.json file <!-- or `MAIRU_ROLE` environment variable --> as a JSON object as follows to determine a role to assume:

{
    "server": "server id or url to use", // Equivalent to --server cli argument
    "role": "role to assume",
    "mode": "preferred credential provider method", // optional
}

If it is read by a filesystem, Mairu prompts user to trust that file for the first time. And prompt appears again if the file content has been changed.

We recommend use auto role by default. This allows using per-project AWS role seamlessly, securely and concurrently! It would also be convenient to have alias ae="mairu exec auto " in your shell profile.

Role chaining

You can chain an additional sts:AssumeRole call after obtaining credentials from the credential server. This is useful when your SSO role needs to assume a different IAM role (e.g. cross-account access).

$ mairu exec --server=contoso --assume-role=arn:aws:iam::123456789012:role/TargetRole 999999999999/SSORole rails server

The following options are available for both mairu exec and mairu credential-process:

• --assume-role — ARN of the role to assume using the first-hop credentials
• --assume-role-session-name — Override the role session name (default: derived from the first-hop caller identity, falling back to $USER, then "mairu")
• --assume-role-duration-seconds — Override session duration in seconds
• --assume-role-external-id — External ID for the AssumeRole call

This can also be configured in .mairu.json via the assume_role field:

{
    // ... other fields
    "assume_role": { // optional, see "Role chaining" section
        "role_arn": "arn:aws:iam::123456789012:role/TargetRole",
        "external_id": "...", // optional
        "role_session_name": "...", // optional
        "duration_seconds": 3600 // optional
    }
}

Reauthentication

If your session with a credential server expired, Mairu prompts you to reauthenticate yourself. For existing processes under mairu exec, you'll see a warning message including a command line to start reauthentication flow.

Credential provider modes

mairu exec supports the following methods to provide credentials to AWS SDK. Choose your best way to pass obtained credentials to your app or tools you love:

• ecs (default): Run ephemeral server to emulate container provider. AWS_CONTAINER_CREDENTIALS_FULL_URI and AWS_CONTAINER_AUTHORIZATION_TOKEN environment variable will be exposed and supports automatic renewal.
• static: Expose traditional AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN environment variables (static credentials). This method doesn't support automatic renewal, so you have to restart mairu exec when credentials have expired.

<!-- TODO: - `docker`: Similar to `ecs`, but launch a proxy container on Docker to connect Mairu agent from Docker containers. See [Docker support](#docker-support) for details. AWS_CONTAINER_CREDENTIALS_FULL_URI and AWS_CONTAINER_AUTHORIZATION_TOKEN environment will be exposed and supports automatic renewal. -->

Your preferred method can be specified in --mode:

$ mairu exec --mode=static auto rails server

Alternatively, you can use Mairu mairu credential-process command for process credential provider.

<!-- ### Docker support TBD -->

Agent process

Mairu automatically launches agent process in background. This is similar to ssh-agent and gpg-agent. Mairu Agent retains all access tokens for credential server, and caches AWS credentials for re-use on memory.

It listens on $XDG_RUNTIME_DIR/mairu-agent.sock (or ~/.local/state/mairu/run/mairu-agent.sock) by default.

Credential Server API

If you don't have the AWS SSO instance, you need to run your own credential vending server to serve AWS credentials for your Mairu users. You may use a known compatible implementations, or implement your own.

Known implementations

• https://github.com/sorah/himari2amc
• https://github.com/sorah/himeko

API Spec

• HTTP_API_SPEC.md

Comparison with other products and solutions

vs. AWS IAM Identity Center (AWS SSO)

https://aws.amazon.com/iam/identity-center/

• Mairu can automatically switch AWS role to use by reading .mairu.json configuration file in a working directory, similar to .{language}-version files.
• AWS SSO stores a token on a filesystem. Mairu stores on memory and doesn't persist.
• AWS SSO has to setup a ~/.aws/config profile for every new role encountered. Mairu can reuse the single configuration (per credential server) for multiple roles and accounts.
• As Mairu retrieves all credentials from a credential server where implements compatible API, you can spin your own implementation to authenticate users and authorize AWS IAM roles with your own identity provider and authorization rules.

vs. aws-vault

https://github.com/99designs/aws-vault

• Mairu can automatically switch AWS role to use by reading .mairu.json configurati