Agglestone Labs

Quick Start

Get started with authentication in minutes, with Agglestone's Authentication and User Management Service. Configure your OAuth2 ^{(RFC 6749)} client and add a login button to your application.

Robust Authentication & User Management

Our service provides everything you need for secure user authentication and management. Built on industry-standard protocols and designed for modern applications.

Secure by Default

Security is built into every aspect of our authentication service. We follow industry best practices and implement the latest security standards.

PKCE (Proof Key for Code Exchange) ^{(RFC 7636)}

PKCE is enabled by default for all authorization flows, providing an additional layer of security against authorization code interception attacks. This is especially important for public clients and mobile applications.

Short-Lived Access Tokens

Access tokens are designed to be short-lived, minimizing the window of opportunity for attackers if a token is compromised. Tokens automatically expire, and refresh tokens are used to obtain new access tokens seamlessly.

Cryptographically Signed JWTs ^{(RFC 7519)}

All tokens issued by the service are JSON Web Tokens (JWTs) ^{(RFC 7519)} that are cryptographically signed. Each tenant has its own signing authority with dedicated cryptographic keys, ensuring complete tenant isolation and independent key management.

Benefits of Per-Tenant Signing Authority

• Complete Tenant Isolation: Tokens from one tenant cannot be validated using another tenant's keys, providing cryptographic separation between tenants
• Independent Key Management: Each tenant can rotate their signing keys independently without affecting other tenants
• Enhanced Security: Compromise of one tenant's keys does not impact the security of other tenants
• Compliance & Data Residency: Supports data residency requirements by allowing tenant-specific key storage and management
• Performance: Resource servers can verify token authenticity using the tenant's public keys without contacting the authorization server for every request
• Scalability: Key management operations are scoped per tenant, allowing for efficient scaling and maintenance

Public keys for token verification are available through the JWKS endpoint (RFC ⁷⁵¹⁷), which is tenant-specific and automatically included in the OpenID Connect discovery document.

Time-Based One-Time Passwords (TOTP) ^{(RFC 6238)}

Multi-factor authentication is supported through TOTP ^{(RFC 6238)}, compatible with standard authenticator apps like Google Authenticator, Microsoft Authenticator, and Authy. MFA can be enforced on a user-by-user basis.

Automatic Discovery & Configuration

Simplify your integration with automatic discovery through the .well-known endpoint ^{(RFC 8414)}. Industry-standard libraries can automatically configure themselves using the OpenID Connect Discovery specification.

Simply point your OAuth2 ^{(RFC 6749)} or OpenID Connect client library to:

The discovery endpoint provides all necessary configuration including authorization endpoints, token endpoints, supported scopes, supported response types, and public key information (JWKS) ^{(RFC 7517)} for token verification.

Multi-Factor Authentication (MFA / 2FA)

Enable MFA / 2FA for your users to enhance security. Users can setup by scanning QR Code with their favourite authenticator app. Alternatively, you can choose to enable email delivery of time-based, one-time codes.

Use the admin portal to easily reset the user to use a different MFA method or disable MFA if needed.

Self-Service Password Reset

Users can securely reset their passwords without requiring administrator intervention. The password reset flow uses secure, time-limited tokens sent via email.

When a user requests a password reset:

• A secure reset token is generated and sent to the user's registered email address
• The token expires after a configurable time period (typically 1 hour)
• Users are redirected to a customizable password reset page
• After successful reset, all active sessions can be optionally invalidated for security

The password reset pages are fully customizable with HTML and CSS, allowing you to maintain your brand identity throughout the user experience.

Highly Customizable Authentication Pages

Make the authentication experience feel seamlessly integrated with your application. All authentication pages can be customized using HTML and CSS.

Customizable Pages

• Login Page: Customize the login form with your branding, colors, and layout
• Password Reset: Match your brand on the password reset request and confirmation pages
• MFA/2FA Screen: Customize the multi-factor authentication verification interface
• Email Verification: Brand the email verification and account activation screens

Upload your HTML templates and CSS files, and the service will render them with the appropriate authentication forms and validation. This ensures a consistent user experience that feels like a native part of your application.

Intelligent Session Management

Advanced refresh token management with IP address awareness provides both security and user convenience.

Refresh Token Timelines

Refresh tokens have configurable expiration times and can be set to rotate on each use for enhanced security. The service supports both sliding expiration (extend on use) and fixed expiration policies.

IP Address Awareness

Configure how the service handles refresh token usage from different IP addresses:

