feat: add external IDP integration (hybrid mode)

Signed-off-by: Vladimir Belousov <vbelouso@redhat.com>

Author: vbelouso

docs/authentication.md

@@ -12,6 +12,21 @@ ExploitIQ supports multiple authentication modes via Quarkus profiles:
 | `external-idp` | External identity providers | Keycloak, Google, Azure AD, Okta |
 | `dev` | Local development | Keycloak DevServices |
 
+### Authentication Methods
+
+All profiles support both browser and API authentication:
+
+| Method | Use Case | Flow |
+|--------|----------|------|
+| Browser | Web UI | Authorization Code Flow (redirects to IdP) |
+| API | CLI, scripts, services | Bearer JWT token in `Authorization` header |
+
+**Token acquisition differs by profile:**
+
+- `prod` (OpenShift): Use `oc whoami -t` or ServiceAccount tokens
+- `external-idp` (Keycloak): Use OIDC token endpoint with password grant
+- `dev`: Same as `external-idp` (DevServices Keycloak)
+
 ## OpenShift OAuth (Production)
 
 The default production configuration uses OpenShift's built-in OAuth server.
@@ -57,6 +72,16 @@ spec:
           key: secret
 ```
 
+### API Access (prod profile)
+
+For API access in OpenShift, use your user token:
+
+```bash
+# After oc login
+TOKEN=$(oc whoami -t)
+curl -H "Authorization: Bearer $TOKEN" https://exploit-iq-client.apps.example.com/api/v1/reports
+```
+
 ## External Identity Providers
 
 Use the `external-idp` profile to integrate with external OIDC providers.
@@ -84,13 +109,17 @@ Create an OIDC client in Keycloak with the following settings:
   "clientId": "exploit-iq-client",
   "enabled": true,
   "clientAuthenticatorType": "client-secret",
+  "secret": "<your-client-secret>",
   "redirectUris": ["https://your-app-url/*"],
   "webOrigins": ["https://your-app-url"],
   "publicClient": false,
-  "standardFlowEnabled": true
+  "standardFlowEnabled": true,
+  "directAccessGrantsEnabled": true
 }
 ```
 
+**Important:** `directAccessGrantsEnabled: true` is required for API authentication via password grant.
+
 Required protocol mappers (add to client scope):
 
 - `preferred_username`: Maps `username` to `preferred_username` claim
@@ -149,6 +178,80 @@ The same approach works with any OIDC-compliant provider:
 
 **Note:** GitHub does not support OIDC. Use Keycloak as an identity broker for GitHub authentication.
 
+## API Authentication with JWT (external-idp)
+
+When using Keycloak or other OIDC providers, you can obtain tokens via the standard OIDC token endpoint. This allows CLI tools, scripts, and external services to authenticate without browser interaction.
+
+### Obtaining a User Token
+
+Use the password grant to obtain a token for a specific user:
+
+```bash
+# Configuration (match your Keycloak setup)
+KC_URL="http://localhost:8190"           # Keycloak URL
+KC_REALM="quarkus"                       # Realm name
+CLIENT_ID="exploit-iq-client"            # Client ID
+CLIENT_SECRET="example-credentials"      # Client secret
+USERNAME="bruce"                         # User
+PASSWORD="wayne"                         # Password
+
+# Get user token (scope=openid is REQUIRED)
+USER_TOKEN=$(curl -s -X POST \
+  "${KC_URL}/realms/${KC_REALM}/protocol/openid-connect/token" \
+  -d "client_id=${CLIENT_ID}" \
+  -d "client_secret=${CLIENT_SECRET}" \
+  -d "username=${USERNAME}" \
+  -d "password=${PASSWORD}" \
+  -d "grant_type=password" \
+  -d "scope=openid profile email" | jq -r '.access_token')
+
+# Verify token was obtained
+echo "Token: ${USER_TOKEN:0:50}..."
+```
+
+**Important:** The `scope=openid profile email` parameter is required. Without `openid`, the UserInfo endpoint will reject the token with "Missing openid scope" error.
+
+### Making API Requests
+
+Use the token in the `Authorization` header:
+
+```bash
+# List reports
+curl -H "Authorization: Bearer $USER_TOKEN" \
+  http://localhost:8080/api/v1/reports
+
+# Get specific report
+curl -H "Authorization: Bearer $USER_TOKEN" \
+  http://localhost:8080/api/v1/reports/{id}
+```
+
+### Service-to-Service Authentication (Optional)
+
+For machine-to-machine communication, use the client credentials grant:
+
+```bash
+# Get service token
+SERVICE_TOKEN=$(curl -s -X POST \
+  "${KC_URL}/realms/${KC_REALM}/protocol/openid-connect/token" \
+  -d "client_id=${SERVICE_CLIENT_ID}" \
+  -d "client_secret=${SERVICE_SECRET}" \
+  -d "grant_type=client_credentials" | jq -r '.access_token')
+
+curl -H "Authorization: Bearer $SERVICE_TOKEN" \
+  http://localhost:8080/api/v1/reports
+```
+
+**Note:** Requires a separate Keycloak client configured for service accounts.
+
+### Token Validation
+
+The application validates JWT tokens by:
+
+1. Verifying the signature using JWKS from the IdP
+2. Checking token expiration
+3. Validating the issuer (`iss` claim)
+4. Fetching UserInfo to extract user details
+
 ## Identity Brokering with Keycloak
 
 Keycloak can act as an identity broker, allowing users to authenticate via external providers while maintaining centralized user management.
