Authentication

Agentlet includes an optional, popup-based authentication system that integrates with the agentlet panel. It supports OIDC, OAuth2, and custom identity providers through a configurable popup flow and token extraction.

Basic configuration

const agentlet = new AgentletCore({
    auth: {
        enabled: true,
        buttonText: 'Login',
        loginUrl: 'https://your-idp.com/auth',
        popupWidth: 400,
        popupHeight: 600,
        allowedOrigins: ['https://your-idp.com'],

        onSuccess: (result) => {
            console.log('Authentication successful', result);
        },
        onError: (result) => {
            console.error('Authentication failed', result.error);
        },
        onCancel: (result) => {
            console.log('Authentication cancelled', result);
        },
    },
});

onSuccess receives an AuthResult: { success: true, token, timestamp, userInfo }, plus any extra fields the token extractor or message handler attached.

Custom token extraction

For identity providers that return the token in a non-standard location (URL hash, query string, custom message body), provide a tokenExtractor:

tokenExtractor: (raw) => {
    if (raw.includes('#access_token=')) {
        const match = raw.match(/access_token=([^&]+)/);
        return match ? match[1] : null;
    }
    return null;
};

Custom message handling

For flows that need full control over the popup’s postMessage payload, provide a messageHandler. It receives the raw message data and the AuthManager instance, and returns a result object (or null/undefined to let the default handling continue):

messageHandler: (data, manager) => {
    if (data.type === 'ENTERPRISE_AUTH_SUCCESS') {
        return { success: true, accessToken: data.accessToken, userInfo: data.user };
    }
    if (data.type === 'ENTERPRISE_AUTH_ERROR') {
        return { success: false, error: data.message };
    }
    return null;
};

Programmatic control

const auth = window.agentlet.auth;

if (auth.isEnabled()) {
    await auth.startAuthentication();
}

const state = auth.getState();
// { enabled, authenticating, popupOpen }

await auth.logout();

auth.updateConfig({ buttonText: 'New login text', loginUrl: 'https://new-idp.com/auth' });

isEnabled() and AuthState.enabled are not strict booleans: they return the configured loginUrl string when authentication is enabled and a login URL is set, not literal true.

Identity provider examples

Auth0

const auth0Config = {
    auth: {
        enabled: true,
        buttonText: 'Login with Auth0',
        loginUrl:
            'https://your-domain.auth0.com/authorize?response_type=token&client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&scope=openid profile email',
        popupWidth: 500,
        popupHeight: 700,
        allowedOrigins: ['https://your-domain.auth0.com'],
        tokenExtractor: (raw) => {
            const match = raw.match(/access_token=([^&]+)/);
            return match ? match[1] : null;
        },
        onSuccess: (result) => {
            localStorage.setItem('auth0_token', result.token);
        },
    },
};

Google OAuth

const googleConfig = {
    auth: {
        enabled: true,
        buttonText: 'Sign in with Google',
        loginUrl:
            'https://accounts.google.com/oauth/v2/auth?client_id=YOUR_GOOGLE_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=openid email profile',
        popupWidth: 500,
        popupHeight: 600,
        allowedOrigins: ['https://accounts.google.com'],
        tokenExtractor: (raw) => {
            const match = raw.match(/code=([^&]+)/);
            return match ? match[1] : null;
        },
        onSuccess: async (result) => {
            const tokenResponse = await exchangeCodeForToken(result.token);
            localStorage.setItem('google_token', tokenResponse.access_token);
        },
    },
};

Security considerations

• Since agentlet-core 2.3.0, the manager only accepts messages posted by the login popup it opened (event.source must be that popup). Messages from any other window or frame on the page are ignored, even from an allowed origin. Earlier versions accepted a message from any window, and from any origin when allowedOrigins was empty.
• Set allowedOrigins to the origin of the page that posts the result, usually your callback page or the identity provider. When the list is empty, a warning is logged in the console.
• The message payload carries the token, so it is never logged, even in debug mode.
• Validate tokens on your backend before trusting them.
• Prefer HTTPS-only storage for tokens returned by onSuccess.

Troubleshooting

• Popup blocked: ensure popups are allowed for your domain.
• CORS issues: configure proper CORS headers on your identity provider.
• Message not received: the result must be posted from the popup window itself, with window.opener.postMessage(...), not from a frame inside it. Its origin must also be listed in allowedOrigins when that list is set.
• Token extraction failed: verify the tokenExtractor function against the actual popup payload.

Inspect the current auth configuration and state from the console:

window.agentlet.auth.getState();
window.agentlet.debug?.getConfig().auth; // Only when the core was constructed with debugMode: true