Use kc_idp_hint to Choose Identity Provider in Keycloak

Last updated: March 2026
When you configure multiple identity providers in Keycloak, users typically land on a login page where they must choose which provider to authenticate with. This extra step adds friction, especially when you already know which IdP the user should use. The kc_idp_hint query parameter solves this by bypassing the Keycloak login screen entirely and redirecting users straight to their designated identity provider.

This guide covers everything you need to know about kc_idp_hint — from basic usage and client integration to dynamic IdP selection, security best practices, and troubleshooting common issues.

What Is kc_idp_hint?

kc_idp_hint is a Keycloak-specific query parameter that you append to the OpenID Connect authorization URL. When Keycloak receives a request with this parameter, it skips rendering its own login page and immediately redirects the user to the specified external identity provider.

The value you pass must match the alias of an identity provider configured in your Keycloak realm. For example, if you have Google configured with the alias google, passing kc_idp_hint=google sends users directly to Google’s login screen.

This is particularly useful in enterprise scenarios where:

• Tenants each use a different IdP — a SaaS application can route customers to their corporate IdP without showing a generic login page.
• You want a branded login experience — instead of showing Keycloak’s login page, users go straight to their organization’s SSO portal.
• Self-service portals — employees accessing internal tools should authenticate through their company’s Active Directory or Okta instance without extra clicks.

If you manage multiple identity providers in your Keycloak deployment, kc_idp_hint is one of the simplest ways to streamline the login flow.

How kc_idp_hint Works

The mechanism is straightforward. During a standard OIDC authorization code flow, your application redirects users to Keycloak’s authorization endpoint. Keycloak normally presents its login page, which lists all configured identity providers alongside any local login form.

When you add kc_idp_hint to the authorization URL, Keycloak intercepts the request before rendering the login page. It looks up the IdP alias you specified, and if it finds a match, it immediately constructs the appropriate redirect to that provider’s authorization endpoint.

The full flow looks like this:

1. User clicks “Log in” in your application.
2. Your application redirects to Keycloak’s authorization endpoint with kc_idp_hint={idp_alias}.
3. Keycloak skips the login page and redirects to the specified identity provider.
4. The user authenticates with the external IdP.
5. The IdP redirects back to Keycloak with the authentication response.
6. Keycloak processes the response, creates or updates the user session, and redirects back to your application with an authorization code.
7. Your application exchanges the code for tokens.

The rest of the OIDC flow proceeds exactly as it would without the hint. The only difference is that step 3 bypasses the Keycloak login page.

Basic Usage Example

Here is the full authorization URL with kc_idp_hint included:

https://{keycloak-host}/realms/{realm}/protocol/openid-connect/auth?client_id={client_id}&response_type=code&scope=openid&redirect_uri={redirect_uri}&kc_idp_hint={idp_alias}

Replace the placeholders with your actual values:

Placeholder	Description
{keycloak-host}	Your Keycloak server domain (e.g., auth.example.com)
{realm}	The Keycloak realm name
{client_id}	The OIDC client ID registered in Keycloak
{redirect_uri}	The URL Keycloak redirects to after authentication
{idp_alias}	The alias of the identity provider in Keycloak

A concrete example using Google as the IdP:

https://auth.example.com/realms/my-realm/protocol/openid-connect/auth?client_id=my-app&response_type=code&scope=openid%20email%20profile&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback&kc_idp_hint=google

To find the alias of your identity provider, go to Realm Settings > Identity Providers in the Keycloak admin console. The alias is displayed in the list and is also part of the redirect URI that Keycloak generates for the provider.

Using kc_idp_hint with OIDC Clients

Most OIDC client libraries allow you to pass additional query parameters to the authorization endpoint. Here are examples for common frameworks.

JavaScript (Using oidc-client-ts)

const settings = {
  authority: 'https://auth.example.com/realms/my-realm',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  response_type: 'code',
  scope: 'openid email profile',
  extraQueryParams: {
    kc_idp_hint: 'google'
  }
};

const userManager = new UserManager(settings);
userManager.signinRedirect();

