Features
Application Management

Application Management

Applications

Skycloak’s Application Management system provides intelligent guidance and streamlined workflows for integrating your applications with Keycloak authentication. From initial setup to production deployment, get step-by-step guidance tailored to your technology stack.

Overview

The Application Management feature helps you:

  • Guided Integration: Step-by-step setup for popular frameworks
  • Technology Detection: Automatic configuration based on your stack
  • Code Generation: Ready-to-use integration code and examples
  • Testing Tools: Built-in testing and validation capabilities
  • Documentation: Framework-specific guides and best practices

Application Wizard

Getting Started

The Application Wizard guides you through the entire integration process:

  1. Application Type Selection

    • Single Page Applications (SPA)
    • Traditional Web Applications
    • Mobile Applications
    • API/Backend Services
    • Machine-to-Machine Applications

  2. Technology Selection

    • Frontend frameworks (React, Vue, Angular, etc.)
    • Backend technologies (Node.js, Python, Java, etc.)
    • Mobile platforms (iOS, Android, React Native, etc.)
    • API frameworks (Express, FastAPI, Spring Boot, etc.)

  3. Configuration Generation

    • Automatic client configuration
    • Environment-specific settings
    • Security best practices applied
    • Integration code samples

Supported Technologies

Frontend Frameworks:

  • React: Complete integration with popular libraries
  • Vue.js: Vue 2 and Vue 3 support with composition API
  • Angular: Full Angular integration with guards and interceptors
  • Vanilla JavaScript: Pure JavaScript implementation
  • Next.js: Server-side rendering and static site generation
  • Nuxt.js: Vue-based universal applications

Backend Technologies:

  • Node.js: Express, Koa, and Fastify integrations
  • Python: Django, Flask, and FastAPI implementations
  • Java: Spring Boot and JAX-RS integrations
  • PHP: Laravel, Symfony, and vanilla PHP
  • Go: Gin, Echo, and native implementations
  • .NET: ASP.NET Core and Web API

Mobile Platforms:

  • React Native: Cross-platform mobile applications
  • iOS: Native Swift and Objective-C
  • Android: Native Java and Kotlin
  • Flutter: Cross-platform mobile development
  • Xamarin: Microsoft mobile development platform

Enterprise SSO (Salesforce, Microsoft 365, Google Workspace)

Enterprise SSO connects a SaaS application to your realm, so your people sign into it with their Skycloak identity instead of a separate password. Your realm acts as the identity provider and the SaaS application trusts it over SAML.

Choose Enterprise SSO in the application wizard, then pick the application from the gallery. Applications tagged “Ready” have a guided setup; anything tagged “Roadmap” can still be configured through Configure a custom SAML app, which works with any SAML 2.0 application.

Setting up Salesforce SSO

You will move between two browser tabs: Skycloak and your Salesforce Setup screen. Have Salesforce open before you start.

1. Tell Skycloak about your Salesforce org

Skycloak asks for two values, both from Salesforce:

Field Where to find it in Salesforce
Salesforce My Domain Setup > Company Settings > My Domain. Enter the host only, for example acme.my.salesforce.com. Leave off https:// and any path.
Salesforce Organization ID Setup > Company Settings > Company Information > Salesforce.com Organization ID.

Skycloak builds Salesforce’s entity ID and login URL from these, and creates the SAML client in your realm. Nothing is written to Salesforce.

2. Give Salesforce Skycloak’s details

In Salesforce, go to Setup > Identity > Single Sign-On Settings and select SAML Enabled.

The quickest route is to import Skycloak’s SAML metadata, which carries the issuer, the login URL and the signing certificate in one file. Copy the SAML metadata URL from Skycloak (the Open button shows it), then in Salesforce choose New from Metadata URL and paste it. If your Salesforce org cannot reach the URL, open it, save the page as a .xml file, and use New from Metadata File instead.

To fill the form by hand instead, choose New and map the values Skycloak shows:

Skycloak value Salesforce field
Identity Provider Login URL Identity Provider Login URL
Identity Provider Entity ID Issuer

For Identity Provider Certificate, Salesforce wants a certificate file, not the metadata document. Open the metadata, copy the text inside the <ds:X509Certificate> tag, and save it to a file between -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines. This is the step the metadata import saves you, which is why it is worth trying first.

Set SAML Identity Type to match how your users sign in. Skycloak sends the user’s email address, so either their Salesforce username must be that email address, or set the identity type to Federation ID and set each user’s Federation ID to their email address.

3. Test the connection

Back in Skycloak, choose Start test login. A sign-in opens in a new tab; complete it.

