The first step is to determine one or more identities; using home and work is usually a good start. Then you will be able to attach resources to each identities. A resource can be anything like an username, an email, environment variable, an account (Unix, google, github ...), git author name, SSH keys, SSH certificates, TLS files, secrets, tokens... You can extend resources types with a powerful plugin system. To each of those resources, you can attach variables and dependencies.

When you finished to list all your user resources in a iam.yml config file, you can now start to jump from one identity to others. Be sure you have correctly installed iam in your favorite shell config, because it hooks to your shell like direnv does.

To enable an identity, simple run iam enable home in your shell session. All your resources related to this identity are now available in your shell session. You can switch back and forth between your identities, without being worried about mixing/leaking your secrets and environments. When your done your work, disable the current identity with iam disable or directly switch to another identity with iam enable work.

Iam is extensible via a plugin system that allows you to define Services. Each service may provide custom enable/disable shell scripts, custom commands and more... That let the user to implement virtually anything. Usually a service will simply load environment variables, but it can also starts process/daemons like a dedicated ssh-agent.

Quickstart

Install iam python package:

pipx install python-iam

Install in your shell:

iam shell install --shell $SHELL,bash,zsh

Initial setup

Let's create a basic configuration, with 2 identities and two resources:

mkdir -p ~/.config/iam/
cat <<EOF > ~/.config/iam/default.yml

idents:
    home:
        resources:

            # Mendatory resource to declare identity
            account:home:
                input:
                    user: jdoe
                    name: John
                    surname: Doe
                    email: johnny.d@gmail.com
                uses:
                - auth.ssh_key:home

            # Let's setup a basic ssh_keys
            auth.ssh_key:home:
                input:
                    ssh_key_file: ~/.ssh/home/id_rsa
                    ssh_pub_file: ~/.ssh/home/id_rsa.pub

    work:
        resources:

            # Mendatory resource to declare identity
            account:work:
                input:
                    user: john-doe327
                    name: John
                    surname: Doe
                    email: jdoe327@company.com
                uses:
                - auth.ssh_key:work
                - auth.gpg_key:work

            # Let's setup a basic ssh_keys
            auth.ssh_key:work:
                input:
                    ssh_key_file: ~/.ssh/work/id_rsa
                    ssh_pub_file: ~/.ssh/work/id_rsa.pub
            auth.gpg_key:work:
                input:
                    gpg_key_file: ~/.gpg/work/gpgkey
                    gpg_pub_file: ~/.gpg/work/gpgkey.pub

EOF

You can add any resources kinds listed here:

iam kind list
iam kind show auth.ssh_key

Just be sure the right part, after the colon is unique. You will be able to make custom resources later via the plugin system.

You can inspect your current configuration:

iam res list
iam res show account

Then you can see whats happen:

iam shell enable home
iam shell enable work
iam shell disable