Installation

There are two ways to configure Authula in your project: as a standalone server or as a library integrated into your existing API server.

The following sections will guide you through both methods.

Standalone Mode

Setup configuration file

Make a copy of the config.example.toml file provided in the repository.
Rename the copied file to config.toml.
Populate the configuration fields with your desired settings. Most of these settings allow you to configure the server according to your needs.
It is recommended that you do not set secret values within the config.toml file directly. Instead, use environment variables to manage sensitive information securely.

config.toml

app_name = "Authula"
base_url = "http://localhost:8080"
base_path = "/auth"

[database]
provider = "postgres"

# ... other settings

Set environment variables via .env file

Make a copy of the .env.example file provided in the repository.
Rename the copied file to .env.
Populate the environment variables with your desired values. These values will override any corresponding values set in the config.toml file.

.env

# Path to your configuration file (e.g., ./config.toml) (optional)
AUTHULA_CONFIG_PATH=

# The base URL of your API
AUTHULA_BASE_URL=

# Used for encryption. Generate using `openssl rand -base64 50 | tr -dc 'A-Za-z0-9' | cut -c -40`
AUTHULA_SECRET=

# sqlite/postgres/mysql connection string
AUTHULA_DATABASE_URL=

Run the server via Docker

$ docker run -itd \
  -p 8080:8080 \
  -v $(pwd)/config.toml:/home/appuser/config.toml \
  -e AUTHULA_BASE_URL=http://localhost:8080 \
  -e AUTHULA_SECRET=my-app-secret \
  -e AUTHULA_DATABASE_URL=<your_connection_string> \
  ghcr.io/authula/authula:latest

Library Mode

Set environment variables

Create a .env file in the root of your project and add the following environment variables:

.env

# The base URL of your API
AUTHULA_BASE_URL=

# Used for encryption. Generate using `openssl rand -base64 50 | tr -dc 'A-Za-z0-9' | cut -c -40`
AUTHULA_SECRET=

# sqlite/postgres/mysql connection string
AUTHULA_DATABASE_URL=

Install the Package

$ go get github.com/Authula/authula

Create auth config

import (
  authula "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
)

config := authulaconfig.NewConfig(/*...*/)
auth := authula.New(&authula.AuthConfig{
  Config:  config,
  Plugins: [/*...*/],
})

Configure database

Authula supports multiple database providers. You can select a database provider by supplying it in the config.

authulaconfig.NewConfig(
  authulaconfig.WithDatabase(authulamodels.DatabaseConfig{
    Provider:   "sqlite",
  }),
)

Authula runs all migrations (core & plugins) automatically when you create a new instance of the library so all the relevant database tables are created for you without any additional steps. This is done via goose and migration files are embedded in the binary. But Authula also provides migration files which you can run manually against your database which you can find within the migrations/ directories within the repository.

Authentication Methods

Configure the authentication methods you want to use by choosing from the available plugins. Authula supports the Email/Password authentication method as a plugin and also OAuth2 providers such as Discord, GitHub and Google with more coming soon.

import (
  authula "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
  emailpasswordplugin "github.com/Authula/authula/plugins/email-password"
  emailpasswordplugintypes "github.com/Authula/authula/plugins/email-password/types"
)

config := authulaconfig.NewConfig(/*...*/)
auth := authula.New(&authula.AuthConfig{
  Config:  config,
  Plugins: [
    emailpasswordplugin.New(emailpasswordplugintypes.EmailPasswordPluginConfig{
      Enabled:                  true,
      MinPasswordLength:        8,
      MaxPasswordLength:        32,
      DisableSignUp:            false,
      RequireEmailVerification: true,
      AutoSignIn:               true,
      SendEmailOnSignUp:        true,
    }),
  ],
})

Mount Handlers

To handle API requests, you need to integrate the Authula handlers in your API.

This is an example of how it can be done with the standard library server:

// Initialise auth
config := authulaconfig.NewConfig(/*...*/)
auth := authula.New(&authula.AuthConfig{
  Config:  config,
  Plugins: [/*...*/],
})

// Start the server and mount the handler
log.Fatal(http.ListenAndServe(":8080", auth.Handler()))

Take a look at the Integrations section to see how to integrate it with other frameworks.