Skycloak confirms its own half of the exchange, that it signed you in and sent the assertion to Salesforce, and marks the application Verified. Check the tab that opened: if Salesforce signed you in, the connection works end to end. If Salesforce shows an error instead, the assertion reached it but was rejected, which usually means the certificate or the identity type does not match. Fix that in Salesforce and test again.

An application stays Not tested until a test login passes. Skycloak never marks a connection working just because the setup form succeeded.

If something goes wrong

  • “is not your managed realm”: the guided gallery currently sets up applications on the realm Skycloak manages for your workspace. For a realm on your own dedicated cluster, use the Keycloak admin console, or contact support.
  • The test login never confirms: your realm may have login events turned off, so Skycloak cannot see the result. The login itself still works; check the tab that opened.
  • You want to start over: remove the application and add it again. Removing it leaves the SAML client in your realm, so delete that from the Keycloak admin console too if you no longer want it.

Application Configuration

Basic Configuration

Application Details:

  • Name: Human-readable application name
  • Description: Purpose and functionality description
  • Type: Application architecture type
  • Environment: Development, staging, or production

Client Settings:

  • Client ID: Unique application identifier
  • Client Secret: Secure authentication credential (when applicable)
  • Redirect URIs: Allowed callback URLs after authentication
  • Logout URIs: Post-logout redirect destinations

Advanced Configuration

Authentication Flow:

  • Authorization Code Flow: Standard for web applications
  • PKCE: Enhanced security for public clients
  • Implicit Flow: Legacy flow for simple applications
  • Client Credentials: Machine-to-machine authentication
  • Device Flow: For devices with limited input capabilities

Token Configuration:

  • Access Token Lifespan: Token validity duration
  • Refresh Token Settings: Refresh token behavior
  • ID Token Claims: Custom claims and mappings
  • Token Encryption: Advanced security options

Scope and Permissions:

  • Default Scopes: Automatically granted permissions
  • Optional Scopes: User-consent required permissions
  • Audience Restrictions: Token audience limitations
  • Role Mappings: Application-specific role assignments

Token Mappers

A mapper decides what an application puts in the tokens it issues. Open an application and choose the Mappers tab to see what it adds today and to add more.

Token mappers on an application

Mappers run at the moment a token is created, so a change takes effect at the user’s next login, not for tokens already issued.

Adding a mapper

Add mapper offers the handful of things most applications need, plus an escape hatch for everything else.

Choosing a mapper type

Type What it does
Audience Names an API or gateway that should accept the token
User attribute Copies an attribute from the user into a claim
Role Puts the user’s realm roles in the token
Group membership Lists the groups the user belongs to
Fixed value Always adds the same claim and value
Something else Any Keycloak mapper type, with its config set by hand

Each one asks only for what it needs, and you choose whether the claim goes in the access token, the ID token, or both.

When a gateway rejects your tokens

If an API gateway refuses tokens with an audience error, an Audience mapper is the fix. Set the audience to the client ID of the API, or to whatever value the gateway expects in aud.

This bites on upgrade more than on first setup. Keycloak 26.6.2 began enforcing audience checks, so a token that a gateway accepted before can start being refused with no change on your side.

Passing a user attribute to an application

A User attribute mapper is how an attribute you keep on a user reaches the application. Name the attribute, and optionally a different claim name if the application expects one. Attributes are covered in User Management.

Mappers you cannot edit here

Below your own mappers is everything inherited from client scopes. These are shared: they come from a scope the application uses and apply to every application using that scope, so they are read-only on this page. Change them on the scope itself when you need to.

Integration Guidance

Step-by-Step Integration

1. Initial Setup

# Example for React application
npx create-react-app my-app
cd my-app
npm install @skycloak/react-auth

2. Configuration

// src/auth-config.js
export const authConfig = {
  realm: 'your-realm',
  clientId: 'your-client-id',
  serverUrl: 'https://your-cluster.skycloak.io'
};

3. Integration Implementation

// src/App.js
import { AuthProvider, useAuth } from '@skycloak/react-auth';
import { authConfig } from './auth-config';

function App() {
  return (
    <AuthProvider config={authConfig}>
      <Dashboard />
    </AuthProvider>
  );
}

4. Protected Routes

// src/Dashboard.js
import { ProtectedRoute } from '@skycloak/react-auth';

function Dashboard() {
  return (
    <ProtectedRoute>
      <h1>Protected Content</h1>
    </ProtectedRoute>
  );
}

Framework-Specific Guides

React Integration:

  • Hooks-based authentication state management
  • Context providers for global auth state
  • Protected route components
  • Automatic token refresh handling

