unionflow-client-quarkus-primefaces-freya/keycloak-mobile-client-config.md

# Configuration Client Mobile Keycloak pour UnionFlow

## Objectif
Configurer un client Keycloak spécifique pour l'application mobile UnionFlow avec authentification OIDC.

## Étapes de Configuration

### 1. Créer le Client Mobile
1. Accéder à Keycloak Admin Console: http://localhost:8180/admin
2. Sélectionner le realm **unionflow**
3. Aller dans **Clients** → **Create client**

### 2. Configuration de Base
- **Client type**: OpenID Connect
- **Client ID**: `unionflow-mobile`
- **Name**: `UnionFlow Mobile App`
- **Description**: `Application mobile UnionFlow avec authentification OIDC`

### 3. Configuration Capability
- **Client authentication**: OFF (Public client pour mobile)
- **Authorization**: OFF (pas besoin pour l'app mobile)
- **Standard flow**: ON (Authorization Code Flow)
- **Direct access grants**: OFF (pas recommandé pour mobile)
- **Implicit flow**: OFF (deprecated)
- **Service accounts roles**: OFF

### 4. Configuration Login Settings
- **Root URL**: `com.unionflow.mobile://`
- **Home URL**: `com.unionflow.mobile://home`
- **Valid redirect URIs**: 
  - `com.unionflow.mobile://login-callback`
  - `com.unionflow.mobile://login-callback/*`
- **Valid post logout redirect URIs**:
  - `com.unionflow.mobile://logout-callback`
  - `com.unionflow.mobile://logout-callback/*`
- **Web origins**: `+` (pour permettre CORS depuis l'app)

### 5. Configuration Advanced Settings
- **Access Token Lifespan**: 15 minutes
- **Client Session Idle**: 30 minutes
- **Client Session Max**: 12 hours
- **Proof Key for Code Exchange Code Challenge Method**: S256 (PKCE pour sécurité mobile)

### 6. Configuration des Scopes
Dans **Client scopes**, s'assurer que les scopes suivants sont assignés:
- **openid** (Default)
- **profile** (Default)
- **email** (Default)
- **roles** (Default)

### 7. Configuration des Mappers
Ajouter des mappers personnalisés si nécessaire:

#### Mapper: audience
- **Name**: audience
- **Mapper Type**: Audience
- **Included Client Audience**: unionflow-server
- **Add to access token**: ON

#### Mapper: roles
- **Name**: client-roles
- **Mapper Type**: User Client Role
- **Client ID**: unionflow-server
- **Token Claim Name**: resource_access.unionflow-server.roles
- **Add to access token**: ON

### 8. Test de Configuration

#### Test 1: Authorization URL
```
http://localhost:8180/realms/unionflow/protocol/openid-connect/auth?client_id=unionflow-mobile&redirect_uri=com.unionflow.mobile://login-callback&response_type=code&scope=openid%20profile%20email%20roles&code_challenge=CHALLENGE&code_challenge_method=S256
```

#### Test 2: Token Exchange
```bash
curl -X POST "http://localhost:8180/realms/unionflow/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&client_id=unionflow-mobile&code=AUTHORIZATION_CODE&redirect_uri=com.unionflow.mobile://login-callback&code_verifier=VERIFIER"
```

### 9. Configuration Android (android/app/src/main/AndroidManifest.xml)
```xml
<activity
    android:name=".MainActivity"
    android:exported="true"
    android:launchMode="singleTop"
    android:theme="@style/LaunchTheme">
    
    <!-- Intent filter pour les redirections OAuth -->
    <intent-filter android:autoVerify="true">
        <action android:name="android.intent.action.VIEW" />
        <category android:name="android.intent.category.DEFAULT" />
        <category android:name="android.intent.category.BROWSABLE" />
        <data android:scheme="com.unionflow.mobile" />
    </intent-filter>
    
    <!-- Intent filter standard -->
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
</activity>
```

### 10. Configuration iOS (ios/Runner/Info.plist)
```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
        <key>CFBundleURLName</key>
        <string>com.unionflow.mobile</string>
        <key>CFBundleURLSchemes</key>
        <array>
            <string>com.unionflow.mobile</string>
        </array>
    </dict>
</array>
```

### 11. Validation de la Configuration

#### Vérifications à effectuer:
1. ✅ Client créé avec le bon type (Public)
2. ✅ Redirect URIs configurées correctement
3. ✅ PKCE activé (S256)
4. ✅ Scopes appropriés assignés
5. ✅ Mappers de rôles configurés
6. ✅ Configuration mobile (Android/iOS) ajoutée

#### Tests fonctionnels:
1. **Test d'autorisation**: L'app peut ouvrir le navigateur pour l'auth
2. **Test de callback**: L'app reçoit le code d'autorisation
3. **Test de token**: L'app peut échanger le code contre des tokens
4. **Test d'API**: L'app peut appeler les APIs backend avec le token

### 12. Sécurité Mobile

#### Bonnes pratiques implémentées:
- **PKCE**: Protection contre l'interception du code d'autorisation
- **Client Public**: Pas de secret stocké dans l'app
- **Deep Links sécurisés**: Schéma d'URL spécifique à l'app
- **Token sécurisé**: Stockage dans FlutterSecureStorage
- **Refresh automatique**: Gestion transparente de l'expiration

## Résultat Attendu
- ✅ Authentification OIDC fonctionnelle depuis l'app mobile
- ✅ Tokens JWT valides pour les appels API backend
- ✅ Gestion automatique du refresh des tokens
- ✅ Déconnexion propre avec invalidation côté Keycloak