Skip to main content

Key Concepts

Guardhouse is built around several core concepts that work together to provide a complete identity and access management solution.

Tenants (Organizations)​

A tenant (also called an organization) represents an isolated environment for your applications and users.

What is a Tenant?​

  • An isolated container for applications, users, and configurations
  • Each tenant has its own domain, branding, and settings
  • Users and applications are scoped to a specific tenant
  • Complete data isolation between tenants

Use Cases​

  • Multi-tenant SaaS applications: Each customer gets their own tenant
  • Enterprise organizations: Single tenant for internal applications
  • White-label solutions: Each brand or customer gets a separate tenant

Tenant Properties​

  • Domain: Custom domain (e.g., auth.yourcompany.com)
  • Branding: Logo, colors, email templates
  • Settings: Security policies, session management, MFA requirements
  • Users: User accounts specific to the tenant
  • Applications: Clients and APIs registered under the tenant

Clients (Applications)​

A client (or application) is any software that requests authentication or authorization from Guardhouse.

Client Types​

1. Regular Web Applications​

Server-side rendered applications where the source code is not publicly accessible.

  • Characteristics: Can securely store secrets
  • Examples: ASP.NET MVC, Django, Ruby on Rails applications
  • Token Storage: Server-side session or cookies
  • Recommended Flow: Authorization Code Flow with PKCE

2. Single-Page Applications (SPA)​

JavaScript applications running in the browser where the source code is public.

  • Characteristics: Cannot securely store secrets
  • Examples: React, Vue, Angular applications
  • Token Storage: In-memory or httpOnly cookies
  • Recommended Flow: Authorization Code Flow with PKCE

3. Native/Mobile Applications​

Applications installed on devices (iOS, Android, Desktop).

  • Characteristics: Code can be decompiled, secrets not fully secure
  • Examples: iOS apps, Android apps, Electron applications
  • Token Storage: Secure keychain/keystore
  • Recommended Flow: Authorization Code Flow with PKCE

4. Machine-to-Machine (M2M) Applications​

Background services or daemons without user interaction.

  • Characteristics: No user interface, automated access
  • Examples: Cron jobs, microservices, CI/CD pipelines
  • Authentication: Client Credentials Flow
  • Token: Access token only (no ID token or refresh token)

Client Configuration​

Each client has essential configuration settings:

  • Client ID: Public identifier for your application
  • Client Secret: Confidential secret (for regular web apps and M2M)
  • Callback URLs: URLs where Guardhouse redirects after authentication
  • Logout URLs: URLs where users are redirected after logout
  • Allowed Origins: CORS origins for SPAs
  • Token Settings: Token lifetimes, token types, encryption

Resources (APIs)​

A resource (or API) represents a protected API that requires authentication and authorization.

What is a Resource?​

  • An API endpoint or service that requires authenticated requests
  • Defines the scopes and permissions available
  • Controls which clients can access the API
  • Enables fine-grained authorization control

Scopes​

Scopes are permissions that define what access a client can request.

Example Scopes:

read:users      - Read user information
write:users     - Create or update users
delete:users    - Delete users
admin:users     - Full administrative access

Resource Registration​

When registering a resource:

  1. Define the Resource: Give your API a name and identifier
  2. Configure Scopes: Add the scopes your API supports
  3. Set Access Control: Specify which clients can access the resource
  4. Token Validation: Configure how tokens are validated (audience, issuer)

Accessing Protected Resources​

Clients request specific scopes during authentication:

# Authorization URL with scopes
GET /authorize?
  response_type=code
  &client_id=your_client_id
  &redirect_uri=https://app.example.com/callback
  &scope=read:users write:users
  &state=random_state_value

The resulting access token will include the granted scopes:

{
  "scope": "read:users write:users",
  "permissions": ["read:users", "write:users"]
}

Users​

Users are the individuals who authenticate through Guardhouse.

User Profile​

Each user has a profile containing:

  • Basic Information: Name, email, phone
  • User Attributes: Custom attributes defined by your tenant
  • Authentication Methods: Password, social providers, MFA
  • Role: Assigned role for authorization

User Authentication Flow​

User → Guardhouse Login → Authentication → Identity Provider
                                    ↓
                            Token Issuance
                                    ↓
                            Access Token + ID Token

User Sources​

  • Database: Users stored in Guardhouse's database
  • Social Providers: Google, GitHub, Microsoft, etc.
  • Enterprise Providers: Active Directory, LDAP, SAML
  • External Identity Providers: Custom OIDC providers

Roles & Permissions​

Guardhouse implements Role-Based Access Control (RBAC) for fine-grained authorization.

Roles​

A role is a collection of permissions assigned to users.

Example Roles:

  • admin - Full administrative access
  • moderator - Limited administrative access
  • user - Standard user access
  • guest - Restricted access

Permissions​

Permissions define specific actions users can perform.

Example Permissions:

  • users:read - Read user data
  • users:write - Create/update users
  • users:delete - Delete users
  • settings:manage - Manage settings

Role Assignment​

Users can be assigned one or more roles:

// Example: User with multiple roles
{
  "user_id": "usr_123456789",
  "email": "user@example.com",
  "roles": ["user", "moderator"],
  "permissions": [
    "users:read",
    "posts:read",
    "posts:write",
    "moderate:content"
  ]
}

Connections​

Connections are identity providers that Guardhouse uses to authenticate users.

Connection Types​

  1. Database: Username/password authentication
  2. Social: OAuth 2.0/OIDC social providers (Google, Facebook, GitHub)
  3. Enterprise: SAML, LDAP, Active Directory
  4. Passwordless: Email magic links, SMS OTP

Connection Configuration​

Each connection can be configured with:

  • Display name and icon
  • Authentication settings
  • User profile mapping
  • Custom claims and attributes

Relationships​

Tenant (Organization)
  ├── Users
  ├── Roles
  ├── Clients (Applications)
  │   ├── Regular Web Apps
  │   ├── SPAs
  │   ├── Native Apps
  │   └── M2M Apps
  ├── Resources (APIs)
  │   └── Scopes
  └── Connections
      ├── Database
      ├── Social Providers
      └── Enterprise Providers

Next Steps​