Vue.js Integration:

  • Composition API authentication composables
  • Vue Router integration and guards
  • Reactive authentication state
  • Plugin-based configuration

Angular Integration:

  • Service-based authentication management
  • Route guards for protected routes
  • HTTP interceptors for token management
  • Dependency injection patterns

Testing and Validation

Built-in Testing Tools

Authentication Testing:

  • Login Flow Validation: Test complete authentication flows
  • Token Verification: Validate token format and claims
  • Logout Testing: Verify proper session cleanup
  • Refresh Token Testing: Test token renewal processes

Integration Testing:

  • API Endpoint Testing: Test protected API endpoints
  • CORS Configuration: Validate cross-origin settings
  • Redirect URI Testing: Test callback URL configurations
  • Error Handling: Test error scenarios and recovery

Development Tools

Debug Dashboard:

  • Real-time authentication events
  • Token inspection and decoding
  • Network request monitoring
  • Error diagnosis and troubleshooting

Test Users:

  • Pre-configured test accounts
  • Different role and permission sets
  • Automated test scenario execution
  • Performance testing capabilities

Security Best Practices

Implementation Security

Token Management:

  • Secure token storage (httpOnly cookies recommended)
  • Automatic token refresh implementation
  • Proper token expiration handling
  • Cross-site scripting (XSS) protection

Network Security:

  • HTTPS enforcement for all communications
  • Proper CORS configuration
  • Content Security Policy (CSP) implementation
  • Secure redirect URI validation

Client Configuration:

  • Public vs confidential client types
  • PKCE implementation for public clients
  • Client secret protection and rotation
  • Minimum required scope principle

Vulnerability Prevention

Common Security Issues:

  • Token leakage through logs or error messages
  • Insecure redirect URI configurations
  • Cross-site request forgery (CSRF) attacks
  • Session fixation vulnerabilities

Prevention Strategies:

  • Regular security audits and reviews
  • Automated vulnerability scanning
  • Security-focused code reviews
  • Penetration testing recommendations

Production Deployment

Deployment Checklist

Pre-Deployment:

  • Security review completed
  • Performance testing passed
  • Error handling implemented
  • Monitoring and logging configured
  • Backup and recovery plan ready

Configuration Review:

  • Production redirect URIs configured
  • Client secrets properly secured
  • Token lifespans appropriately set
  • Scope and permissions reviewed
  • Rate limiting configured

Post-Deployment:

  • Authentication flows tested
  • Monitoring dashboards configured
  • Error alerts set up
  • Performance metrics baseline established
  • Documentation updated

Monitoring and Maintenance

Performance Monitoring:

  • Authentication success rates
  • Token refresh frequency
  • API response times
  • Error rates and patterns

Security Monitoring:

  • Failed authentication attempts
  • Suspicious user behavior
  • Token abuse patterns
  • Compliance audit trails

Troubleshooting

Common Integration Issues

Authentication Failures:

  • Invalid client configuration
  • Incorrect redirect URI setup
  • Token expiration issues
  • Network connectivity problems

Configuration Problems:

  • Missing or incorrect scopes
  • Wrong authentication flow selection
  • CORS configuration errors
  • SSL/TLS certificate issues

Performance Issues:

  • Slow authentication responses
  • Token refresh failures
  • Network latency problems
  • Resource exhaustion

Debugging Tools

Built-in Diagnostics:

  • Real-time error logging
  • Authentication flow visualization
  • Token introspection tools
  • Network request analysis

External Tools:

  • Browser developer tools integration
  • Postman collection for API testing
  • Curl command examples
  • SDK debugging features

Advanced Features

Multi-Environment Support

Environment Management:

  • Development, staging, and production configurations
  • Environment-specific client settings
  • Automated deployment pipelines
  • Configuration synchronization

Environment Variables:

  • Secure credential management
  • Environment-specific URLs and settings
  • Configuration templating
  • Secret rotation automation

Enterprise Features

Advanced Analytics:

  • Application usage analytics
  • User behavior tracking
  • Performance metrics
  • Security event monitoring

Compliance Support:

  • Audit trail logging
  • Compliance reporting
  • Data retention policies
  • Regulatory requirement tracking

Custom Integrations:

  • Webhook-based notifications
  • Custom authentication flows
  • API gateway integration
  • Legacy system connectors

Integration Documentation

Once you’ve created your application, follow our comprehensive integration guides:

🚀 Quick Links by Technology

Frontend Frameworks:

Backend Technologies:

Mobile Platforms:

📚 Complete Integration Resources

Next Steps

Last updated on
User ManagementWebhooks