Skip to content

getting-started.md

Latest commit

 

History

History
96 lines (69 loc) · 2.67 KB

getting-started.md

File metadata and controls

96 lines (69 loc) · 2.67 KB

Getting Started with @harperfast/oauth

The @harperfast/oauth plugin provides OAuth 2.0 and OpenID Connect (OIDC) authentication for Harper applications.

Installation

npm install @harperfast/oauth

Quick Start

1. Configure the Plugin

Add the plugin to your Harper application's config.yaml:

'@harperfast/oauth':
  package: '@harperfast/oauth'
  providers:
    github:
      clientId: ${OAUTH_GITHUB_CLIENT_ID}
      clientSecret: ${OAUTH_GITHUB_CLIENT_SECRET}

2. Set Environment Variables

For local development, export variables in your terminal session:

export OAUTH_GITHUB_CLIENT_ID="your_github_client_id"
export OAUTH_GITHUB_CLIENT_SECRET="your_github_client_secret"

Note: These export commands are for local development only. You can also use a .env file with dotenv-cli for local dev — just don't commit it to source control.

For Harper Fabric deployments, your app-root .env is deployed alongside your component, so the same .env you use locally works in production — see the Harper Fabric documentation for managing runtime environment variables.

3. (Optional) Register Lifecycle Hooks

If you need to provision users or customize the authentication flow, register hooks in your resources.js:

import { registerHooks } from '@harperfast/oauth';

registerHooks({
	onLogin: async (oauthUser, tokenResponse, session, request, provider) => {
		// Find or create user
		let user;
		for await (const u of tables.User.search([{ attribute: 'email', value: oauthUser.email }])) {
			user = u;
			break;
		}
		if (!user) {
			user = await tables.User.create({ email: oauthUser.email, name: oauthUser.name });
		}
		return { user: String(user.id) };
	},
});

See Lifecycle Hooks for complete details.

4. Start Your Application

npm start

5. Test Authentication

Navigate to:

http://localhost:9926/oauth/github/login

Supported Providers

The OAuth plugin includes built-in templates for:

  • GitHub - OAuth 2.0
  • Google - OIDC
  • Azure AD - OIDC
  • Auth0 - OIDC
  • Okta - OIDC
  • Custom - Generic OIDC provider

Important: Built-in providers are templates only. None are active until you configure them with clientId, clientSecret, and other required settings. The presence of provider code does not enable authentication or create security exposure.

Next Steps