EWC IAM Users Edition in Bulk

Subroutines to simplify bulk edition of EWC IAM users.

Functionality

✅ Combinations of all features listed below are also supported.

Adds new users
- Emails new users with 1st-login action requirements (update password, etc.)
Updates existing users
- Updates first and/or last names
- Attaches new or replaces existing EWC IAM roles
Disables users
Deletes users
(Optional) Runs step-by-step via Jupyter Notebook, on an arbitrary amount of tabular user data in CSV format

Prerequisites

Obtain a username and password from a EWC IAM user with the ewc-iam-tenant-admin role.
Verify Python version >=3.10 is available on your working environment

Usage

Run step-by-step via Jupyter Notebook

Open the iam-user-bulk-edition-via-jupyter.ipynb notebook, start the runtime, and execute cells top to bottom to apply access/permission changes.

Run natively via Ansible Playbook

1. Setup working environment

pip install -r requirements.txt

ansible-galaxy collection install -r requirements.yml -p .ansible

2. Configure inputs

💡 For complete information on required and optional input attributes, checkout the templates/inputs.schema.json definition.

The included input configuration, in YAML format, exemplifies most common supported cases. Customize according to your needs:

# vars/inputs.yml
---
schema_version: 1
tenancy:

  # --- Tenancy Specification ---
  name: my-ewc-tenancy

  # --- User Specification ---
  users:
    - email: john.smith@example.com     # <- Adds/updates user with all defaults (email reused as username)

    - email: philipp.mayer@example.com  # <- Adds/updates user with overrides for
      username: pmayer                  #    optional username,
      first_name: Philipp               #    optional first name,
      last_name: Mayer                  #    optional last name
      roles:                            #    optional roles to
        - name: ewc-iam-tenant-admin    #    create/delete/modify other users, assign roles to users
        - name: ewc-app-admin           #    administer, deploy and create/modify resources to any integrated Apps

    - email: ada.wong@example.com       # <- Adds/updates user with all defaults (email reused as username)
      enabled: false                    #    and disables login

    - email: carlos.perez@example.com   # <- Removes user, if exists
      state: absent

  # --- Defaults ---
  # These apply to every user unless overridden per-user above
  defaults:
    deletion_protection: false
    state: present
    enabled: true
    email_verified: true
    initial_login_actions:
      - UPDATE_PASSWORD
    roles:                               #    default roles to
      - name: ewc-iam-user               #    login to the IAM self-service and change their basic profile
      - name: ewc-app-user               #    login to any integrated App
    roles_reconciliation_mode: replace
    first_name: Unknown
    last_name: Unknown

3. Execute one-line command

⚠️ You will be prompted to enter EWC IAM tenancy admin username and password. This is required by the tooling to make changes on your behalf.

ansible-playbook iam-users-bulk-edition.yml

Best Practices

Prefer a single input file per tenancy, to facilitate auditing tasks such as ensuring a single config per user. Consider these edge-cases:
- A user is marked as absent in one input config, the change is applied, and the entry is removed altogether right after. Yet their email appears on a second input config and reintroduced accidentally with login enabled by default.
- A user requires access to multiple EWC Jupyter Hub environments, but necessary roles to are stated by different input configs, with the last one applied replacing the roles added by the former ones.
There is risk of data loss or security breaching WHEN ANY OF THE ABOVE becomes true; the recommendation above mitigates said risk.
Keep the input config clean of users which are confirmed to have been marked as absent and for which said change was applied.
Backup logs or track your input file with GIT or similar version management tools, to better trace access changes applied by this tooling over time.

Development

Fork this repository and change into the Item's subdirectory

git clone https://github.com/ewcloud/ewc-user-tools.git && cd ./ewc-user-tools/item/iam-users-bulk-edition

Install the development dependencies
```
pip install -r dev-requirements.yml
```
Modify the local code and test changes, including code styling tests
```
ansible-lint --offline .
```
Share your work by following the contribution guidelines

Resources

EWC Identity and Access Management (IAM) Service