# Security Best Practices

## Transport Security

### HTTPS Requirements

* **Production:** Must use `https://` for all redirect URIs
* **Development:** Can use `http://localhost` only
* Use TLS 1.2 or higher

***

## CSRF Protection

### State Parameter

The `state` parameter prevents CSRF attacks.

**Implementation:**

1. Generate random state value
2. Store in session
3. Include in authorization URL
4. Validate on callback

**Requirements:**

* Minimum 128 bits entropy
* Cryptographically random
* Single-use
* Time-limited (5-10 minutes)

***

## PKCE

### When required

PKCE is **mandatory** for:

* Single Page Applications (SPAs)
* Mobile applications
* Any public client

### How it works

1. Generate code verifier (43-128 random characters)
2. Create code challenge (SHA-256 hash of verifier)
3. Send challenge with authorization request
4. Send verifier with token exchange

***

## Token security

### Storage

| Platform | Recommended                | ❌ Avoid                     |
| -------- | -------------------------- | --------------------------- |
| Web App  | Server-side session        | Browser localStorage        |
| SPA      | Memory only                | localStorage/sessionStorage |
| iOS      | Keychain                   | UserDefaults                |
| Android  | EncryptedSharedPreferences | SharedPreferences           |

### Best practices

* Use short-lived access tokens (15-60 min)
* Implement refresh token rotation
* Always use HTTPS
* Include tokens in `Authorization` header
* Never log tokens

***

## Client secret management

{% hint style="danger" %}
**Never:**

* Commit to version control
* Embed in client-side code
* Log in application logs
* Share via email/chat
* Store in plain text
  {% endhint %}

### Secure storage

| Environment | Solution                                       |
| ----------- | ---------------------------------------------- |
| Development | Environment variables (.env)                   |
| Production  | Secret management (Vault, AWS secrets manager) |

### Rotation policy

* Regular: Every 90 days
* Incident: Immediately upon compromise
* Automated: Use secret rotation tools

***

## Monitoring

### Security events to monitor

* Failed authentication attempts
* Unusual token usage patterns
* Scope escalation attempts
* Geographic anomalies
* Rapid token refresh

### Incident response

1. Detect and assess
2. Revoke compromised credentials
3. Investigate logs
4. Rotate secrets
5. Notify affected users
6. Document incident

***

## Compliance

### Data protection

* Implement data minimization
* Provide clear privacy policies
* Enable user consent management
* Support data deletion requests
* Maintain audit logs

### Regulations

* **GDPR** (EU) - Data protection
* **CCPA** (California) - Consumer privacy
* **HIPAA** (Healthcare) - Health information
* **PCI DSS** (Payment) - Card data security

***

## Resources

### External guidelines

* [OAuth 2.0 Security Best Practices](https://tools.ietf.org/html/draft-ietf-oauth-security-topics)
* [OWASP OAuth Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/OAuth2_Cheat_Sheet.html)

### Tools

* [jwt.io](https://jwt.io) - Decode JWT tokens
* [OWASP ZAP](https://www.zaproxy.org/) - Security scanner


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://oten.gitbook.io/identity-support/user-guide/oten-workspace/applications/oten-developer/user-guides/security-best-practices.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.