React (Using react-oidc-context)

import { AuthProvider } from 'react-oidc-context';

const oidcConfig = {
  authority: 'https://auth.example.com/realms/my-realm',
  client_id: 'my-app',
  redirect_uri: 'https://app.example.com/callback',
  extraQueryParams: {
    kc_idp_hint: 'okta-corporate'
  }
};

function App() {
  return (
    <AuthProvider {...oidcConfig}>
      <YourApp />
    </AuthProvider>
  );
}

Keycloak JavaScript Adapter

If you use Keycloak’s own JavaScript adapter, pass the hint through the idpHint option:

const keycloak = new Keycloak({
  url: 'https://auth.example.com',
  realm: 'my-realm',
  clientId: 'my-app'
});

keycloak.init({ onLoad: 'login-required' });

// When triggering login explicitly:
keycloak.login({
  idpHint: 'azure-ad'
});

The Keycloak adapter translates idpHint into the kc_idp_hint query parameter automatically.

Using kc_idp_hint with SAML Clients

For SAML service providers, Keycloak supports kc_idp_hint as a query parameter on the SAML SSO endpoint. You can append it to the IDP-initiated or SP-initiated SSO URL:

https://auth.example.com/realms/my-realm/protocol/saml?kc_idp_hint=corporate-saml-idp

Alternatively, if your SAML SP supports relay state or additional parameters, you can embed the hint there. The exact implementation depends on your SAML library, but the principle is the same — the hint value must reach Keycloak’s endpoint as a query parameter.

For SP-initiated flows, most SAML libraries let you customize the authentication request URL. Add kc_idp_hint as an additional query parameter alongside the SAMLRequest.

Dynamic IdP Selection with Home Realm Discovery

Hardcoding kc_idp_hint works well when you know the IdP upfront, but many applications need to determine the correct provider dynamically. This pattern is commonly called Home Realm Discovery (HRD).

Email Domain Mapping

The most common approach maps email domains to identity providers. Your application collects the user’s email address first, then determines which IdP to use based on the domain:

const idpMap = {
  'acme.com': 'acme-okta',
  'globex.com': 'globex-azure-ad',
  'initech.com': 'initech-saml'
};

function getIdpForEmail(email) {
  const domain = email.split('@')[1]?.toLowerCase();
  return idpMap[domain] || null;
}

// Usage
const email = document.getElementById('email-input').value;
const idpAlias = getIdpForEmail(email);

if (idpAlias) {
  // Redirect with kc_idp_hint
  const authUrl = new URL(
    'https://auth.example.com/realms/my-realm/protocol/openid-connect/auth'
  );
  authUrl.searchParams.set('client_id', 'my-app');
  authUrl.searchParams.set('response_type', 'code');
  authUrl.searchParams.set('scope', 'openid email profile');
  authUrl.searchParams.set('redirect_uri', 'https://app.example.com/callback');
  authUrl.searchParams.set('kc_idp_hint', idpAlias);
  window.location.href = authUrl.toString();
} else {
  // Fall back to standard Keycloak login page
  window.location.href = 'https://auth.example.com/realms/my-realm/protocol/openid-connect/auth?client_id=my-app&response_type=code&scope=openid&redirect_uri=https://app.example.com/callback';
}

Database-Driven Mapping

For multi-tenant SaaS applications, store IdP mappings in your database rather than hardcoding them. This lets you onboard new enterprise customers without code changes:

// API call to your backend
const response = await fetch(`/api/tenant/idp?email=${encodeURIComponent(email)}`);
const { idpAlias } = await response.json();

if (idpAlias) {
  keycloak.login({ idpHint: idpAlias });
} else {
  keycloak.login(); // Standard login page
}

This pattern is essential for single sign-on implementations where each customer organization has its own identity provider.

Keycloak’s Built-in Home Realm Discovery

Keycloak also supports a built-in approach using the kc_idp_hint with authentication flows. You can create a custom authentication flow that inspects the user’s email domain and automatically redirects to the appropriate IdP. This is configured entirely within Keycloak’s admin console under Authentication > Flows.

