IAM Backend

An Identity Access Management (IAM) system using Google Workspace accounts.

Intended Users. This system is intended for use at Community Builder Toolbox, Inc., a California-based 501(c)(3) non-profit organization. It is currently incubated under ZaiGeZaiGu, a volunteer platform for Chinese in the SF Bay Area.

Installation

Set up the environment

Assuming you have GitHub CLI installed (possibly via brew install gh) and uses Conda as your environment manager, execute the following commands:

git clone zgzgorg/iam-backend # Clone the repo.
cd iam-backend
conda create -n zgiam python=3.8
conda activate zgiam
make develop

Bootstrap the database

You can skip this section if you're provided with a zgiam.sql file.

1. Run make update-schema. This will create an empty SQLite file at zgiam/zgiam.sql.

2. Open this file with a SQLite editor of your choice. We recommend DBeaver, which you can install via brew install --cask dbeaver-community (assuming you have Homebrew installed).

3. Insert a row to the table account. Provide the following required fields:

   1. email -- You must be able to receive emails via this email address.
   2. first_name
   3. last_name
   4. phone_number

4. Save and exit.

Run the server

Someone should've sent you an iam_sqlite.cfg. Place it under the repo's directory. Run:

IAM_CONFIG_PATH=$PWD/iam_sqlite.cfg python zgiam/app.py

Now, go to http://127.0.0.1:5000/api/v1/. You should see a page similar to this screenshot.

Configuration

Using a file. By default, iam-backend reads /etc/zgiam/zgiam.cfg for configs. The file supports a dialect of the INI file structure defined by the Python 3 standard library configparser. A sample zgiam.cfg file can be found at zgiam/conf/default_iam.cfg. You can override the default path via the environment variable IAM_CONFIG_PATH.

Using environment variables. All variables in this file are also overridable via environment variables. The overriding environment variable should follow the format of IAM_{section}_{option}. For example:

• IAM_CORE_DEBUG
• IAM_DATABASE_TYPE
• IAM_DATABASE_FILE_PATH
• IAM_DATABASE_HOST
• IAM_DATABASE_PORT
• IAM_DATABASE_USER
• IAM_DATABASE_PASSWORD
• IAM_DATABASE_DBNAME
• IAM_DATABASE_SQLALCHEMY_TRACK_MODIFICATIONS
• IAM_LOGGING_CONFIG_PATH

Styles, Conventions, and Standards

This repo adheres to the following practices:

• Semantic Versioning 2.0.0.
• Conversational Commits: A specification for adding human and machine readable meaning to commit messages. Configured with .commitlintrc.yml.
• Black: The uncompromising code formatter for Python. Takes priority over PEP 8.
• PEP 8: Style Guide for Python Code.
  • This repo uses both pycodestyle and flake8 to enforce PEP 8. They have each other's back.
• Python code should be typed. This repo uses both mypy (by Python makers) and pytype (by Google) as type checkers. They have each other's back.

Further, this repo uses these dev-cycle tools:

• A requirements file defines dependencies that are parsable to pip. pip-tools reads the .in files and generates pip-friendly requirements.txt.

• makefile defines most of the dev-cycle actions.

  • Many of these actions are automatically triggered with pre-commit hooks.

• pytest is for unit tests.

  • pytest-cov generates the .coverage file. It computes coverage from pytest unit tests.

• Codacy checks code quality and keep track of technical debt. It integrates well into GitHub reviews.

• Pylint is another Python code analyzer.

• Dependabot makes security updates.

• CodeQL (by GitHub) and LGTM (by Semmle) discover vulnerabilities. They have each other's back.

Structure

This repo uses these modules:

• Alembic is a lightweight database migration tool for usage with the SQLAlchemy Database Toolkit for Python.
• google-auth is the Google authentication library for Python.
• Gunicorn 'Green Unicorn' is a Python WSGI HTTP Server for UNIX.
• SQLAlchemy is a Python SQL toolkit.
• Blinker provides fast & simple object-to-object and broadcast signaling for Python objects.
• Flask is a web framework for Python. Flask depends on the Jinja template engine and the Werkzeug WSGI toolkit. We use these plugins of Flask:
  • Flask-RESTX enables one to define API endpoints via a class-method structure.
  • Flask-SQLAlchemy.
  • Flask-JWT-Extended.
  • Flask-Dance for OAuth.
  • Flask-Login provides user session management for Flask.