• Strict Mode: Require full login when a refresh token is used from a different IP address to initial login
• Flexible Mode: Allow silent refresh if the IP address has been seen before for that user
• IP Whitelisting: Optionally maintain a list of trusted IP addresses for automatic approval

This balance between security and user experience ensures that legitimate users aren't unnecessarily challenged while protecting against token theft and unauthorized access.

Flexible Username Configuration

Support different authentication models to match your application's requirements.

Email as Username

Users can authenticate using their email address as their username. This is the most common pattern for modern web applications and provides a familiar experience for users.

Distinct Usernames

Alternatively, configure the service to require distinct usernames separate from email addresses. This allows for more traditional authentication models or applications where users may have multiple email addresses.

Username configuration is set per tenant, allowing different applications or organizations to use the authentication model that best fits their needs.

Request Validation & Allowed Origins

Protect your authentication endpoints with comprehensive request validation and origin checking.

Allowed Origins

Configure a whitelist of allowed origins for authorization requests. This prevents unauthorized applications from attempting to use your authentication service and protects against certain types of attacks.

Request Validation

All authentication requests are validated for:

• Valid client credentials and redirect URIs
• Proper request signatures and PKCE parameters
• Origin and referrer header validation
• Rate limiting to prevent abuse
• CSRF protection on state parameters

These validations ensure that only legitimate, authorized applications can initiate authentication flows and obtain tokens.

Easy Migration Paths

Migrating from another authentication system doesn't have to be disruptive. Our service supports incremental adoption and provides tools to make the transition smooth.

Incremental Adoption

You don't need to migrate all users at once. The service supports running alongside existing authentication systems, allowing you to migrate users gradually or support both systems during a transition period.

User Import & Mapping

Import existing users from your current authentication system with support for:

• Bulk user import via API
• User attribute mapping and transformation
• Group and role migration

Compatibility Modes

Make your authentication standards compatible with existing systems by:

• Supporting legacy token formats alongside modern JWTs
• Providing compatibility endpoints that match your old system's API
• Configuring scopes and claims to match existing expectations
• Maintaining backward compatibility during the transition

This approach minimizes disruption to your existing applications and users while you transition to a more modern, secure authentication system.

API Keys for Server-to-Server Auth

Perfect for background services, scheduled jobs, and automated processes. API keys provide long-lived credentials for server-to-server communication without the complexity of token refresh.

Primary and Secondary Keys

Each tenant has both primary and secondary API keys, allowing for zero-downtime key rotation. Generate a new key while keeping the old one active, then switch over when ready.

Key Rotation

When you generate a new primary or secondary key, the previous key of the same type is automatically invalidated. This ensures secure key rotation without service interruption.

Token Exchange

Exchange your API key for a JWT token when you need to make requests on behalf of a specific user. This is useful for server-side operations that require user context.

Usage

Simply include your API key in the X-API-Key header for all API requests. No token refresh needed—use the same key until you rotate it.

User & Group Management APIs

Full Create, Read, Update, and Delete (CRUD) operations for users and groups with pagination, filtering, and role-based access control. Manage your user base programmatically through REST APIs.

Build Your Own Admin Interface

With comprehensive REST APIs, you can build user management directly into your own applications. Your admins can view users, reset passwords, manage groups, and perform all administrative tasks from within your application—no need to log into the Agglestone Portal. This provides a seamless experience for your team and keeps all management tools in one place.

User Management

Complete user lifecycle management:

• Create Users: Create new user accounts with email, display name, password, and user type
• List Users: Paginated user listing with configurable page size (up to 100 per page)
• Get User: Retrieve detailed user information by user ID
• Update User: Update email, display name, password, enabled status, and group membership
• Delete User: Remove users from your tenant (with safety checks)

Group Management

Organize users into groups for access control:

• Create Groups: Create new groups with name and description
• List Groups: Paginated group listing
• Get Group: Retrieve group details including member count
• Update Group: Modify group name and description
• Delete Group: Remove groups (users remain, just lose group membership)

Role-Based Access Control

Users can belong to multiple groups. The default "Tenant Administrators" group provides full access to user and group management, API key management, and administrative privileges. Control access to your APIs based on group membership in JWT tokens.

Pagination

All list endpoints support pagination with configurable page size. Efficiently manage large user bases without loading everything at once.

Token Introspection & Revocation

OAuth2-compliant endpoints ^{(RFC 7662, RFC 7009)} for token management. Verify token validity, check token metadata, and revoke tokens when needed.

