goth

By default, gothic uses a CookieStore from the gorilla/sessions package with specific default options (Path: /, MaxAge: 30 days, HttpOnly: true, Secure: false).

You can override the gothic.Store variable at application startup to customize session behavior, such as setting a session secret, adjusting MaxAge, or enabling Secure cookies for production (HTTPS).

key := ""             // Replace with your SESSION_SECRET or similar
maxAge := 86400 * 30  // 30 days
isProd := false       // Set to true when serving over https

store := sessions.NewCookieStore([]byte(key))
store.MaxAge(maxAge)
store.Options.Path = "/"
store.Options.HttpOnly = true   // HttpOnly should always be enabled
store.Options.Secure = isProd

gothic.Store = store

To use the Nextcloud provider, you must create an OAuth 2.0 Client within your Nextcloud instance.

1. Navigate to Settings -> Security -> OAuth 2.0 client in your Nextcloud admin settings.
2. Create a new client with the name goth.
3. Set the redirection URI to http://localhost:3000/auth/nextcloud/callback.
4. Retrieve the Client Identifier and Secret generated by Nextcloud. These are required for your application configuration.

You can run the provided example application to see Goth in action. Note that you must set the necessary environment variables for the specific providers you wish to test (refer to examples/main.go for details).

1. Clone the repository.
2. Navigate to the examples directory.
3. Install dependencies, build, and run.

$ git clone git@github.com:markbates/goth.git
$ cd goth/examples
$ go get -v
$ go build
$ ./examples

To use Goth in your Go project, install it using go get:

$ go get github.com/markbates/goth

You can spin up a local Nextcloud instance for testing using Docker Compose and Traefik. Ensure you have an external network named traefik-web created.

Use the following docker-compose.yml configuration:

version: '2'

networks:
  traefik-web:
    external: true

services:
  app:
    image: nextcloud
    restart: always
    networks:
      - traefik-web
    labels:
      - traefik.enable=true
      - traefik.frontend.rule=Host:${NEXTCLOUD_DNS}
      - traefik.docker.network=traefik-web
    environment:
      SQLITE_DATABASE: "database.sqlite3"
      NEXTCLOUD_ADMIN_USER: admin
      NEXTCLOUD_ADMIN_PASSWORD: admin
      NEXTCLOUD_TRUSTED_DOMAINS: ${NEXTCLOUD_DNS}

Start the environment by running:

NEXTCLOUD_DNS=goth.my.server.name docker-compose up -d

Default credentials for the instance will be admin / admin.

To run the default login example provided in the <goth>/examples directory, you must provide the Nextcloud instance URL, the Client Identifier, and the Client Secret via environment variables. You also need to provide a SESSION_SECRET.

NEXTCLOUD_URL=https://goth.my.server.name \
NEXTCLOUD_KEY=<your-key> \
NEXTCLOUD_SECRET=<your-secret> \
SESSION_SECRET=1 \
./examples

To run the provider-specific tests, use the same environment variables required for the login example, but execute the Go test command.

NEXTCLOUD_URL=https://goth.my.server.name \
NEXTCLOUD_KEY=<your-key> \
NEXTCLOUD_SECRET=<your-secret> \
SESSION_SECRET=1 \
go test -v

Goth supports a wide range of authentication providers including:

• Amazon, Apple, Auth0, Azure AD, Battle.net, Bitbucket, Box, ClassLink, Cloud Foundry, Dailymotion, Deezer, DigitalOcean, DingTalk, Discord, Dropbox, Eve Online, Facebook, Fitbit, Gitea, GitHub, Gitlab, Google, Heroku, InfluxCloud, Instagram, Intercom, Kakao, Lastfm, LINE, Linkedin, Mailru, Meetup, MicrosoftOnline, Naver, Nextcloud, Okta, OneDrive, OpenID Connect (auto discovery), Oura, Patreon, Paypal, Reddit, SalesForce, Shopify, Slack, Soundcloud, Spotify, Steam, Strava, Stripe, TikTok, Tumblr, Twitch, Twitter, Typetalk, Uber, VK, WeCom, Wepay, Xero, Yahoo, Yammer, Yandex, Zoom

When building a new provider for Goth, you must implement the Session interface. This interface manages the authentication state by marshaling and persisting data between the start and end of the OAuth/OIDC authorization process.

Required methods:

• GetAuthURL(): Returns the provider's authentication endpoint URL.
• Marshal(): Generates a string representation of the session state to be stored (e.g., in a cookie or database) between requests.
• Authorize(Provider, Params): Validates the data returned from the provider and returns an access token.

type Session interface {
	GetAuthURL() (string, error)
	Marshal() string
	Authorize(Provider, Params) (string, error)
}