Callbacks overview
Callbacks are synchronous hooks that shape auth decisions. Events are fire-and-forget side effects. Both live on goauth.Config.
Callbacks: goauth.Callbacks{ /* control flow */ },
Events: goauth.Events{ /* logging, analytics */ },
When callbacks run (sign-in success path)
flowchart TD
A[Provider authenticates] --> B[Profile → User]
B --> C{Callbacks.SignIn}
C -->|false| X[AccessDenied]
C -->|true| D[resolveUser]
D --> E{Adapter database?}
E -->|yes| F[GetUserByAccount / CreateUser / LinkAccount]
E -->|no| G[Use profile user]
F --> H{Callbacks.ResolveUser?}
G --> H
H --> I[issueSession]
I --> J{JWT strategy?}
J -->|yes| K[Callbacks.JWT]
J -->|no| L[CreateSession row]
K --> M[Set cookie / tokens]
L --> N[Callbacks.Session]
M --> N
Callback reference
| Callback | Input | Return | Purpose |
|---|---|---|---|
| SignIn | SignInCallbackParams | (bool, error) | Allow or deny sign-in |
| ResolveUser | ResolveUserParams | (*User, error) | Persist user in your DB |
| JWT | JWTCallbackParams | (JWT, error) | Add claims to token |
| Session | SessionCallbackParams | (*Session, error) | Shape API session JSON |
| Redirect | URL strings | (string, error) | Sanitize post-login redirects |
Events reference
| Event | When | Use for |
|---|---|---|
| SignIn | After auth, before response | Audit log |
| SignOut | POST signout | Revoke external sessions |
| CreateUser | Adapter created user | Welcome email, CRM |
| LinkAccount | OAuth account linked | Analytics |
| Session | GET /auth/session | Metrics |
Events cannot return errors to block sign-in.
What callbacks do NOT do
| Task | Where it belongs |
|---|---|
| Send magic link email | email.SendVerificationRequest |
| Send login OTP email | otp.SendCode |
| Send MFA OTP after password | MFA.SendCode |
| Validate password | credentials.Authorize |
| Verify WebAuthn | goauth/webauthn (internal) |
Minimal config with callbacks
Callbacks: goauth.Callbacks{
SignIn: func(ctx context.Context, p goauth.SignInCallbackParams) (bool, error) {
if p.User.Email == "" {
return false, nil
}
return true, nil
},
},