{"id":18470378,"url":"https://github.com/aliencreations/auth-platform","last_synced_at":"2025-10-19T17:58:00.103Z","repository":{"id":99301661,"uuid":"311210232","full_name":"AlienCreations/auth-platform","owner":"AlienCreations","description":"Alien Creations authentication and authorization platform","archived":false,"fork":false,"pushed_at":"2023-06-19T20:31:41.000Z","size":741,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-05-12T11:58:14.629Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AlienCreations.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-11-09T03:10:14.000Z","updated_at":"2023-02-21T22:18:00.000Z","dependencies_parsed_at":"2024-12-25T09:44:05.159Z","dependency_job_id":"df5ac22b-b387-4682-bf9e-c1adeb5393b7","html_url":"https://github.com/AlienCreations/auth-platform","commit_stats":null,"previous_names":[],"tags_count":0,"template":true,"template_full_name":null,"purl":"pkg:github/AlienCreations/auth-platform","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlienCreations%2Fauth-platform","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlienCreations%2Fauth-platform/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlienCreations%2Fauth-platform/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlienCreations%2Fauth-platform/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AlienCreations","download_url":"https://codeload.github.com/AlienCreations/auth-platform/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AlienCreations%2Fauth-platform/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278916444,"owners_count":26068090,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-08T02:00:06.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T10:13:47.302Z","updated_at":"2025-10-08T08:44:10.133Z","avatar_url":"https://github.com/AlienCreations.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"Auth Platform\n========\n\n## Overview\n\nProvides API endpoints to manage authorization via [JWT](https://jwt.io/). \n\nThe routes for this API are located at the bottom of `./server/core/core.js` and expand into their own respective route definitions from there. \nMany of them require a signed JWT. This app signs all JWTs with a common private key and issues both a JWT as well as a refresh token. \nThe refresh token includes the JWT payload and is encrypted with an internal key and the user's email address. We save the refresh token \nin the app memory and the front-end can send that up to re-authenticate a user and avoid prompting a username/password UI interruption.\n\nThis platform recognizes JWTs from both users and services - services are typically the other platforms in the microservice suite, but could potentially \nbe another third party service that needs to make API calls to us. The services should sign their own tokens with their own private key, but all JWTs can \nbe verified with a sister-library to this repo called [node-authenticator](https://github.com/aliencreations/node-authenticator). All JWTs will use RS256 \npublic/private key signing, so it's important that services for which this app wants to support incoming traffic provide their public keys \nto a `PUBLIC_KEYS` environment variable dictionary. Ideally this is a shared dictionary stored in AWS that all the platforms would receive on start-up. \n\n## Prerequisites\n\n1. Node 12.18.x\n\n2. yarn\n\n3. Docker\n\n## Build\n\n- Access to the Alien Creations Git Packages repository is required. See [NPM Access](#npm_access) below\n- run `yarn install`\n\n### NPM Access\n\n**option 1**:\nLog in to the NPM server using this command:\n```bash\nnpm login --scope=@aliencreations --registry=https://npm.pkg.github.com/\n```\n\n**option 2**:\n- add these lines to `~/.npmrc`:\n```bash\n@aliencreations:registry=https://npm.pkg.github.com/\n```\n- define NPM_TOKEN in your shell:\n```bash\nexport NPM_TOKEN='your_npm_token_value_here'\n```\n\n## Dependencies\n\n### System Components\n\n#### MySQL\nFor local development, MySQL is provided in the `docker-compose` suite. For production, it will be available in \nAWS or RDS, but the code will work the same and will leverage the [node-mysql-connector](https://github.com/aliencreations/node-mysql-connector) library.\n\n## Configuration\n\n### Database\n\n1. The schema identified by CORE_DB_NAME must be created and must have full privileges granted to CORE_DB_USER\n\n2. Tables must be created using the script defined in `./migrations/coreDb/20151119234015-initialSchema-up.sql`.\nMigration instructions can be found below.\n\n### Environment Variables\n\n#### Required\n\nThese variables need to be provided by a .env or exported into the context. \n\nSee `./run/env/demo/.env` for some more example values.\n\nvariable | description | values/format | example/suggested value\n---------|-------------|---------------|--------\nNODE_ENV | mode the API should run in | test, demo, production |  \nBUILD_NUM | Hash or something to represent the deployed build, can be viewed in the health check page | string | uuid\nCORE_DB_NAME | MySQL schema name | string | auth_platform_core\nPLATFORMS | List of known services capable of authenticating | JSON array (string) | \nPRIVATE_KEY | RSA private key from JWT signing key pair | PEM format string | \nPUBLIC_KEYS | RSA public keys for validation of JWTs signed by this and other services | JSON map related services names (from PLATFORMS env. var.) to PEM format public keys | \nWHITELIST | Subset of PLATFORMS permitted to make calls to the Auth API | JSON map of service to list of services from which it will accept calls. All services must match names on PLATFORMS list | \nNODE_AUTHENTICATOR_RELATIVE_CHECK_PERMISSION_PATH | Relative path from project root to the `checkTenantAccessPermission` controller. This should be set for the auth platform only to avoid making API calls to itself to check permission on requests | file path | '../../../server/core/controllers/api/tenantAccessPermission/checkTenantAccessPermission'\nNODE_AUTHENTICATOR_RELATIVE_CACHE_PATH | Relative path to a folder where we should store `flat-cache` containing refresh token references | file path | './cache'\n\n#### Optional\n\nThe app will use default values for the following variables if they are not provided at start-up.\n* Production most likely does not want to use most of these default values, so they should be overridden at start-up *\n\nvariable | description | values/format | default\n---------|-------------|---------------|--------\nNODE_PORTS | comma-delimited list of ports to listen on | comma-delimited list of int | 1337,1338,1339\nTHIS_SERVICE_NAME | | | platform\nTHIS_PROCESS_NAME | Optional param if we want to pass along to logger | |\nCORE_DB_HOST | domain name for MySQL database | string | localhost\nCORE_DB_USER | MySQL application user name | string | root\nCORE_DB_PASSWORD | MySQL application user password | string | root\nCORE_DB_PORT | MySQL listening port | integer | 3306\nTENANT_CONNECTION_ENCRYPTION_KEY | Key to allow us to connect to a tenant database, provided by said tenant | | \nALLOW_DEBUG | This flag is mainly used by the `node-logger` to include a deeper stacktrace in the logs | | undefined\nJWT_TTL | Length of time for which JWTs signed by this service will be valid | string - integer followed by time unit abbreviation | 20s\nLOG_LEVEL | The pino logging level to use.  If not set, defaults to `info` | string | trace, debug, info, warn, error, fatal, silent\nKEEP_ALIVE_TIMEOUT | Idle timeout for keep alive setting for HTTP sockets, in milliseconds. Must be \u003e load balancer idle timeout | integer | 120000\n\n## Maintenance\n\nThis project uses the NPM library `db-migrate` to manage the database schema over time. \nIt creates a `migrations` table in the schema, which tracks what migrations have been applied. \nMigrations have been defined in code at `sql/migrations/coreDb`. \nYou may need to also install `db-migrate-mysql`. \n\n#### Create a new migration\nSay you need to add a new column to a table. An example is adding a `source` column to the `coreDb.documents` table. \n\nSimply run this command : \n\n```bash\nyarn create-migration documentSource coreDb CORE_DB\n```\n\nThree files will be generated for you :\n```text\n./migrations/coreDb/*-documentSource.js\n./sql/migrations/coreDb/*-documentSource-down.sql\n./sql/migrations/coreDb/*-documentSource-up.sql\n```\n\nAny logic you need to apply to the migration file itself - interpolation, etc - can be added to the js file. \nAny SQL changes you want to apply to the database moving forward should be added to the `*-up.sql` file.\nAny SQL changes you would want to roll back if something bad happened should be added to the `*-down.sql` file.\n\n*Example 20180503214105-documentSource-up.sql*\n```sql\nALTER TABLE `__CORE_DB_NAME__`.`documents` ADD COLUMN `source` VARCHAR(50) NOT NULL DEFAULT '' AFTER `title`;\n```\n\n*Example 20180503214105-documentSource-down.sql*\n```sql\nALTER TABLE `__CORE_DB_NAME__`.`documents` DROP COLUMN `source`;\n```\n\n### Run migrations\nMigrating up will run all migrations which have not been applied to bring you to the latest database state. \nMigrating down will roll back one at a time, per command. \n\nAssume `coreDb` is up to date, and assume the environment is `demo`:\n\n```bash\nyarn migrate demo down coreDb # coreDb is now one migration behind\nyarn migrate demo down coreDb # coreDb is now two migrations behind\nyarn migrate demo down coreDb # coreDb is now three migrations behind\nyarn migrate demo up coreDb   # coreDb is now current again\n```\n\nYou can migrate multiple databases at once (example with `production` env): \n```bash\nyarn migrate production up coreDb legacyDb fooDb\n```\nThis assumes each of those `coreDb`, `legacyDb`, `fooDb` examples have at least an initial migration \nscript in `migrations/{dbName}/{here}` respectively,\n\n\n## Test\n\n### Lint \nRun `yarn lint`\n\n### Unit Tests\nRun `yarn test`\n- Unit tests require install, and configuration of environment variables and database as described above.\n- Unit tests will give a pass/fail report as well as a coverage report\n- Unit tests destroy/rebuild the database every spec, so it's much faster if MySQL is mounted to memory when \nrunning the tests.\n\n### Health Check\nNavigate to `http://auth-platform.test:1337/health` to see a list of supported infrastructure connections (ex: MySQL) \nand any connection errors that may be occurring. \n\n### Ping\nSimply `curl http://auth-platform.test:1337/ping --insecure` to check that the express server is up and running. It will \nreturn a `pong` response with a timestamp. \n\n* _The `--insecure` flag is an optional, quick way to avoid providing curl with an SSL \nkey to satisfy the https connection and should only be used for smoke screen testing._\n\n\n## Development\n\n### General Dependencies\n* [Environment Variables](#environment-variables)\n* [NodeJS](#nodejs)\n* [MySQL](#mysql)\n\n### Optional Dependencies\n* [Nginx](#nginx)\n\n \n### NPM\nThis project includes a few private modules, which come from the Alien Creations Git Packages.\nThe following command will update your `.npmrc` file to include a token.\n```\nnpm login --scope=@aliencreations --registry=https://npm.pkg.github.com/\n```\n\n### Environment Variables\nThe required environment variables will be enforce d by the node package [dotenv-safe](https://www.npmjs.com/package/dotenv-safe). As you add required \nenv vars. A local `.env` file has been provided for `demo` and `test` environments in `./run/env/demo/` or `./run/env/test` respectively.\n\nA project root `.env.example` outlines which vars are required and do not fail-over to defaults in the app config. \nYou can override any of these by adding a project-root `.env` file, which \nhas been added to the `.gitignore` so it isn't inadvertently committed to the repo.  \n\n* note: production _MUST_ have its own environment variables provided to it after deployment, either from a `.env` created on the machine or through some CD \ninjection.\n\n### NodeJS\nMake sure [Node is installed](https://nodejs.org/en/download/). This app requires at least version 12.x with latest yarn or npm.\nMake sure you are the owner of the folder in which NPM needs to install any global dependencies: ([article with more information](http://howtonode.org/introduction-to-npm)).\nOn OSX/Unix, this command should work:\n```\n$ sudo chown -R $USER /usr/local\n```  \n* note: Depending on how much is in that directory, that command may take a bit of time to run.\n\n### MySQL\nThis app uses MySQL as the database. It is included in the `docker-compose`. If you want to visually manage the database for local \ndevelopment, we include [phpmyadmin](https://en.wikipedia.org/wiki/PhpMyAdmin) which can typically be viewed \nat `http://localhost:8080` and accessed with username `root` and password `root`. This tool should _not_ be deployed to AWS. Local dev _only_.\n\n### Source Code\nClone the app (make sure you are added as a collaborator)\n\n*https*\n```bash\ngit clone https://yourusername@github.com/aliencreations/auth-platform.git\n```\n\n*ssh*\n```bash\ngit clone git@github.com/aliencreations/auth-platform.git\n```\n\n### Install the Node dependencies\nIf you have [yarn](https://yarnpkg.com/lang/en/docs/install/), use it, otherwise use npm.\nOn OSX, you can easily install Yarn with Homebrew:\n\n```bash\nbrew update\nbrew install yarn\n```\n\nWith Windows there is an [msi file](https://yarnpkg.com).\n\nRegardless, install the dependencies:\n\n```bash\nyarn install # or npm install\n```\n\n### Local Development DNS\nDo this, for `.test` domain. Do NOT use `.dev` (Substitute all .dev references with .test)\n - https://gist.github.com/ogrrd/5831371\n \nLocal dev needs `*.auth-platform.test` since the platform API will use `http://platform.auth-platform.test` and tenant-specific \nAPI endpoints will use their respective subdomain, for example a POST to `http://cnn-media.auth-platform.test/api/v1/document` \nwhere `cnn` would be the tenant domain for `Cable News Network` and `media` would be the organization domain.\n\n### Local Development Nginx\nIf you want to use port 80 for local dev, you can install or configure Nginx as follows. This is completely optional, as the app will work \njust fine with port specification in the urls. Copy the `/etc/nginx/auth-platform.conf` from this repo into your appropriate `sites_enabled` folder \nfrom your Nginx install location. Ideally it will live at `/etc/nginx/sites_enabled/auth-platform.conf` and will then be included \nautomatically from the `/Applications/MAMP/conf/etc/nginx.conf` file.\n\nConsider this excerpt from the `./etc/auth-platform.conf` file for an understanding of the proxy: \n\n``` \nupstream auth-platform {\n    server 127.0.0.1:3000;\n    server 127.0.0.1:3001;\n    server 127.0.0.1:3002;\n    #server 127.0.0.1:3003;\n}\n\n# The Nginx server instance.\nserver {\n    listen 80;\n    server_name *.auth-platform.test auth-platform;\n    access_log  /var/log/nginx/auth-platform.log;\n\n```\n\n### Docker Services\nThis app has a `docker-compose.yml` to pull down all the required third-party services it needs to function properly. \nThis yml file requires that some environment variables have been set ahead of time. Again, these are pulled in from \nthe appropriate run space, meaning that `NODE_ENV=test` and `NODE_ENV=demo` will populate the `docker-compose.yml` file \ndifferently. \n\nThe app has helper commands to make this easy, which can be scaled in the `package.json` scripts section: \n\nFor example, the following command will start the docker services where `NODE_ENV=demo` : \n```bash\nyarn docker demo up\n```\n \n... and for unit tests : \n\n```bash\nyarn docker test up\n```\n\nTo stop these services, simply replace `up` with `down`.\n\n* Note: You might need to increase the default memory to 4gb. https://stackoverflow.com/a/39720010/353802\n* Note: If you need to free up any memory between demo and test toggles, simply restart the Docker daemon. \n\nAfter running the `demo` compose, simply wait for the docker logs to settle down to give you an indication all the services \nare finished booting up. \n\n### Run the tests\nDon't forget to have already run `yarn docker test up` in *another terminal* so your services are available. \n\nThe unit tests invoke models which contain SQL. The test process tears down, rebuilds, and reseeds MySQL with mock \ndata every spec so there are no side-effects. For MySQL in particular, the db volume is mounted to RAM for ludicrous speed.\n\n```bash\nyarn test \n```\n\n### Start the app\nAssuming you just ran the tests, first stop the test services with `yarn docker test down` and then start the demo \nservices with `yarn docker demo up`. That command is in terminal 1.\n\nIn terminal 2, run the app in the appropriate local environment setting. For example, to run a demo : \n\n```bash\nyarn demo\n```\n\nMore local environments may be supported in the future, for long term development in which the data should persist and \nsimply migrate up, it would make sense to support this, but at this point that is not implemented. An example supplemented \nenvironment might be : \n\n```bash\nyarn dev\n```\n\n# Demo\nThe demo environment mentioned above will bootstrap fresh every time you run `yarn demo`. This merely acts as a \nworking API to support any clients that need it (web dashboards, mobile apps, etc). \n\n# Deployment\nBasic deploy script on `demo` environment/AWS : \n\n```bash\nsudo yarn docker demo up -d\nsudo pm2 start ./run/env/demo/run.sh --name demo-platform\n```\n\nDeployment on a persistent server would not want to run demo scripts because those will destroy/rebuild the \ndatabase. Instead, do something like this : \n\n```bash\npm2 start ./server/platform.js --name platform\n```\n\nThis would assume you have all the dependencies up and running : \n - MySQL\n - S3\n\nThis also assumes that environment variables are available on the process. Please see `./env.example` for a list of \nrequired env vars. Since we use `demo` and `test` for local development usually, if `./.env.example` is missing any \nrequired variables, please reference `./run/env/demo/.env` as a working file and fill in any gaps to the example file.\n\n# Debugging\nDocker has logs for each of the processes in the compose file, which should still be tailing in terminal 1. If that terminal was closed, \nsimply run `docker logs`\n\nTo ssh into a container to debug or to see pm2 logs in the data modeler for example:\n\n - List the containers\n\n```bash\ndocker ps\n```\n\n - SSH into a container. (Example container id 2d94ed9a8491)\n\n```bash\ndocker exec -it 2d94ed9a8491 /bin/bash\n```\n\nFor containers running pm2, simply run `pm2 logs` from within the container. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliencreations%2Fauth-platform","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faliencreations%2Fauth-platform","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faliencreations%2Fauth-platform/lists"}