@@ -207,6 +310,8 @@ podman run -d --name keycloak \
   -p 8190:8080 \
   -e KEYCLOAK_ADMIN=admin \
   -e KEYCLOAK_ADMIN_PASSWORD=admin \
+  -e KC_HTTP_ENABLED=true \
+  -e KC_HOSTNAME=localhost \
   quay.io/keycloak/keycloak:26.4 start-dev
 
 # Start application (using 'quarkus' as example realm name)
@@ -225,14 +330,30 @@ An automated testing script is available for all authentication scenarios:
 ./scripts/test-auth.sh --help
 ```
 
-The script supports:
+The script supports DevServices Keycloak, external Keycloak (with optional GitHub/Google brokers), and direct Google OIDC.
 
-1. DevServices Keycloak (local development)
-2. DevServices + GitHub Broker
-3. External Keycloak (standalone)
-4. External Keycloak + GitHub Broker
-5. External Keycloak + Google Broker
-6. Direct Google OIDC
+#### Testing API Authentication
+
+After running a scenario with Keycloak, test API authentication:
+
+```bash
+# 1. Get user token (uses bruce/wayne created by the script)
+USER_TOKEN=$(curl -s -X POST \
+  "http://localhost:8190/realms/quarkus/protocol/openid-connect/token" \
+  -d "client_id=exploit-iq-client" \
+  -d "client_secret=example-credentials" \
+  -d "username=bruce" \
+  -d "password=wayne" \
+  -d "grant_type=password" \
+  -d "scope=openid profile email" | jq -r '.access_token')
+
+# 2. Verify token obtained
+[ -n "$USER_TOKEN" ] && echo "Token obtained" || echo "Failed to get token"
+
+# 3. Call API with Bearer token
+curl -H "Authorization: Bearer $USER_TOKEN" \
+  http://localhost:8080/api/v1/reports
+```
 
 ## User Display
 
@@ -262,6 +383,31 @@ Ensure your identity provider or Keycloak is configured to include the `email` c
 - Ensure exact match including trailing slash: `https://your-app/`
 - Changes may take 5-15 minutes to propagate
 
+### API Returns 401 Unauthorized
+
+**Cause:** Token missing `openid` scope or invalid token.
+
+**Solution:**
+
+1. Ensure `scope=openid profile email` is included in token request
+2. Verify token is not expired
+3. Check Keycloak logs for "Missing openid scope" error
+
+### HTTPS Required Error (Keycloak)
+
+**Cause:** Keycloak 26.x requires HTTPS by default, even in development.
+
+**Solution:** For local development, set `sslRequired=NONE` on the realm:
+
+```bash
+# Using kcadm.sh inside container
+podman exec keycloak /opt/keycloak/bin/kcadm.sh config credentials \
+  --server http://localhost:8080 --realm master --user admin --password admin
+podman exec keycloak /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE
+```
+
+The testing script (`test-auth.sh`) handles this automatically.
+
 ### Enable Debug Logging
 
 Add to `application.properties` or set as environment variable:
