Comprehensive Guide to Keycloak OAuth2 and OpenID Connect Endpoints

Introduction

Keycloak is an open-source identity and access management solution that provides Single Sign-On (SSO) capabilities using standards like OAuth2 and OpenID Connect. Many developers choose to integrate Keycloak with their applications using standard OAuth2 and OpenID Connect client libraries, rather than Keycloak-specific adapters, to ensure compatibility across diverse programming languages such as PHP, Ruby, Node.js, Java, C#, and Angular. However, Keycloak's documentation can sometimes lack basic details, such as the specific endpoints required for OAuth2 and OpenID Connect flows. This article aims to fill that gap by providing a comprehensive guide to Keycloak's key endpoints, how to discover them, and how to use them effectively with standard libraries.

Discovering Endpoints via OpenID Connect Discovery

As a fully compliant OpenID Connect Provider, Keycloak exposes a discovery endpoint that allows clients to dynamically retrieve all necessary configuration, including endpoint URLs. For a Keycloak instance running on http://localhost:8080/ and a realm named test, the discovery endpoint is:

http://localhost:8080/realms/test/.well-known/openid-configuration

Accessing this URL returns a JSON object that contains various endpoints and configuration options. For example, a typical response might include:

{"issuer": "http://localhost:8080/realms/test", "authorization_endpoint": "http://localhost:8080/realms/test/protocol/openid-connect/auth", "token_endpoint": "http://localhost:8080/realms/test/protocol/openid-connect/token", "userinfo_endpoint": "http://localhost:8080/realms/test/protocol/openid-connect/userinfo", "end_session_endpoint": "http://localhost:8080/realms/test/protocol/openid-connect/logout", "jwks_uri": "http://localhost:8080/realms/test/protocol/openid-connect/certs", "grant_types_supported": ["authorization_code", "refresh_token", "password"], "response_types_supported": ["code"], "subject_types_supported": ["public"], "id_token_signing_alg_values_supported": ["RS256"], "response_modes_supported": ["query"]}

This endpoint is crucial for clients that need to adapt to changes in Keycloak configuration without hardcoding URLs.

Key OAuth2 and OpenID Connect Endpoints

Based on the discovery response, several key endpoints are essential for OAuth2 and OpenID Connect flows:

• Authorization Endpoint: Used to authenticate users via redirects. URL: http://localhost:8080/realms/test/protocol/openid-connect/auth
• Token Endpoint: Used to obtain tokens (e.g., access token, refresh token). URL: http://localhost:8080/realms/test/protocol/openid-connect/token
• UserInfo Endpoint: Returns user claims, protected by a bearer token. URL: http://localhost:8080/realms/test/protocol/openid-connect/userinfo
• End Session Endpoint: Used for logging out users. URL: http://localhost:8080/realms/test/protocol/openid-connect/logout
• JWKS URI: Provides public keys for token validation. URL: http://localhost:8080/realms/test/protocol/openid-connect/certs

Additional endpoints include introspection, revocation, dynamic client registration, device authorization, and backchannel authentication, as detailed in Keycloak's documentation.

Code Examples

To use these endpoints with standard OAuth2/OpenID Connect libraries, you can first retrieve the configuration dynamically. Here's an example using cURL in a shell script:

curl -X GET http://localhost:8080/realms/test/.well-known/openid-configuration

In Python, you might use the requests library:

import requests
response = requests.get('http://localhost:8080/realms/test/.well-known/openid-configuration')
config = response.json()
authorization_url = config['authorization_endpoint']
# Use authorization_url in OAuth2 flow

Similarly, in JavaScript with Node.js:

const https = require('https'); // or use a library like axios
const url = 'http://localhost:8080/realms/test/.well-known/openid-configuration';
https.get(url, (res) => {
  let data = '';
  res.on('data', (chunk) => { data += chunk; });
  res.on('end', () => {
    const config = JSON.parse(data);
    console.log(config.authorization_endpoint);
  });
});

These examples demonstrate how to avoid hardcoding endpoints by leveraging the discovery mechanism.

Best Practices and Security Considerations

When integrating Keycloak with standard libraries, consider the following best practices:

• Always use HTTPS in production to encrypt communications.
• Validate redirect URIs strictly to prevent open redirect attacks.
• Use the introspection endpoint for token validation if needed, but prefer local JWT validation for performance.
• Avoid using deprecated flows like Implicit Grant or Resource Owner Password Credentials, as per OAuth 2.0 security best practices.
• Ensure client applications are configured with correct redirect URIs and client credentials.

For compliance with standards like FAPI or OAuth 2.1, refer to Keycloak's client policies and profiles.

Conclusion

Keycloak provides a robust set of OAuth2 and OpenID Connect endpoints that can be easily discovered and used with standard client libraries. By utilizing the .well-known/openid-configuration endpoint, developers can build flexible and secure applications across multiple programming languages. This approach reduces dependency on Keycloak-specific code and enhances interoperability. For further details, consult the official Keycloak documentation and relevant RFC specifications.