Security Considerations

While kc_idp_hint simplifies the login experience, there are important security aspects to consider.

Validate the Hint Value

Never pass user-supplied input directly as the kc_idp_hint value without validation. If an attacker can control the hint, they might redirect users to a malicious identity provider (if one were somehow configured) or cause unexpected behavior.

// Always validate against a known allowlist
const allowedIdps = ['google', 'azure-ad', 'okta-corporate'];

function sanitizeIdpHint(hint) {
  if (allowedIdps.includes(hint)) {
    return hint;
  }
  return null; // Fall back to standard login
}

Prevent Open Redirects

Ensure your redirect_uri values are strictly configured in Keycloak’s client settings. Use exact match URIs rather than wildcards. This prevents attackers from crafting authorization URLs that redirect users to malicious sites after authentication.

In the Keycloak admin console, configure Valid Redirect URIs with specific paths:

https://app.example.com/callback
https://app.example.com/auth/callback

Avoid patterns like https://app.example.com/* in production.

IdP-Specific Considerations

• SAML IdPs: Ensure the assertion consumer service URL is correctly configured on both sides.
• Social providers: Rate limiting may apply if many users are redirected simultaneously.
• Enterprise IdPs: Verify that the IdP’s session policies align with your application’s requirements.

Token Validation

After authentication completes, always validate the tokens you receive. The kc_idp_hint only affects the login redirect — it does not change how tokens are issued or validated. Use a JWT token analyzer to inspect tokens during development and verify that claims from the external IdP are correctly mapped.

Common Issues and Troubleshooting

“Identity Provider Not Found” Error

Symptom: Keycloak returns an error page instead of redirecting to the IdP.

Cause: The kc_idp_hint value does not match any configured IdP alias.

Fix: Check the exact alias in Identity Providers in the admin console. Aliases are case-sensitive and typically lowercase with hyphens.

User Lands on Keycloak Login Page Despite the Hint

Symptom: The kc_idp_hint parameter seems to be ignored.

Possible causes:

• The parameter name is misspelled (it must be exactly kc_idp_hint).
• The IdP is disabled in Keycloak.
• A custom authentication flow overrides the default behavior.
• The parameter is being URL-encoded incorrectly.

Fix: Check the browser’s network tab to confirm the parameter appears correctly in the authorization URL. Verify the IdP is enabled and the alias matches exactly.

First Login Flow Interrupts the Redirect

Symptom: New users are shown a Keycloak “Update Account” or “Review Profile” page after IdP authentication.

Cause: Keycloak’s first broker login flow requires users to review or complete their profile on first login.

Fix: Configure the IdP’s First Login Flow to automatically create users without prompting. In the admin console, go to the IdP settings and set the first login flow to one that skips the review step, or create a custom flow that auto-links accounts.

Token Does Not Contain Expected IdP Claims

Symptom: After authentication through the hinted IdP, the access token or ID token is missing expected claims.

Fix: Configure identity provider mappers on the IdP in Keycloak. These mappers control how attributes from the external IdP are mapped to Keycloak user attributes and token claims. Go to Identity Providers > {Your IdP} > Mappers to add or adjust mappings.

CORS Errors During Redirect

Symptom: Browser console shows CORS errors when initiating the login flow.

Fix: Ensure your application’s origin is listed in the Web Origins setting of your Keycloak client. You can set it to + to automatically allow all valid redirect URIs, or specify exact origins.

Wrapping Up

The kc_idp_hint parameter is a simple but powerful tool for controlling the authentication experience in Keycloak. By directing users to the correct identity provider automatically, you eliminate unnecessary login page friction and create a smoother SSO experience.

For production deployments, combine kc_idp_hint with Home Realm Discovery to dynamically route users based on their email domain or tenant configuration. This approach scales well for multi-tenant SaaS applications and enterprise deployments.

If you are setting up Keycloak identity providers for the first time, check out the Skycloak documentation for detailed configuration guides. For managed Keycloak hosting with built-in identity provider management, Skycloak handles the infrastructure so you can focus on building your application.