Token Introspection ^{(RFC 7662)}

The introspection endpoint allows you to verify whether a token is valid and retrieve its metadata without decoding the JWT. This is useful for resource servers that need to validate tokens.

Introspection provides information about:

• Token validity (active/inactive)
• Token expiration time
• User ID and tenant ID
• Scopes and claims
• Token type (access token or refresh token)

Token Revocation ^{(RFC 7009)}

Revoke access tokens or refresh tokens when they're no longer needed or have been compromised. The revocation endpoint supports both access tokens and refresh tokens.

Bulk Token Revocation

Revoke all refresh tokens for a specific user across all devices. This is useful when a user reports a lost device or when you need to force a user to re-authenticate.

Security Benefits

Token introspection and revocation are essential for:

• Validating tokens at resource servers
• Implementing logout functionality
• Responding to security incidents
• Managing user sessions across multiple devices
• Complying with security policies and regulations

Backend for Frontend (BFF) Pattern

Keep your frontend simple and secure with the Backend-for-Frontend pattern. Your backend handles all OAuth2/OIDC complexity while your frontend uses simple session-based authentication.

Security Benefits

• No tokens in the browser: Access tokens never leave your backend, reducing XSS attack surface
• Secure refresh token storage: Refresh tokens stored in httpOnly cookies on your backend
• Better token management: Centralized token refresh logic in your backend
• Reduced complexity: Frontend doesn't need to handle OAuth2 flows or token refresh

How It Works

Your backend acts as a secure proxy between your frontend and the authentication service:

1. User clicks "Login" in your frontend
2. Frontend redirects to your backend's login endpoint
3. Backend initiates OAuth2 flow with the authentication service
4. User authenticates and is redirected back to your backend
5. Backend exchanges authorization code for tokens
6. Backend stores tokens securely and creates a session
7. Frontend uses standard session cookies for subsequent requests

Developer Experience

The BFF pattern simplifies frontend development:

• No OAuth2/OIDC libraries needed in your frontend
• Standard HTTP session management
• Easier debugging with all auth logic in one place
• Better error handling and centralized logging
• Can proxy requests to multiple backend services

When to Use BFF

The BFF pattern is ideal for:

• Traditional web applications with server-side rendering
• Applications requiring maximum security (no tokens in browser)
• Teams that want to keep frontend code simple
• Applications that need to proxy requests to multiple services
• Scenarios where you want centralized rate limiting and caching

Multi-Tenant Architecture

Built from the ground up for multi-tenancy. Every request is tenant-scoped, ensuring complete data isolation and security between tenants.

Tenant Isolation

All data, users, groups, and configurations are isolated per tenant. Users from one tenant cannot access data from another tenant, even with valid credentials.

URL Structure

Every API request includes the tenant ID in the URL path:

Tenant Validation

The service validates that:

• Tokens belong to the tenant specified in the URL
• API keys belong to the tenant making the request
• Users can only access resources within their tenant
• Groups are scoped to a single tenant

Benefits

• Complete isolation: Each tenant's data is completely separate
• Scalability: Support unlimited tenants on a single infrastructure
• Customization: Each tenant can have different authentication settings
• Security: Tenant ID validation on every request prevents cross-tenant access
• Flexibility: Different tenants can use different authentication models (email-as-username vs distinct usernames)

Login History & Audit Trails

Comprehensive tracking of all login attempts with detailed audit information. Monitor user access patterns and enhance security with complete visibility into authentication events.

What's Tracked

Every login attempt is recorded with:

• IP Address: The IP address from which the login attempt originated
• Timestamp: Exact time of the login attempt
• User ID: The user attempting to authenticate
• Success/Failure: Whether the login attempt was successful
• User Agent: Browser or client information

Security Benefits

Login history provides:

• Audit trails: Complete record of all authentication events for compliance
• Anomaly detection: Identify unusual login patterns or potential security threats
• Forensics: Investigate security incidents with detailed access logs
• User monitoring: Track user access patterns and behavior
• Compliance: Meet regulatory requirements for authentication logging

Integration with Session Management

Login history seamlessly integrates with refresh token management. When a refresh token is used, the service checks the IP address against the user's login history to determine whether to allow silent refresh or require full re-authentication.

Standards & Specifications

Our authentication service implements industry-standard protocols and specifications. For detailed technical information, refer to the following RFC documents:

Additionally, our service implements the OpenID Connect Core 1.0 specification for identity layer functionality on top of OAuth 2.0.