authentikate/docs/guide/applications.md

# Managing Applications

Learn how to create and manage OAuth applications in AuthentiKate.

## Creating Applications

### Via Web Interface

1. **Navigate** to **Applications** in the admin panel
2. **Click** "Create Application" 
3. **Fill in** the application details:
   - **Name**: Display name for your application
   - **Redirect URI**: OAuth callback URL
   - **Icon**: Optional icon URL for the application
4. **Save** the application

### Application Details

Each application gets:
- **Unique Client ID**: Public identifier for your application
- **Client Secret**: Private key for token exchange
- **Redirect URI**: Where users return after authentication

::: warning
Keep your Client Secret secure! It should never be exposed in client-side code.
:::

## Application Templates

AuthentiKate includes templates for popular applications:

### Available Templates
- **Grafana**: Analytics and monitoring
- **Nextcloud**: File sharing and collaboration  
- **Proxmox**: Virtualization management
- **Portainer**: Docker container management
- **GitLab**: Git repository hosting

Templates automatically configure:
- Correct redirect URI patterns
- Appropriate application icons
- Common configuration settings

## OAuth Configuration

### Client Credentials
```yaml
Client ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
Client Secret: 40-character-random-string
```

### Endpoints
Your applications will use these endpoints:
- **Authorization**: `/oauth/authorize`
- **Token**: `/oauth/token` 
- **User Info**: `/oauth/userinfo`
- **JWKS**: `/.well-known/jwks.json`

### Supported Features
- **Authorization Code Flow**: Standard OAuth2 flow
- **PKCE**: Enhanced security for public clients
- **JWT Tokens**: Signed with RSA256
- **Refresh Tokens**: Long-lived token renewal

## Security Best Practices

### Redirect URI Validation
- Use exact URI matching
- Always use HTTPS in production
- Avoid wildcard redirects

### Client Secret Management
- Store secrets securely
- Rotate secrets regularly
- Use different secrets per environment

### Token Handling
- Validate token signatures
- Respect token expiration
- Implement proper logout

## Common Integration Patterns

### Server-Side Applications
Best for applications that can securely store client secrets:

```javascript
// Example: Node.js application
const config = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  authorizationURL: 'https://auth.yourdomain.com/oauth/authorize',
  tokenURL: 'https://auth.yourdomain.com/oauth/token',
  callbackURL: 'https://yourapp.com/auth/callback'
};
```

### Single Page Applications (SPA)
For client-side applications using PKCE:

```javascript
// Example: React application with PKCE
const config = {
  clientId: 'your-client-id',
  // No client secret for public clients
  authorizationURL: 'https://auth.yourdomain.com/oauth/authorize',
  tokenURL: 'https://auth.yourdomain.com/oauth/token',
  redirectUri: 'https://yourapp.com/callback',
  usePKCE: true
};
```

### Mobile Applications
Similar to SPAs, always use PKCE:

```swift
// Example: iOS Swift
let config = OIDServiceConfiguration(
    authorizationEndpoint: URL(string: "https://auth.yourdomain.com/oauth/authorize")!,
    tokenEndpoint: URL(string: "https://auth.yourdomain.com/oauth/token")!
)
```

## Testing Applications

### Manual Testing
1. **Start OAuth flow** from your application
2. **Verify redirect** to AuthentiKate
3. **Complete authentication** 
4. **Confirm successful** return to your app
5. **Check user data** is populated correctly

### Automated Testing
```bash
# Test authorization endpoint
curl "https://auth.yourdomain.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=openid"

# Test token exchange (after getting auth code)
curl -X POST https://auth.yourdomain.com/oauth/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI"
```

## Troubleshooting

### Invalid Redirect URI
**Error**: `The redirect URI is invalid`

**Solutions**:
- Verify exact URL match in application settings
- Check for trailing slashes
- Ensure HTTPS is used

### Invalid Client
**Error**: `Client authentication failed`

**Solutions**:
- Verify Client ID and Secret
- Check that application exists and is active
- Ensure secrets haven't been regenerated

### Token Validation Issues
**Error**: `Invalid token signature`

**Solutions**:
- Use JWKS endpoint for signature validation
- Verify token hasn't expired
- Check token issuer matches AuthentiKate URL

## Application Management

### Updating Applications
- **Edit** application details anytime
- **Regenerate** client secrets if compromised
- **Update** redirect URIs for new environments

### Deactivating Applications
- **Disable** applications to prevent new logins
- Existing tokens remain valid until expiration
- **Re-enable** anytime to restore access

### Monitoring Usage
View application usage in the admin panel:
- **Active tokens** per application
- **Recent authentications**
- **User access patterns**

Your applications are now ready for OAuth integration with AuthentiKate!