magiclinksdev

README

magiclinksdev

The magiclinksdev project is an authentication service for magic link and One-Time Password (OTP) use cases. There is built-in email support through Amazon SES and SendGrid.

Use cases include:

• Sign up
• Log in
• Password resets
• Email verification
• And more authentication use cases

This project can be used to supplement password authentication or replace it entirely.

If your project has an alternate secure means of communication, you can use generate magic links and OTPs without sending emails. An example would be mobile push notifications.

Getting started

To get started implementing a client application that uses magiclinksdev for authentication, the recommended path is:

1. Do the quickstart
2. Find a pre-built SDK or generate one from the formatted API specification
3. Choose the magic link or OTP workflow
4. Review the implementation tips for recommendations and best practices

Screenshots

The built-in email templates are friendly to mobile and desktop screens. They also adapt to light/dark mode automatically. The templates are built using maizzle.

Suggested Magic Link Workflow

Suggested OTP Workflow

Self-hosting the service

The magiclinksdev project is open-source and can be self-hosted. Check out the Quickstart page to get started in minutes. For reference on configuring your self-hosted instance, check out the Configuration.

Source code and license

The magiclinksdev project is open source on GitHub and licensed under Apache License 2.0.

Optional SaaS platform

You can find the optional Software-as-a-Service (SaaS) platform landing page at https://magiclinks.dev. Use of the SaaS platform is not required, but it's very inexpensive and may be cheaper than deploying yourself.

Support the project

This project took a lot of time, effort, and money to create and maintain for you. If you get some business value of this project consider becoming a GitHub Sponsor.

Documentation

Index

• Constants
• Variables
• func Ptr[T any](v T) *T
• type SigningBytesClaims
  • func (s SigningBytesClaims) GetAudience() (jwt.ClaimStrings, error)
  • func (s SigningBytesClaims) GetExpirationTime() (*jwt.NumericDate, error)
  • func (s SigningBytesClaims) GetIssuedAt() (*jwt.NumericDate, error)
  • func (s SigningBytesClaims) GetIssuer() (string, error)
  • func (s SigningBytesClaims) GetNotBefore() (*jwt.NumericDate, error)
  • func (s SigningBytesClaims) GetSubject() (string, error)
  • func (s SigningBytesClaims) MarshalJSON() ([]byte, error)

Constants

const (
	AttrIss = "iss"
	AttrSub = "sub"
	AttrAud = "aud"
	AttrExp = "exp"
	AttrNbf = "nbf"
	AttrIat = "iat"
	AttrJti = "jti"
)

const (
	// ContentTypeJSON is the content type for JSON.
	ContentTypeJSON = "application/json"
	// DefaultOTPLength is the default length for OTPs.
	DefaultOTPLength = 6
	// DefaultRelativePathRedirect is the default relative path for redirecting.
	DefaultRelativePathRedirect = "redirect"
	// HeaderContentType is the content type header.
	HeaderContentType = "Content-Type"
	// LogFmt is the log format.
	LogFmt = "%s\nError: %s"
	// LogErr is the log error.
	LogErr = "error"
	// LogRequestBody is key for logging the request body.
	LogRequestBody = "requestBody"
	// LogResponseBody is key for logging the response body.
	LogResponseBody = "responseBody"
	// Over250Years is the maximum duration for this project. Restriction derived from Golang's time.Duration.
	Over250Years = 250 * 366 * 24 * time.Hour
	// ResponseInternalServerError is the response for internal server errors.
	ResponseInternalServerError = "Internal server error."
	// ResponseTooManyRequests is the response for too many requests.
	ResponseTooManyRequests = "Too many requests."
	// ResponseUnauthorized is the response for unauthorized requests.
	ResponseUnauthorized = "Unauthorized."
)

Variables

var (
	ErrParams = errors.New("invalid parameters")
)

Functions

func Ptr

func Ptr[T any](v T) *T

Types

type SigningBytesClaims

type SigningBytesClaims struct {
	Claims json.RawMessage
}

SigningBytesClaims is a JWT claims type that allows for signing claims represented in bytes.

func (SigningBytesClaims) GetAudience

func (s SigningBytesClaims) GetAudience() (jwt.ClaimStrings, error)

func (SigningBytesClaims) GetExpirationTime

func (s SigningBytesClaims) GetExpirationTime() (*jwt.NumericDate, error)

func (SigningBytesClaims) GetIssuedAt

func (s SigningBytesClaims) GetIssuedAt() (*jwt.NumericDate, error)

func (SigningBytesClaims) GetIssuer

func (s SigningBytesClaims) GetIssuer() (string, error)

func (SigningBytesClaims) GetNotBefore

func (s SigningBytesClaims) GetNotBefore() (*jwt.NumericDate, error)

func (SigningBytesClaims) GetSubject

func (s SigningBytesClaims) GetSubject() (string, error)

func (SigningBytesClaims) MarshalJSON

func (s SigningBytesClaims) MarshalJSON() ([]byte, error)

MarshalJSON helps implement the json.Marshaler interface.