Your First Application Setup

This guide walks you through connecting your first application to Skycloak. We’ll create a simple web application that can authenticate users through your Keycloak cluster.

What You’ll Learn

By the end of this tutorial, you’ll have:

A working Keycloak cluster
A configured application client
A simple web page that can log users in and out
Understanding of how authentication flows work

Prerequisites

A Skycloak account (sign up for free at skycloak.io)
Basic knowledge of HTML and JavaScript
A text editor or IDE

Step 1: Create Your Keycloak Instance

Creating the Cluster

Log into Skycloak and go to your dashboard
Click “Create Cluster” - you’ll see the cluster creation form
Choose your settings:
- Name: “My First Cluster” (or whatever you prefer)
- Region: Choose the closest to your users
- Size: Small (perfect for getting started)
- Keycloak Version: Use the latest version (recommended)
Click “Create Cluster” and wait 2-3 minutes for setup

ℹ️

Free Trial Note: Your free trial includes one Small cluster for 7 days. This is perfect for learning and testing!

Access Your Keycloak Console

Once your cluster is ready:

Click on your cluster in the dashboard
Click “Go to Keycloak Console” - this opens the Keycloak admin interface
Log in using the admin credentials shown in Skycloak

What is the Keycloak Console? Think of it as the “control panel” for your authentication system. Here you’ll create realms (like separate “environments”), configure applications, and manage users.

Step 2: Create Your First Realm

A realm is like a separate workspace for your applications. It keeps different projects isolated from each other.

In the Keycloak Console:

Hover over “Master” dropdown (top-left corner)
Click “Add realm”
Name it: “my-app” (use lowercase, no spaces)
Click “Create”

ℹ️

Why create a new realm? The “master” realm is for Keycloak administration. Your applications should use their own realms for security and organization.

Step 3: Create an Application Client

A client represents your application in Keycloak. It defines how your app will communicate with Keycloak.

Configure Your Client:

Go to “Clients” section (left sidebar)
Click “Create”
Fill in the details:
- Client ID: “my-web-app”
- Client Protocol: “openid-connect”
- Root URL: “http://localhost:8080” (we’ll test locally)
Click “Save”

Configure Client Settings:

After creating the client, you’ll see the settings page:

Set “Valid Redirect URIs”: http://localhost:8080/*
Set “Web Origins”: http://localhost:8080
Access Type: “public” (for web apps without server-side secrets)
Click “Save”

What do these settings mean?

Redirect URIs: Where Keycloak can send users after login
Web Origins: Which websites can make requests to Keycloak
Access Type: How secure your client is (public = browser-based)

Step 4: Create a Test User

Let’s create a user account to test with:

Go to “Users” section (left sidebar)
Click “Add user”
Fill in:
- Username: “testuser”
- Email: “[email protected]”
- First Name: “Test”
- Last Name: “User”
- Email Verified: ON
Click “Save”

Set a Password:

Go to “Credentials” tab
Set Password: “password123”
Temporary: OFF (so user doesn’t need to change it)
Click “Set Password”

Step 5: Build Your Web Application

Now let’s create a simple web page that uses Keycloak for authentication.

Create the HTML File

Create a file called index.html:

<!DOCTYPE html>
<html>
<head>
    <title>My First Skycloak App</title>
    <script src="https://cdn.jsdelivr.net/npm/keycloak-js@latest/dist/keycloak.min.js"></script>
    <style>
        body { font-family: Arial, sans-serif; margin: 40px; }
        .container { max-width: 600px; }
        .user-info { background: #f0f0f0; padding: 20px; border-radius: 5px; }
        button { padding: 10px 20px; margin: 10px 0; }
        .login-button { background: #007bff; color: white; border: none; border-radius: 5px; }
        .logout-button { background: #dc3545; color: white; border: none; border-radius: 5px; }
    </style>
</head>
<body>
    <div class="container">
        <h1>Welcome to My App!</h1>
        
        <div id="not-authenticated" style="display: none;">
            <p>Please log in to continue:</p>
            <button class="login-button" onclick="login()">Login</button>
        </div>
        
        <div id="authenticated" style="display: none;">
            <div class="user-info">
                <h3>Hello, <span id="username"></span>!</h3>
                <p><strong>Email:</strong> <span id="email"></span></p>
                <p><strong>Full Name:</strong> <span id="fullName"></span></p>
            </div>
            <button class="logout-button" onclick="logout()">Logout</button>
        </div>
    </div>

    <script>
        // Replace these with your actual values from Skycloak
        const keycloak = new Keycloak({
            url: 'https://your-cluster-url.skycloak.io',  // Your cluster URL
            realm: 'my-app',                              // The realm you created
            clientId: 'my-web-app'                        // The client you created
        });

        // Initialize Keycloak
        keycloak.init({ onLoad: 'check-sso' }).then(function(authenticated) {
            if (authenticated) {
                showUserInfo();
            } else {
                showLoginButton();
            }
        }).catch(function(error) {
            console.error('Failed to initialize Keycloak:', error);
        });

        function login() {
            keycloak.login();
        }

        function logout() {
            keycloak.logout();
        }

        function showLoginButton() {
            document.getElementById('not-authenticated').style.display = 'block';
            document.getElementById('authenticated').style.display = 'none';
        }

        function showUserInfo() {
            document.getElementById('not-authenticated').style.display = 'none';
            document.getElementById('authenticated').style.display = 'block';
            
            // Get user information from the token
            const token = keycloak.tokenParsed;
            document.getElementById('username').textContent = token.preferred_username;
            document.getElementById('email').textContent = token.email || 'Not provided';
            document.getElementById('fullName').textContent = (token.given_name + ' ' + token.family_name) || 'Not provided';
        }
    </script>
</body>
</html>

Update Configuration

Important: Replace your-cluster-url.skycloak.io with your actual cluster URL from the Skycloak dashboard.

Step 6: Test Your Application

Run a Local Server

You can’t just open the HTML file directly - you need a web server. Here are easy options:

Option 1: Python (if you have Python installed)

# Navigate to your folder with index.html
cd /path/to/your/file

# Python 3
python -m http.server 8080

# Python 2
python -m SimpleHTTPServer 8080

Option 2: Node.js (if you have Node.js installed)

# Install a simple server
npm install -g http-server

# Run it
http-server -p 8080

Option 3: PHP (if you have PHP installed)

php -S localhost:8080

Test the Login Flow

Open your browser and go to http://localhost:8080
Click “Login” - you should be redirected to Keycloak
Enter your test credentials:
- Username: testuser
- Password: password123
You should be redirected back to your app and see your user information
Click “Logout” to test the logout flow

Step 7: Understanding What Happened

The Authentication Flow

When you clicked “Login”, here’s what happened:

Your app redirected you to Keycloak’s login page
Keycloak verified your username and password
Keycloak created tokens containing your user information
Keycloak redirected you back to your app with the tokens
Your app verified the tokens and logged you in

The Tokens

Keycloak gives your app three types of tokens:

Access Token: Proves you’re authenticated (like a temporary ID card)
ID Token: Contains your basic profile information
Refresh Token: Lets your app get new tokens when they expire

Next Steps

Congratulations! You’ve successfully: ✅ Created a Keycloak cluster ✅ Configured a realm and client ✅ Built a working authentication flow ✅ Tested login and logout

What to Try Next:

Add More Users: Create additional test accounts with different information
Customize the Login Page: Learn about branding customization
Add User Registration: Enable users to create their own accounts
Protect API Endpoints: Learn how to secure backend APIs
Add Social Login: Connect Google, GitHub, or other social providers

Common Next Steps:

For React Apps: Check out our React integration guide
For Backend APIs: Learn about JWT validation
For Production: Review our cluster management

Getting Help

Stuck on something? Check our FAQs
Need more features? Explore our extensions marketplace
Want to customize the look? See our branding guide

Troubleshooting

Common Issues

“Invalid redirect URI” error:

Check that your Redirect URIs in the client settings include http://localhost:8080/*

Login page doesn’t load:

Verify your cluster URL is correct
Make sure your cluster is running (check the Skycloak dashboard)

Can’t log in with test user:

Verify the username and password are correct
Check that the user is in the correct realm

CORS errors in browser console:

Make sure Web Origins includes http://localhost:8080
Check that you’re accessing the app via http://localhost:8080, not file://

Need more help? Contact our support team at [email protected]!

Understanding Keycloak Basics