@@ -270,9 +416,16 @@ Add to `application.properties` or set as environment variable:
 quarkus.log.category."io.quarkus.oidc".level=DEBUG
 ```
 
+Or run the testing script with debug flag:
+
+```bash
+./scripts/test-auth.sh --debug
+```
+
 ## Additional Resources
 
 - [Quarkus OIDC Guide](https://quarkus.io/guides/security-openid-connect)
+- [Quarkus OIDC Bearer Token Authentication](https://quarkus.io/guides/security-oidc-bearer-token-authentication)
 - [Quarkus Configuring Well-Known OpenID Connect Providers](https://quarkus.io/guides/security-openid-connect-providers)
 - [Keycloak Documentation](https://www.keycloak.org/documentation)
 - [GitHub OAuth Apps](https://docs.github.com/en/developers/apps/building-oauth-apps)

docs/development.md

@@ -61,6 +61,20 @@ Or, if you don't have GraalVM installed, you can run the native executable build
 
 You can then execute your native executable with: `./target/agent-morpheus-client-1.0.0-SNAPSHOT-runner`
 
+### Building with profiles
+
+Some Quarkus properties are **build-time only** and cannot be changed at runtime. When building for a specific deployment target, include the profile:
+
+```shell
+# For external-idp deployments (Keycloak, Google, etc.)
+./mvnw package -Dnative -Dquarkus.profile=external-idp
+
+# For prod deployments (OpenShift OAuth) - default
+./mvnw package -Dnative
+```
+
+**Important:** The CI/CD pipeline builds a universal image without a specific profile. Runtime profile selection via `QUARKUS_PROFILE` works for most configurations, but build-time properties (like `@IfBuildProfile` annotations) are fixed at compile time.
+
 If you want to learn more about building native executables, please consult <https://quarkus.io/guides/maven-tooling>.
 
 ## Related Guides

scripts/test-auth.sh

@@ -59,6 +59,7 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 APP_NAMESPACE=""
 KC_BASE_URL=""
 KC_TOKEN=""
+DEBUG="${DEBUG:-false}"
 
 # Colors for output
 readonly RED='\033[0;31m'
@@ -86,6 +87,12 @@ print_info() {
   echo "$1"
 }
 
+print_debug() {
+  if [ "$DEBUG" = "true" ]; then
+    echo -e "${YELLOW}[DEBUG] $1${NC}"
+  fi
+}
+
 show_help() {
   cat << EOF
 Authentication Testing Script
@@ -94,17 +101,19 @@ Usage: $0 [OPTIONS]
 
 Options:
   --help, -h    Show this help message
+  --debug, -d   Enable debug output (shows curl responses, URLs, etc.)
 
 Environment Variables:
-  CONTAINER_ENGINE     Container runtime: podman or docker (auto-detected)
-  APP_SERVICE_NAME     Kubernetes deployment name (default: exploit-iq-client)
   APP_CLIENT_ID        OIDC client ID (default: exploit-iq-client)
   APP_CLIENT_SECRET    OIDC client secret (default: example-credentials)
-  KC_LOCAL_PORT        Local Keycloak port (default: 8190)
+  APP_SERVICE_NAME     Kubernetes deployment name (default: exploit-iq-client)
+  CONTAINER_ENGINE     Container runtime: podman or docker (auto-detected)
+  DEBUG              Enable debug mode (true/false, default: false)
+  KC_ADMIN_PASS        Keycloak admin password (default: admin)
+  KC_ADMIN_USER        Keycloak admin username (default: admin)
   KC_CONTAINER_NAME    Keycloak container name (default: keycloak-standalone)
   KC_IMAGE             Keycloak container image (default: quay.io/keycloak/keycloak:26.4)
-  KC_ADMIN_USER        Keycloak admin username (default: admin)
-  KC_ADMIN_PASS        Keycloak admin password (default: admin)
+  KC_LOCAL_PORT        Local Keycloak port (default: 8190)
   KC_OCP_NAMESPACE     OpenShift namespace for Keycloak (default: keycloak-dev)
 
 Scenarios:
@@ -213,10 +222,19 @@ setup_local_keycloak() {
     -e KC_HEALTH_ENABLED=true \
     -e KC_METRICS_ENABLED=true \
     -e KC_HTTP_MANAGEMENT_HEALTH_ENABLED=false \
+    -e KC_HOSTNAME=localhost \
+    -e KC_HTTP_ENABLED=true \
     "${KC_IMAGE}" start-dev >/dev/null
 
   KC_BASE_URL="http://localhost:${KC_LOCAL_PORT}"
   wait_for_keycloak_health "$KC_BASE_URL"
+  
+  # Disable SSL requirement for local development (Keycloak 26.x requires this)
+  print_info "Configuring Keycloak for HTTP access..."
+  ${CONTAINER_ENGINE} exec "${KC_CONTAINER_NAME}" /opt/keycloak/bin/kcadm.sh config credentials \
+    --server http://localhost:8080 --realm master --user "${KC_ADMIN_USER}" --password "${KC_ADMIN_PASS}" >/dev/null
+  ${CONTAINER_ENGINE} exec "${KC_CONTAINER_NAME}" /opt/keycloak/bin/kcadm.sh update realms/master -s sslRequired=NONE >/dev/null
+  print_success "Keycloak configured for HTTP"
   echo ""
 }
 
@@ -294,15 +312,24 @@ wait_for_keycloak_health() {
 # ==============================================================================
 
 get_admin_token() {
-  KC_TOKEN=$(curl -k -s -X POST "${KC_BASE_URL}/realms/master/protocol/openid-connect/token" \
+  local token_url="${KC_BASE_URL}/realms/master/protocol/openid-connect/token"
+  print_debug "Token URL: $token_url"
+  print_debug "Admin user: ${KC_ADMIN_USER}"
+  
+  local response
+  response=$(curl -k -s -X POST "$token_url" \
     -d "username=${KC_ADMIN_USER}" \
     -d "password=${KC_ADMIN_PASS}" \
     -d "grant_type=password" \
-    -d "client_id=admin-cli" \
-    | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
+    -d "client_id=admin-cli")
+  
+  print_debug "Token response: $response"
+  
+  KC_TOKEN=$(echo "$response" | grep -o '"access_token":"[^"]*' | cut -d'"' -f4)
 
   if [ -z "$KC_TOKEN" ]; then
     print_error "Failed to obtain Keycloak admin token"
+    print_error "Response: $response"
     exit 1
   fi
 }
@@ -319,12 +346,12 @@ configure_keycloak() {
     -H "Authorization: Bearer $KC_TOKEN" || true
   print_success "done"
 
-  # Create realm
+  # Create realm (with sslRequired=NONE for local development)
   echo -n "Creating realm '${KC_REALM}'... "
   curl -k -s -o /dev/null -X POST "${KC_BASE_URL}/admin/realms" \
     -H "Authorization: Bearer $KC_TOKEN" \
     -H "Content-Type: application/json" \
-    -d "{\"realm\": \"${KC_REALM}\", \"enabled\": true}"
+    -d "{\"realm\": \"${KC_REALM}\", \"enabled\": true, \"sslRequired\": \"NONE\"}"
   print_success "done"
 
   sleep 1
@@ -343,7 +370,7 @@ configure_keycloak() {
       \"webOrigins\": [\"${app_url}\"],
       \"publicClient\": false,
       \"standardFlowEnabled\": true,
-      \"directAccessGrantsEnabled\": false,
+      \"directAccessGrantsEnabled\": true,
       \"attributes\": {
         \"post.logout.redirect.uris\": \"${app_url}/logged-out\"
       }
@@ -739,11 +766,20 @@ scenario_direct_google() {
 
 main() {
   # Parse arguments
-  case "${1:-}" in
-    --help|-h)
-      show_help
-      ;;
-  esac
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --help|-h)
+        show_help
+        ;;
+      --debug|-d)
+        DEBUG=true
+        shift
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
 
   check_dependencies
   cd "$PROJECT_ROOT"