Understanding Keycloak Basics
Keycloak can seem complex at first, but once you understand the basic concepts, everything else makes sense. This guide explains Keycloak’s key concepts in simple terms with real-world examples.
What is Keycloak?
Think of Keycloak as a security guard for your applications. Instead of every app needing its own login system, Keycloak handles all the authentication and user management in one place.
Real-world analogy: Like a hotel reception desk that checks guests in once, then gives them a key card that works for their room, the gym, and the restaurant - without having to check ID again at each location.
Core Concepts
1. Realms
A realm is like a separate building with its own set of users, applications, and security rules.
Examples:
- Company realm: For your company’s internal applications
- Customer realm: For your customer-facing applications
- Development realm: For testing and development
Why use multiple realms?
- Keep different projects completely separate
- Different security requirements (internal vs external users)
- Easy to manage permissions and settings independently
2. Users
Users are people who can log into your applications. Each user has:
- Username: How they identify themselves
- Password: How they prove who they are
- Profile information: Name, email, phone number, etc.
- Attributes: Custom information you want to store
User lifecycle:
- Registration: User creates an account (or admin creates it)
- Verification: Email verification (optional but recommended)
- Authentication: User logs in with username/password
- Profile management: User can update their information
3. Clients
A client represents an application that wants to use Keycloak for authentication.
Types of clients:
- Web applications: Your website or web app
- Mobile apps: iOS or Android applications
- APIs: Backend services that need to verify tokens
- Desktop applications: Native desktop software
Client configuration includes:
- Where to redirect after login/logout
- What information the app can access
- How secure the communication should be
4. Roles
Roles define what users can do in your applications.
Examples:
- admin: Can manage everything
- editor: Can create and edit content
- viewer: Can only view content
- customer: Can access customer features
Two types of roles:
- Realm roles: Apply across all applications in the realm
- Client roles: Specific to one application
5. Groups
Groups are collections of users that share the same roles or attributes.
Examples:
- HR Department: Access to HR applications
- Premium Customers: Access to premium features
- Beta Testers: Access to new features
Benefits:
- Easier to manage many users
- Assign roles to groups instead of individual users
- Automatically apply rules to new group members
Authentication Flows
What Happens When a User Logs In?
Let’s follow Sarah through a typical login:
-
Sarah visits your app at
myapp.com - App says “Please log in” and redirects her to Keycloak
- Sarah enters username/password on Keycloak’s login page
- Keycloak verifies her credentials
- Keycloak creates tokens with her information and permissions
- Keycloak redirects Sarah back to your app with the tokens
- Your app verifies the tokens and logs her in
- Sarah can now use your app - she’s authenticated!
Types of Authentication
Username/Password (Basic)
- Most common method
- User enters credentials
- Can add requirements like password complexity
Multi-Factor Authentication (MFA)
- Password + something else (like a phone app code)
- Much more secure
- Required for sensitive applications
Social Login
- Login with Google, Facebook, GitHub, etc.
- Users don’t need to create new accounts
- Faster and more convenient
Single Sign-On (SSO)
- Log in once, access multiple applications
- Like using your Google account for Gmail, Drive, and YouTube
- Great user experience
Tokens Explained Simply
When Keycloak authenticates a user, it creates tokens - think of them as temporary digital ID cards.
Types of Tokens
Access Token
- What it is: Proof that the user is logged in
- Like: A wristband at an event that shows you paid admission
- Used for: Accessing protected features in your app
- Expires: Usually after 15-30 minutes (configurable)
ID Token
- What it is: Contains the user’s basic information
- Like: A driver’s license with name, photo, and details
- Contains: Username, email, name, roles, etc.
- Used for: Displaying user information in your app
Refresh Token
- What it is: A way to get new access tokens
- Like: A membership card that lets you get new day passes
- Used for: Keeping users logged in without re-entering passwords
- Expires: Much longer (days or weeks)
Why Do Tokens Expire?
Security: If someone steals a token, it’s only useful for a short time Performance: Forces apps to get fresh user information periodically Control: Admins can revoke access by not issuing new tokens
Common Keycloak Features
User Self-Service
Account Console: Users can:
- Update their profile information
- Change their password
- Enable two-factor authentication
- View their login history
- Manage connected applications
Password Reset: Users can:
- Reset forgotten passwords via email
- Set security questions (optional)
- Use temporary passwords from admins
Social Identity Providers
Connect popular services so users can log in with existing accounts:
- Google: Most popular for consumer applications
- Microsoft: Great for business applications
- GitHub: Perfect for developer tools
- Facebook, Twitter, LinkedIn: For social applications
User Federation
Connect to existing user databases:
- Active Directory: For Windows-based companies
- LDAP: For enterprise directory services
- Custom databases: Via custom connectors
Security Features
Protection Against Attacks
Brute Force Protection
- Temporarily locks accounts after too many failed login attempts
- Prevents automated password guessing attacks
Session Management
- Automatic logout after inactivity
- Detects suspicious login patterns
- Can require re-authentication for sensitive actions
HTTPS Enforcement
- All communication encrypted
- Prevents password interception
- Required for production use
Compliance Features
Event Logging
- Records all user actions
- Required for many compliance standards
- Helps with security investigations
Privacy Controls
- GDPR compliance features
- User consent management
- Data retention policies
Real-World Examples
Example 1: E-commerce Site
Setup:
- Realm: “shopwell-customers”
- Users: Your customers
-
Clients:
- Website (web application)
- Mobile app (public client)
- Admin panel (confidential client)
- Roles: customer, vip-customer, admin
Flow:
- Customer visits your website
- Clicks “Log In”
- Redirected to Keycloak login page
- Enters email/password
- Keycloak redirects back with tokens
- Website shows personalized experience based on customer role
Example 2: Company Internal Apps
Setup:
- Realm: “acme-corp”
- Users: Employees (imported from Active Directory)
-
Clients:
- HR system
- Project management tool
- Time tracking application
- Groups: HR-Department, Engineering, Sales
- Roles: employee, manager, hr-admin
Flow:
- Employee logs into any company application
- Gets redirected to company Keycloak instance
- Enters company credentials
- Can now access ALL company applications without logging in again (SSO)
Example 3: SaaS Platform
Setup:
- Realm: “platform-users”
- Users: Various customers and their teams
- Clients: Main application, API, mobile app
- Roles: free-user, pro-user, admin, team-member
- Groups: Organizations (each customer company)
Flow:
- User signs up for your SaaS platform
- Email verification required
- User logs in and sees features based on their subscription level
- Team members can be invited and inherit organization permissions
Best Practices for Beginners
Realm Organization
Start Simple:
- One realm for your main application
- Add more realms as you add more projects
- Don’t over-complicate initially
Naming Convention:
- Use descriptive names: “customer-portal” not “realm1”
- Use lowercase and hyphens
- Be consistent across your organization
User Management
Required Fields:
- Always require email addresses
- Consider requiring email verification
- Set up password policies appropriate for your users
User Registration:
- Enable self-registration for customer-facing apps
- Use admin-only registration for internal apps
- Consider using social login to reduce friction
Security Settings
Development vs Production:
- Relaxed settings for development/testing
- Strict security settings for production
- Never use development settings in production
Password Policies:
- Minimum 8 characters for most applications
- Require special characters for sensitive applications
- Consider your users’ context (internal vs customer-facing)
Next Steps
Now that you understand the basics:
- Try it yourself: Set up your first application
- Learn about roles: User management and roles
- Customize the experience: Branding and customization
- Add security: Enable multi-factor authentication
Common Questions
“Do I need separate realms for development and production?”
Yes! Always separate development and production environments. This prevents test data from mixing with real user data and allows you to test changes safely.
“Should I use social login?”
For customer-facing applications, social login usually improves user experience and increases conversion rates. For internal business applications, consider your company’s security policies.
“How many roles should I create?”
Start with the minimum you need (usually 2-4 roles). You can always add more later. Too many roles become hard to manage.
“What if users forget their passwords?”
Keycloak has built-in password reset features. Users can reset passwords via email, and admins can generate temporary passwords.
“Is Keycloak secure enough for production?”
Yes! Keycloak is used by thousands of companies worldwide and includes enterprise-grade security features. Just make sure to follow security best practices and keep it updated.
Remember: Start simple and add complexity as you need it. Keycloak is very powerful, but you don’t need to use every feature right away!