Login and Logout

The Agglestone Authentication and User Management Service provides standard OAuth2 and OpenID Connect flows for user authentication. This guide explains how login and logout work in your application.

Login Flow

The login process uses the OAuth2 authorization code flow with PKCE (Proof Key for Code Exchange) for enhanced security. When integrated with a standard OAuth2/OIDC client library, the entire flow is handled automatically.

Don’t have your Tenant ID yet? Log into your account at https://portal.agglestone.com to find your Tenant ID. Then replace {tenantId} or your-tenant-id in the examples below with your own Tenant ID.

Using a Client Library

The easiest way to implement login is to use a standard OAuth2/OIDC client library like oidc-client-ts@^3.4.1 for TypeScript/JavaScript applications. The library handles PKCE generation, discovery endpoint configuration, token storage, and automatic token refresh.

import { UserManager, WebStorageStateStore } from 'oidc-client-ts';

const tenantId = 'your-tenant-id'; // Get from https://portal.agglestone.com
const userManager = new UserManager({
  authority: 'https://auth.agglestone.com/tenant/' + tenantId + '/v2.0/Auth',
  client_id: tenantId,
  redirect_uri: 'https://yourapp.com/callback',
  response_type: 'code',
  scope: 'openid profile email',
  automaticSilentRenew: true,
  userStore: new WebStorageStateStore({ store: window.localStorage })
});

// Login button handler
async function handleLogin() {
  await userManager.signinRedirect();
}

What Happens During Login

When a user clicks the login button in your application:

1. Discovery and Configuration: When signinRedirect() is called, the oidc-client library automatically retrieves the OpenID Connect discovery document from https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/.well-known/openid-configuration to self-configure with the correct authorization, token, and other endpoint URLs. This discovery metadata is typically cached after the first call to improve performance.
2. Redirect to Login Page: The user’s browser is redirected to the Agglestone Authentication and User Management Service secure login page at https://auth.agglestone.com/tenant/{tenantId}/v2.0/Auth/authorize.
3. User Authentication: The user enters their username and password on the secure login page.
4. Password Reset Check: If the user is required to reset their password (configured in the Agglestone Portal), they’ll be prompted to set a new password before proceeding.
5. Multi-Factor Authentication Check: If MFA is enabled for the user, they’ll be prompted to set up MFA by scanning a QR code with their authenticator app if they haven’t already done so, or to enter their authenticator code if their MFA is already configured.
6. Authorization Code Exchange: Once authentication is complete, the service redirects the user back to your redirect_uri with an authorization code. Your client library automatically exchanges this authorization code for tokens at the token endpoint.
7. Token Storage: The client library receives and stores the following tokens:
   • Access Token (JWT) – Used to authenticate API requests
   • Refresh Token – Used to obtain new access tokens when they expire
   • ID Token (JWT) – Contains user identity information (if openid scope is requested)
8. User Returns to Your App: The user is now authenticated and returned to your application. You can use the access token to make authenticated API calls on their behalf.

All of this happens automatically when you use a standard OAuth2/OIDC client library. The library handles the redirects, code exchange, and token storage for you.

Logout Flow

Logging out a user revokes all their refresh tokens, effectively signing them out on all devices. The logout endpoint follows the OpenID Connect End Session specification.

Using a Client Library

When using oidc-client-ts, logout is handled automatically:

// Logout button handler
async function handleLogout() {
  await userManager.signoutRedirect({
    post_logout_redirect_uri: 'https://yourapp.com'
  });
}

The client library will:

1. Call the logout endpoint to revoke all refresh tokens
2. Clear stored tokens from localStorage/sessionStorage
3. Redirect the user to your specified post-logout redirect URI

What Happens During Logout

When a user logs out:

1. Token Revocation: All refresh tokens for that user are revoked, signing them out on all devices
2. Session Cleanup: The user’s session is ended on the authentication service
3. Redirect: If a post_logout_redirect_uri is provided, the user is redirected back to your application

After logout, the user will need to log in again to access protected resources. Any stored tokens in your application should also be cleared.

> 📚 API Documentation: For detailed API documentation, request/response schemas, and to try out the endpoints interactively, visit the Swagger UI.

—

Ready to learn more? Check out the Quick Start Guide for a complete integration example, or learn about Password Management and Multi-Factor Authentication.