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 service 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 ## Resource Service Integration
  23
  24 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).
  25
  26 ## Ticket Auth
  27
  28 This service can accept proffered [authentication tickets](https://indieweb.org/IndieAuth_Ticket_Auth).  It will attempt to redeem any proffered tickets, then publish the resulting tokens to a configured AMQP/RabbitMQ queue for other services to make use of.  If no AMQP server is configured, the ticket endpoint will be disabled and not advertised.
  29
  30 Ensure the output of the script `bin/ticket-queue-profile.js` is executed on RabbitMQ server to install the needed queue profile.
  31
  32 A ticket-sending UI is also available:
  33 ![Ticket Offer page](./documentation/media/ticket-page.png)
  34
  35 ## Architecture
  36
  37 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.
  38
  39 Uh, more later.
  40
  41 ![Entity relationship diagram for Postgres engine](./documentation/media/postgres-er.svg)
  42
  43 ### Quirks
  44
  45 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.
  46
  47 ### File Tour
  48
  49 - bin/ - utility scripts
  50 - config/
  51   - default.js - defines all configuration parameters' default values
  52   - index.js - merges an environment's values over defaults
  53   - *.js - environment specific values, edit these as needed
  54 - server.js - launches the application server
  55 - src/
  56   - chores.js - recurring maintenance tasks
  57   - common.js - utility functions
  58   - db/
  59     - abstract.js - base database class that any engine will implement
  60     - errors.js - database Error types
  61     - index.js - database factory
  62     - schema-version-helper.js - schema migrations aide
  63     - postgres/
  64       - index.js - PostgreSQL engine implementation
  65       - sql/ - statements and schemas
  66     - sqlite/
  67       - index.js - SQLite engine implementation
  68       - sql - statements and schemas
  69   - enum.js - invariants
  70   - errors.js - local Error types
  71   - logger/
  72     - data-sanitizers.js - logger helpers to scrub sensitive and verbose data
  73     - index.js - a very simple logging class
  74   - manager.js - process incoming requests, most of application logic resides here
  75   - service.js - defines incoming endpoints, linking the API server framework to the manager methods
  76   - template/ - HTML content
  77 - static/ - static web assets, CSS, images, et cetera
  78 - test/ - unit and coverage tests