GitHub

Note: This guide uses GitHub Apps for user sign-in, which is recommended by GitHub for new integrations.

Obtain GitHub credentials

Go to GitHub Apps.
Click on "New GitHub App".
Fill in the GitHub App name, Homepage URL, and Description.
On the app page, generate a Client secret under "Client secrets".
Note the Client ID and the generated Client Secret.
Under the "Identifying and authorizing users" section, set the Callback URL to:
```
# Assuming base path is /api/auth
http://localhost:8080/api/auth/oauth2/callback/github
```
For production, replace localhost with the base URL of your Authula server (e.g. https://api.yourdomain.com).
Make sure to check the following checkboxes:
- Request user authorization (OAuth) during installation
- Enable Device Flow
Then save the changes and click on the "Permissions & events" tab on the left, under the "Account permissions", set the "Email addresses" to "Read-only" to access the user's email.

Configure the provider

Standalone Mode

Add the following to your config.toml:

# SECURITY NOTE: It is recommended to set the 'client_secret' for each of these via their
# respective environment variables as shown in the .env.example file rather than hardcoding it here.
[plugins.oauth2.providers.github]
enabled = true
client_id = "your-client-id"
client_secret = "your-client-secret"
redirect_url = "http://localhost:8080/auth/oauth2/callback/github"
scopes = []

Library Mode

import (
  "os"
  "fmt"

  authula "github.com/Authula/authula"
  authulaconfig "github.com/Authula/authula/config"
  authulamodels "github.com/Authula/authula/models"
  oauth2plugin "github.com/Authula/authula/plugins/oauth2"
  oauth2plugintypes "github.com/Authula/authula/plugins/oauth2/types"
)

func main() {
	config := authulaconfig.NewConfig(
    authulaconfig.WithSecurity(authulamodels.SecurityConfig{
      // Make sure to configure CORS and Trusted Origins appropriately
      TrustedOrigins: []string{"your frontend origin"},
      CORS: authulamodels.CORSConfig{
        AllowCredentials: true,
        AllowedOrigins:   []string{"your frontend origin"},
      },
    }),
  )
	auth := authula.New(&authula.AuthConfig{
		Config:  config,
		Plugins: []authulamodels.Plugin{
      oauth2plugin.New(oauth2plugintypes.OAuth2PluginConfig{
        Enabled: true,
        Providers: map[string]oauth2plugintypes.ProviderConfig{
          "github": {
            Enabled:      true,
            ClientID:     os.Getenv(authulaenv.EnvGitHubClientID),
            ClientSecret: os.Getenv(authulaenv.EnvGitHubClientSecret),
            RedirectURL:  fmt.Sprintf("%s%s/oauth2/callback/github", config.BaseURL, config.BasePath),
          },
        },
      }),
    },
	})

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

Test the integration

Start your Authula server.

In your webapp, create a button when clicked on, it navigates the user to:

# (replace localhost with your Authula server URL in production).
http://localhost:8080/auth/oauth2/authorize/github?redirect_to=<YOUR_REDIRECT_URL>

You should be redirected to GitHub's authorization page. After authorizing, you will be redirected back to your application.