authplz-core

authplz

A simple Authentication and User Management microservice, designed to help build secure user-accessible services, and to avoid having to write another authentication and user management service (ever again).

This is heavily inspired by the way Github manage user accounts, two factor authentication, authorized devices etc., and is intended to provide common user management features required for a web application (or web application suite) to handle authentication of web, native and mobile applications, as well end devices, with the minimum possible complexity for developers.

Systems using this service will use OAuth grants with token introspection to validate user credentials so that users can create third party applications that utilise the same APIs.

This provides an alternative to hosted solutions such as StormPath and AuthRocket for companies that prefer (or require) self hosted identity providers. For a well supported self hosted alternative for Single Sign On (SSO) you may wish to investigate gluu, as well as wikipedia's List of SSO implementations. If you already have user management infrastructure, you may be interested in coreos/dex as an OAuth extension.

If you would like to be involved with this project, please first read (and agree to abide by) the Code of Conduct, then go ahead and join the chat on Gitter or open an issue.

Goals

• Developers shouldn't have to write any user management / authorization code
• Users should be able to manage their accounts & authorizations (and create third party apps using these)
• Admins should be able to manage user accounts and create integrations
• Users should be able to make informed security decisions about their account

Check out design.md for more.

Status

WIP. Most components working.

Check out the current build at https://authplz.github.io.

Usage

Frontend components and templates are now in a authplz/authplz-ui project (and have been grossly neglected). Configuration is now via a yaml configuration file which supports explicit loading of environmental variables and explains all the required config options. Use ./authplz --help to display options to specify the config file or environment prefix.

Dependencies

• Golang (for building)
• Docker (for building/running docker images and the dev environment)
• Postgres (for backing data storage)

Development

If you have contributor access to the repository, changes should be created in branches and pull requests opened to merge (as is enforced by the repository settings and Travis-CI). If you don't have access, please follow the normal fork/pull-request flow (though be aware that forking GO projects can be a little interesting due GOPATH).

All features must be implemented with tests to demonstrate the correct (and incorrect) behaviours of the feature.

1. go get github.com/authplz/authplz-core.git to fetch the core repo into your GOPATH
2. cd $GOPATH/src/github.com/authplz/authplz-core to switch to the repo
3. (For out of tree development) git remote add upstream github.com/authplz/authplz-core.git to add the root as an upstream
4. (For out of tree development) git remote set-url github.com/YOURNAME/authplz-core.git to set the master to your fork
5. ./gencert.sh to generate self signed TLS certificates
6. make build-env and make start-env to build and run dependent services (eg. the database)
7. git checkout -b "feature/my-new-feature" to create a new branch
8. Do some work...
9. make test to run repository tests
10. make run to run the application if required
11. Once tests pass you can git commit and git push your changes

For frontend development it is useful to run a local AuthPlz instance that is then proxied by the create-react-app development runner. This is automatic when calling npm start from the authplz-ui project.

Running

1. make install to install dependencies
2. ./gencert.sh to generate self signed TLS certificates
3. make build-env and make start-env to build and run dependencies
4. ./authplz to launch the app

./authplz --help will list available configuration options.

Features

• Account creation
• Account activation
• User login
• User administration
  • Account Unlock / Password Reset
  • Account enable / disable
• Account locking (and token + password based unlocking)
• User logout
• User password update
• User Password reset
• Email notifications
• Audit / Event logging
• 2FA token enrolment
  • TOTP
  • FIDO
  • BACKUP
• 2FA token validation
  • TOTP
  • FIDO
  • BACKUP
• 2FA token management
  • TOTP
  • FIDO
  • BACKUP
• [-] OAuth2
  • Authorization Code grant type
  • Implicit grant type
  • User client management
  • User token management
• ACLs (based on fosite heirachicle ie. public.something.read)
• Account linking (google, facebook, github)
• Plugin Support
  • IP based rate limiting
  • Webhooks
  • Distributed Synchronisation
• Test Server
  • Deployment to https://authplz.herokuapp.com
  • Deployment of frontend assets

Project Layout

Checkout DESIGN.md for design notes and API interaction flows.

• cmd/authplz/main.go contains the launcher for the AuthPlz server
• lib/api contains internal and external API definitions
• lib/app contains the overall application including configuration and wiring (as well as integration tests)
• lib/appcontext contains the base application context (shared across all API modules)
• lib/controllers contains controllers that can be shared across API modules
  • lib/datastore contains the data storage module and implements the interfaces required by other modules
  • lib/token contains a token generator and validator
• lib/modules contains functional modules that can be bound into the system (including interface, controller and API)
  • lib/core contains the core login/logout/action endpoints that further modules are bound into. Checkout this module for information on what components / bindings are available.
  • lib/user contains the user account management module and API
  • lib/2fa contains 2fa implementations
  • lib/user contains the account action / auditing API
  • lib/user contains oauth and OpenID functionality
• lib/templates contains default template files used by components (ie. mailer)
• lib/test contains test helpers (and maybe one day integration tests)

Modules are self-binding and should define interfaces required to function rather than including any (non api or appcontext) other modules.

Each module should define the interfaces required, a controller for interaction / data processing, and an API if required by the module. For an example, checkout lib/modules/2fa/u2f.

If you have any questions, comments, or suggestions, feel free to contact us (uhh, me) on gitter or to open an issue or a pull request.