open-authenticator

A stateless, minimal, dockerized authentication service for easy auth management. Supports custom strategies and a wide variety of PassportJS strategies.

Demo.

Features

• Set up one OAuth flow, enable a myriad of ways to authenticate!

• Demo page with multiple auth choices

• Enable strategies:

  • Easily add supported OAuth strategies via guided CLI tool
  • Define custom strategies yourself. Examples for SMS and Pushover included

• Multiple ways to run:

  • Run the provided composition
  • Include it in your own Docker composition
  • Run as a standalone container

• Upon authentication, your application receives the identifier and profile data in a standardized format

• Automatic TLS certificate generation if running in composition mode (requires ports 443 and 80)

Configuration

Configuration for strategies installed using the CLI tool are added automatically, according to the API key info you enter using the tool.

To run the configuration setup CLI tool + the strategy configuration:

• docker exec -it CONTAINER_NAME yarn setup if you are using an image, or
• yarn setup if you are building yourself, or running outside of the container.

Configuration for custom strategies can also be manually added as a key/value set in config.strategies. The key is the strategy name, the value is an object of what needs to be passed to your strategy code.

If you want to only change the config, run yarn run config. To only modify strategies, run yarn run strategies.

// Strategy configuration example. In this case it is for a custom strategy that requires a user and a token value, which is later used to send out confirmation notifications via Pushover.
"pushover": {
    "user": "PUSHOVER_USER",
    "token": "PUSHOVER_TOKEN"
}

Running by using prebuilt image (just the authenticator)

To run just the container, without Nginx:

# Perform configuration. This will be persisted locally.
$ docker run -v /absolute/path/to/your/config:/app/config/ -it scharkee/open-authenticator yarn setup

# Run the authenticator
$ docker run -d -p 80:80 -v /absolute/path/to/your/config:/app/config/ scharkee/open-authenticator --name="CONTAINER_NAME"

Run docker exec -it CONTAINER_NAME yarn run strategies when you want to adjust your strategy configurations. It will persist in your local config folder for next launch.

To make it reachable, you will want to either:

• Use with a HTTPS-enabled reverse proxy yourself, like Apache or Nginx,
• Or run it in HTTP mode (not advised, and largely unsupported by OAuth providers) on port 80 and reach it directly.

A setup for a composition using the prebuilt image would look something like this:

services:
  authenticator:
    container_name: authenticator
    image: scharkee/open-authenticator
    volumes:
      - ./config/open-authenticator:/app/config
    ports:
      - "8080:80"
  #...other services. You have to use your own https cert solution.

For an example of including open-authenticator as part of different compositions, take a look at my React Hooks boilerplate project.

If you would rather use an included HTTPS cert solution, run it in composition mode:

Set up for composition mode, or for building the container locally

# clone the repo
$ git clone https://github.com/Scharkee/open-authenticator.git
$ cd open-authenticator

# install dependencies
$ yarn

# run configuration
$ yarn setup

Running in composition mode

(needs ports 80 and 443)

This will set up Nginx with HTTPS certificates for you automatically.

$ docker-compose up -d

After configuring and running, you should be able to access open-authenticator at https://DOMAIN, if you have got your DNS correctly set.

Running outside of container, or running locally built Docker container (just the authenticator)

To run without the container, for developing custom strategies or testing:

$ yarn launch # this is for production mode. Run 'yarn dev' if you want hot reload.

To build the container locally, without Nginx, either for use with a reverse proxy or for running in HTTP mode (not advised), run:

$ docker build --tag openauthenticator .

$ docker run -p 80:80 -d openauthenticator # or yourPort:80 for custom port

You can run yarn setup before building. You do not need to map the config folder with -v if building locally like this, since it will be included when building the container.

Restoring configuration

If you only have the config.json, you can restore the managed strategies by running:

• docker exec -it CONTAINER_NAME yarn run restore if you are using an image, or
• yarn run restore if you are building yourself.

This is done every startup automatically, by the container itself.

Adding custom strategy

The template for adding a custom strategy can be found in src/strategies/template.ts. Demos for custom strategies can be found in pushover.ts and sms.ts.

Getting all available strategies

You can get all configured strategies by making a GET request to /strategies

Example response:

["google", "twitter", "github"]

This is very handy for making dynamic log-ins, for example (new strategies will appear automatically once configured). Check out my React Hooks boilerplate for an example.

Mismatched URI warning for testing

When running the demo and/or testing, make sure to configure demoUrl in the config, because otherwise some providers will complain about a mismatched url.

Unique multi-identity support

Multiple identities being linked and unlinked via open-authenticator are not supported since that would force the use of a database, and make stateless operation impossible. This instead can be implemented by the user, using the raw data returned from open-authenticator.

Contribution & Support

Submit bugs and requests through the project's issue tracker. You are also very welcome to contribute :)

License

This project is licensed under the terms of the MIT license.