# Shell IAM - Identity Access Manager

Shell IAM is a small python utility that helps you to manage differents 
identities along your terminal journey.

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](https://direnv.net) 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:

```shell
pipx install python-iam
```

Install in your shell:

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

### Initial setup

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

```yaml
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:

```shell
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:

```shell
iam res list
iam res show account
```

Then you can see whats happen:

```shell
iam shell enable home
iam shell enable work
iam shell disable
```