Provider Interfaces¶

CoreAuth defines four provider interfaces that abstract authentication and OAuth functionality. Each interface can be implemented by the embedded Fosite-based system or external services like Ory.

Identity Provider¶

Manages user identities (CRUD operations).

type IdentityProvider interface {
    CreateIdentity(ctx context.Context, identity *Identity) error
    GetIdentity(ctx context.Context, id uuid.UUID) (*Identity, error)
    GetIdentityByEmail(ctx context.Context, email string) (*Identity, error)
    UpdateIdentity(ctx context.Context, identity *Identity) error
    DeleteIdentity(ctx context.Context, id uuid.UUID) error
    ListIdentities(ctx context.Context, filter *IdentityFilter) ([]*Identity, error)
}

Identity Structure¶

type Identity struct {
    ID        uuid.UUID      `json:"id"`
    State     IdentityState  `json:"state"`      // active, inactive
    Traits    IdentityTraits `json:"traits"`     // email, name, etc.
    Metadata  map[string]any `json:"metadata"`
    CreatedAt time.Time      `json:"created_at"`
    UpdatedAt time.Time      `json:"updated_at"`
}

type IdentityTraits struct {
    Email         string `json:"email"`
    EmailVerified bool   `json:"email_verified"`
    Name          string `json:"name"`
    GivenName     string `json:"given_name"`
    FamilyName    string `json:"family_name"`
    Picture       string `json:"picture"`
    Locale        string `json:"locale"`
}

Example Usage¶

// Create identity
identity := &coreauth.Identity{
    State: coreauth.IdentityStateActive,
    Traits: coreauth.IdentityTraits{
        Email:     "user@example.com",
        Name:      "John Doe",
        GivenName: "John",
    },
}
err := providers.Identity.CreateIdentity(ctx, identity)

// Get by email
identity, err := providers.Identity.GetIdentityByEmail(ctx, "user@example.com")

Authentication Provider¶

Manages user sessions (login, validation, revocation).

type AuthenticationProvider interface {
    Authenticate(ctx context.Context, req *AuthenticateRequest) (*AuthSession, error)
    ValidateSession(ctx context.Context, sessionToken string) (*AuthSession, error)
    RefreshSession(ctx context.Context, sessionToken string) (*AuthSession, error)
    RevokeSession(ctx context.Context, sessionToken string) error
    RevokeSessions(ctx context.Context, identityID uuid.UUID) error
    ListSessions(ctx context.Context, identityID uuid.UUID) ([]*AuthSession, error)
}

Authentication Methods¶

type AuthMethod string

const (
    AuthMethodPassword AuthMethod = "password"
    AuthMethodOIDC     AuthMethod = "oidc"
    AuthMethodWebAuthn AuthMethod = "webauthn"
    AuthMethodTOTP     AuthMethod = "totp"
)

Example Usage¶

// Authenticate with password
session, err := providers.Authentication.Authenticate(ctx, &coreauth.AuthenticateRequest{
    Method:     coreauth.AuthMethodPassword,
    Identifier: "user@example.com",
    Password:   "secret",
    DeviceInfo: &coreauth.DeviceInfo{
        IPAddress: r.RemoteAddr,
        UserAgent: r.UserAgent(),
    },
})

// Validate session (in middleware)
session, err := providers.Authentication.ValidateSession(ctx, sessionToken)
if err != nil {
    // Invalid or expired session
}

// Revoke all sessions (on password change)
err := providers.Authentication.RevokeSessions(ctx, userID)

OAuth Provider¶

Handles OAuth 2.0 / OpenID Connect operations.

type OAuthProvider interface {
    // Token operations
    Introspect(ctx context.Context, token string, tokenTypeHint string) (*OAuthIntrospection, error)
    Revoke(ctx context.Context, token string, tokenTypeHint string) error
    UserInfo(ctx context.Context, accessToken string) (*OAuthUserInfo, error)

    // Login/Consent flow (for custom UI)
    GetLoginRequest(ctx context.Context, challenge string) (*OAuthLoginRequest, error)
    AcceptLogin(ctx context.Context, challenge string, accept *OAuthLoginAccept) (*OAuthLoginResponse, error)
    GetConsentRequest(ctx context.Context, challenge string) (*OAuthConsentRequest, error)
    AcceptConsent(ctx context.Context, challenge string, accept *OAuthConsentAccept) (*OAuthConsentResponse, error)
}

Example Usage¶

// Introspect token (validate and get info)
introspection, err := providers.OAuth.Introspect(ctx, accessToken, "access_token")
if !introspection.Active {
    // Token is invalid or expired
}

// Get user info (OIDC)
userInfo, err := providers.OAuth.UserInfo(ctx, accessToken)
fmt.Printf("User: %s <%s>\n", userInfo.Name, userInfo.Email)

OAuth Client Store¶

Manages OAuth 2.0 client applications.

type OAuthClientStore interface {
    CreateClient(ctx context.Context, client *OAuthClient) error
    GetClient(ctx context.Context, clientID string) (*OAuthClient, error)
    UpdateClient(ctx context.Context, client *OAuthClient) error
    DeleteClient(ctx context.Context, clientID string) error
    ListClients(ctx context.Context) ([]*OAuthClient, error)
}

Client Structure¶

type OAuthClient struct {
    ClientID      string   `json:"client_id"`
    ClientSecret  string   `json:"client_secret,omitempty"`
    ClientName    string   `json:"client_name"`
    RedirectURIs  []string `json:"redirect_uris"`
    GrantTypes    []string `json:"grant_types"`
    ResponseTypes []string `json:"response_types"`
    Scope         string   `json:"scope"`
    Public        bool     `json:"public"`  // No secret (SPA, mobile)
}

Example Usage¶

// Register OAuth client
client := &coreauth.OAuthClient{
    ClientID:      "my-app",
    ClientSecret:  "super-secret",
    ClientName:    "My Application",
    RedirectURIs:  []string{"https://app.example.com/callback"},
    GrantTypes:    []string{"authorization_code", "refresh_token"},
    ResponseTypes: []string{"code"},
    Scope:         "openid profile email",
}
err := providers.OAuthClients.CreateClient(ctx, client)

// List all clients
clients, err := providers.OAuthClients.ListClients(ctx)

Embedded Implementations¶

CoreAuth provides embedded implementations for all providers:

Interface	Implementation	Backend
`IdentityProvider`	`EmbeddedIdentityProvider`	CoreAuth Storage
`AuthenticationProvider`	`EmbeddedAuthProvider`	In-memory sessions
`OAuthProvider`	`EmbeddedOAuthProvider`	Fosite
`OAuthClientStore`	`EmbeddedOAuthClientStore`	CoreAuth Storage

Creating Individual Providers¶

storage := coreauth.NewMemoryStorage()

identityProvider := coreauth.NewEmbeddedIdentityProvider(storage)
authProvider := coreauth.NewEmbeddedAuthProvider(identityProvider,
    coreauth.WithSessionDuration(24 * time.Hour),
    coreauth.WithPasswordVerifier(myVerifier),
)
clientStore := coreauth.NewEmbeddedOAuthClientStore(storage)