repository·master·Indexed 20 days ago
https://github.com/hapijs/bellA third-party login plugin for the hapi.js framework that facilitates authentication via OAuth and OpenID Connect. It manages the handshake with providers, including a wide range of built-in options like Google, GitHub, and Twitter, as well as support for custom OAuth 1.0a and 2.0 protocols. The plugin handles the authorization flow and provides credentials to route handlers, though developers must implement their own long-term session management.
bell manages the third-party OAuth authentication flow. It works by adding a login endpoint and setting it to use a bell-based authentication strategy.
Key Lifecycle & Limitations:
// Typical pattern: bell handles the OAuth flow, then your handler sets the local session
server.route({
method: ['GET', 'POST'],
path: '/login',
options: {
auth: {
mode: 'try',
strategy: 'twitter'
},
handler: function (request, h) {
if (!request.auth.isAuthenticated) {
return `Authentication failed due to: ${request.auth.error.message}`;
}
// 1. Use request.auth.credentials to find/create local user
// 2. Set up local session (e.g., via @hapi/cookie)
// 3. Redirect to application
return h.redirect('/home');
}
}
});To use bell, register it as a plugin to your Hapi server and then define an authentication strategy using server.auth.strategy().
Required Strategy Options:
provider: The name of the built-in provider (e.g., 'twitter', 'google', 'github') or a custom provider object.password: A string used to encrypt the temporary state cookie.clientId: The OAuth client identifier.clientSecret: The OAuth client secret (can be a string or an object for custom client authentication, or a function returning a string).Commonly Used Options:
isSecure: Set to false if developing locally without HTTPS.isSameSite: Set to 'Lax' if experiencing issues with local testing.location: Manually set the base redirect_uri if it cannot be inferred (useful when behind a proxy).const Bell = require('@hapi/bell');
const Hapi = require('@hapi/hapi');
const server = Hapi.server({ port: 8000 });
await server.register(Bell);
server.auth.strategy('twitter', 'bell', {
provider: 'twitter',
password: 'cookie_encryption_password_secure',
clientId: 'my_twitter_client_id',
clientSecret: 'my_twitter_client_secret',
isSecure: false
});To implement a custom provider for @hapi/bell, you should use the existing implementations located in the lib/providers directory of the repository as a reference. When designing your provider, consider whether you need to support the following options to meet your requirements:
uri: To provide a URI for the authentication process.extendedProfile: To request additional user profile information from the provider.// Reference existing implementations in the source code:
// lib/providers/...The Facebook provider defaults to the ['email'] scope. You can customize the profile fields retrieved by setting the fields option in config.
Default fields: 'id,name,email,first_name,last_name,middle_name,gender,link,locale,timezone,updated_time,verified'.
Profile Structure:
{
"id": "profile.id",
"username": "profile.username",
"displayName": "profile.name",
"name": {
"first": "profile.first_name",
"last": "profile.last_name",
"middle": "profile.middle_name"
},
"email": "profile.email",
"raw": "profile"
}// Example: Requesting specific fields
config: {
fields: 'id,name,email'
}If your provider is not built-in, you can define a CustomProtocol in the provider option. Bell supports both oauth (v1) and oauth2 protocols.
Set protocol: 'oauth' and provide:
auth: The authorization endpoint URI.token: The access token endpoint URI.signatureMethod: 'HMAC-SHA1' (default) or 'RSA-SHA1'.temporary: The temporary credentials (request token) endpoint.Set protocol: 'oauth2' and provide:
auth: The authorization endpoint URI.token: The access token endpoint URI.scope: An array of scope strings or a function returning them.useParamsAuth: Boolean; if true, client ID and secret are sent as parameters instead of an Authorization header (defaults to false).pkce: Set to 'plain' or 'S256' to use proof key exchange.scopeSeparator: The character used to separate scopes (e.g., , for Facebook/GitHub). Defaults to space.For both protocols, you must provide a profile function (ProfileGetter) to normalize user information into the credentials.profile object.
To use Auth0 with Bell, you must provide a domain in the config object. The scope defaults to ['openid', 'email', 'profile'] if not specified.
To target a specific API endpoint for tokens or to authenticate with a specific identity provider (connection), use providerParams and tokenParams.
Profile Structure:
{
"id": "profile.user_id",
"email": "profile.email",
"displayName": "profile.name",
"name": {
"first": "profile.given_name",
"last": "profile.family_name"
},
"raw": "profile"
}// Example: Targeting a specific endpoint and connection
providerParams: {
endpoint: 'https://api.service.com',
connection: 'Username-Password-Authentication'
},
tokenParams: {
endpoint: 'https://api.service.com'
}The Slack provider defaults to the ['identify'] scope.
config.extendedProfile to false if you only require the access_token without user details.team ID in providerParams.Profile Structure:
{
"scope": "params.scope",
"access_token": "params.access_token",
"user": "params.user",
"user_id": "params.user_id"
}// Example: Authenticating for a specific team
providerParams: {
team: 'T0XXXXXX'
}Cognito requires a uri pointing to your Cognito user pool in the config object. The scope defaults to ['openid', 'email', 'profile'].
Profile Structure:
{
"id": "profile.sub",
"username": "profile.preferred_username",
"displayName": "profile.name",
"firstName": "profile.given_name",
"lastName": "profile.family_name",
"email": "profile.email",
"raw": "profile"
}// Example configuration
config: {
uri: 'https://your-cognito-user-pool.amazoncognito.com'
}The Instagram provider defaults to the ['basic'] scope. You can fetch more information by setting extendedProfile: true in the config object.
Profile Structure:
{
"id": "params.user.id",
"username": "params.user.username",
"displayName": "params.user.full_name",
"raw": "params.user"
}// Example: Fetching extended profile
config: {
extendedProfile: true
}The LinkedIn provider defaults to the ['r_basicprofile', 'r_emailaddress'] scope. To request additional profile fields, use the fields option within providerParams.
Profile Structure:
{
"id": "profile.id",
"name": {
"first": "profile.firstName",
"last": "profile.lastName"
},
"email": "profile.email",
"headline": "profile.headline",
"raw": "profile"
}// Example: Requesting specific LinkedIn fields
providerParams: {
fields: ':(id,first-name,last-name,positions,picture-url,picture-urls::(original),email-address)'
}Okta requires a uri pointing to your organization's Okta instance in the config object. If you are using a custom authorization server, you must provide the authorizationServerId in the config.
Profile Structure:
{
"id": "profile.sub",
"username": "profile.email",
"displayName": "profile.nickname",
"firstName": "profile.given_name",
"lastName": "profile.family_name",
"email": "profile.email",
"raw": "profile"
}// Example: Using a custom authorization server
config: {
uri: 'https://your-org.okta.com',
authorizationServerId: 'abc123xyz'
}