git.squeep.com Git - squeep-indie-auther/blob - README.md

   1 # Welcome to my IndieAuth-er
   2
   3 ## What
   4
   5 [IndieAuth](https://indieweb.org/IndieAuth) is a [protocol](https://indieauth.spec.indieweb.org/) which facilitates identifying users uniquely by the URLs they control to third-party applications.  It is an extension of [Oauth 2](https://indieauth.spec.indieweb.org).
   6
   7 This service implements the functionality required to negotiate that identity authentication and validation.
   8
   9 ## Let's Do Some Auth
  10
  11 A ```user``` is an entity known to this service, with a credential (currently a password) used to authenticate and login to this service.
  12 Authentication of a ```user``` is handled by either a [hashed password](https://en.wikipedia.org/wiki/Argon2) stored securely in one of the available database engines, or by optionally delegating to the host machine's [<abbr title="Pluggable Authentication Module">PAM</abbr> subsystem](https://en.wikipedia.org/wiki/Pluggable_Authentication_Modules).
  13 PAM can be used to leverage, exempli gratia, LDAP integration for user authentication.
  14
  15 A ```profile``` is a URL (under control of a ```user```) which contents includes the necessary meta-data informing an application to contact this server for identification validation.  Each ```user``` may have one or more ```profile```s.
  16
  17 Each ```profile``` may also be associated with a customizable list of additional [scopes](https://www.oauth.com/oauth2-servers/scope/) which may be added to any application client grant for convenience.
  18
  19 An example of the user-interface when granting consent to a client application:
  20 ![Consent page](./documentation/media/consent-page.png)
  21
  22 A rudimentary ticket-sending UI is also available:
  23 ![Ticket Offer page](./documentation/media/ticket-page.png)
  24
  25 ## Resource Service Integration
  26
  27 Other services (resources) may make calls to validate token grants by configuring a pre-shared secret, and authenticating to this server using [an HMAC-style bearer token scheme](https://git.squeep.com/?p=squeep-resource-authentication-module;a=blob_plain;f=README.md;hb=HEAD).
  28
  29 ## Ticket Auth
  30
  31 This service can accept proffered [authentication tickets](https://indieweb.org/IndieAuth_Ticket_Auth).  It will simply publish any proffered tickets for valid profiles to a configured AMQP/RabbitMQ queue for some other service to redeem and make use of.
  32
  33 ## Architecture
  34
  35 A granted token is an encrypted identifier (specifically a UUID assigned to the initial authentication request) which references the user/client relationship stored in the database.  Details such as granted scopes, token expiration, refreshability, and revocation status are stored there.
  36
  37 Uh, more later.
  38
  39 ![Entity relationship diagram for Postgres engine](./documentation/media/postgres-er.svg)
  40
  41 ### Quirks
  42
  43 This implementation is built atop an in-house API framework, for Reasons.  Limiting the footprint of external dependencies as much as is reasonable is a design goal.
  44
  45 ### File Tour
  46
  47 - bin/ - utility scripts
  48 - config/
  49   - default.js - defines all configuration parameters' default values
  50   - index.js - merges an environment's values over defaults
  51   - *.js - environment specific values, edit these as needed
  52 - server.js - launches the application server
  53 - src/
  54   - chores.js - recurring maintenance tasks
  55   - common.js - utility functions
  56   - db/
  57     - abstract.js - base database class that any engine will implement
  58     - errors.js - database Error types
  59     - index.js - database factory
  60     - schema-version-helper.js - schema migrations aide
  61     - postgres/
  62       - index.js - PostgreSQL engine implementation
  63       - sql/ - statements and schemas
  64     - sqlite/
  65       - index.js - SQLite engine implementation
  66       - sql - statements and schemas
  67   - enum.js - invariants
  68   - errors.js - local Error types
  69   - logger/
  70     - data-sanitizers.js - logger helpers to scrub sensitive and verbose data
  71     - index.js - a very simple logging class
  72   - manager.js - process incoming requests, most of application logic resides here
  73   - service.js - defines incoming endpoints, linking the API server framework to the manager methods
  74   - template/ - HTML content
  75 - static/ - static web assets, CSS, images, et cetera
  76 - test/ - unit and coverage tests