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

1. Log into Skycloak and go to your dashboard

2. Click “Create Cluster” - you’ll see the cluster creation form

3. 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)

4. Click “Create Cluster” and wait 2-3 minutes for setup

Note

Free Trial Note: By default, your free trial gives you a managed realm on our Shared Cluster for 21 days — no dedicated cluster to manage, perfect for learning and testing. If you choose the Expert path during onboarding instead, you get a dedicated Small cluster with a 7-day trial.

Access Your Keycloak Console

Once your cluster is ready:

1. Click on your cluster in the dashboard
2. Click “Open Admin Console” - this opens the Keycloak admin interface
3. You are signed in automatically with your Skycloak account via Admin Console SSO, there is no separate admin password to enter

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:

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

Note

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:

1. Go to “Clients” section (left sidebar)

2. Click “Create”

3. Fill in the details:

   • Client ID: “my-web-app”
   • Client Protocol: “openid-connect”
   • Root URL: “http://localhost:8080” (we’ll test locally)

4. Click “Save”

Configure Client Settings:

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

1. Set “Valid Redirect URIs”: http://localhost:8080/*
2. Set “Web Origins”: http://localhost:8080
3. Access Type: “public” (for web apps without server-side secrets)
4. 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:

1. Go to “Users” section (left sidebar)

2. Click “Add user”

3. Fill in:

   • Username: “testuser”
   • Email: “test@example.com”
   • First Name: “Test”
   • Last Name: “User”
   • Email Verified: ON

4. Click “Save”

Set a Password:

1. Go to “Credentials” tab
2. Set Password: “password123”
3. Temporary: OFF (so user doesn’t need to change it)
4. 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

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

Step 7: Understanding What Happened

The Authentication Flow

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

1. Your app redirected you to Keycloak’s login page
2. Keycloak verified your username and password
3. Keycloak created tokens containing your user information
4. Keycloak redirected you back to your app with the tokens
5. 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:

1. Add More Users: Create additional test accounts with different information
2. Customize the Login Page: Learn about branding customization
3. Add User Registration: Enable users to create their own accounts
4. Protect API Endpoints: Learn how to secure backend APIs
5. 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 support@skycloak.io!