# OAuth Client Management

## Creating OAuth Clients

### Step-by-Step: Create an OAuth Client

```
Access Path:
Admin → Integrations → OAuth → Add client
OR
Menu → IT and Integrations → OAuth → Add client

Procedure:

1. Click "Add Client" Button
   └─ "Add New Client" page appears

2. Enter Application Name (Required)
   ├─ Your application's display name
   ├─ Example: "Salesforce Integration Service"
   ├─ Visible in admin dashboard
   └─ Visible in authorization screens

3. Enter Description (Optional)
   ├─ What the application does
   ├─ Example: "Syncs Salesforce contacts to Genesys every 30 minutes"
   ├─ Helpful for documentation
   └─ Visible in admin UI

4. Select Grant Type(s)
   ├─ Choose one or more:
   │  ├─ Client Credentials (service-to-service)
   │  ├─ Code Authorization / PKCE (web/mobile apps)
   │  ├─ Token Implicit Grant (DEPRECATED - don't use)
   │  └─ SAML2 Bearer (enterprise SSO)
   │
   ├─ Can select multiple grant types
   ├─ Each grant type has specific settings
   └─ Note: Cannot select Implicit after March 2026

5. Click "Next" Button
   └─ Proceed to grant-specific configuration

6. Grant-Specific Configuration:

   For Client Credentials:
   ├─ Assign Roles (Required)
   │  ├─ Select minimum roles needed
   │  ├─ Available roles listed
   │  ├─ Application will have these permissions
   │  └─ Note: Must have roles in your profile to assign
   │
   ├─ Assign Divisions
   │  ├─ Required for role assignment
   │  ├─ Roles scoped to divisions
   │  ├─ Default: Home Division
   │  └─ Update to appropriate divisions
   │
   └─ Token Duration
      ├─ Configurable: 300-172,800 seconds
      ├─ Default: 3600 seconds (1 hour)
      ├─ SCIM special: up to 450 days
      └─ Your choice based on use case

   For Authorization Code / PKCE:
   ├─ Token Duration
   │  ├─ Configurable: 300-172,800 seconds
   │  ├─ Default: 3600 seconds (1 hour)
   │  └─ Recommended: 18 hours (64,800 seconds)
   │
   ├─ Authorized Redirect URIs (Required)
   │  ├─ Up to 125 URIs
   │  ├─ One per line
   │  ├─ Must use HTTPS
   │  ├─ Example: https://yourapp.com/callback
   │  ├─ Example: https://yourapps.com/auth
   │  ├─ Example: http://localhost:3000/callback (dev)
   │  ├─ Loopback: http://localhost/ (any port)
   │  └─ MUST be exact match (case-sensitive)
   │
   └─ Scopes (Required)
      ├─ Click "Scope" button
      ├─ Select minimum scopes needed
      ├─ Space-separated in requests
      ├─ Example: "conversations:readonly users:readonly"
      └─ Recommended: Least privilege principle

7. Click "Next" Button
   └─ Review configuration

8. Review & Save
   ├─ Verify all settings
   ├─ Check OAuth name
   ├─ Confirm grant type(s)
   ├─ Verify scopes correct
   └─ Click "Save"

9. Client Created Successfully
   ├─ System generates Client ID
   ├─ System generates Client Secret
   ├─ IMPORTANT: Copy secret immediately!
   └─ Secret cannot be retrieved later

10. Display Confirmation
    ├─ Client Name: Your application name
    ├─ Client ID: Unique identifier (public)
    ├─ Grant Types: Selected methods
    ├─ Scopes: Requested permissions
    ├─ Created By: Your username
    ├─ Created Date: Timestamp
    └─ Client Secret: (hidden after creation)

11. Finish
    └─ Client ready to use

Typical Client Example:

Name: Salesforce Contact Sync
Grant Type: Client Credentials
Roles: External Contact Manager, Agent
Divisions: Home Division
Token Duration: 86400 (1 day)
Scopes: externalcontacts:manage
Created: 2026-03-13
```

---

## Client Secret Management (Critical - March 2026 Change)

```
⚠️ IMPORTANT SECURITY UPDATE (March 2026)

Previous Behavior:
├─ Client secret visible in admin UI anytime
├─ Could view secret for existing clients
├─ Increased exposure risk
└─ Security concern

Current Behavior (March 2026):
├─ Client secret only shown at creation
├─ Cannot view secret after creation
├─ Must copy immediately when created
├─ Cannot retrieve via API
└─ Enhanced security

Action Required at Client Creation:

1. When Client Created:
   ├─ Page displays client secret
   ├─ Only time you see it
   └─ Immediately copy and store

2. Copy Secret:
   ├─ Click "Copy" button
   ├─ OR manually select and copy
   └─ Keep safe!

3. Store Secret Securely:
   ├─ Secure vault (recommended)
   ├─ Environment variables
   ├─ NOT in code
   ├─ NOT in git repository
   ├─ NOT in logs
   └─ Encrypted storage

4. Acknowledge:
   ├─ Checkbox: "I have copied and stored the secret"
   ├─ Verify before checking
   └─ Only way to proceed

5. If You Lose It:
   ├─ Cannot retrieve from UI
   ├─ Click "Generate new secret"
   ├─ New secret replaces old
   ├─ Old secret no longer works
   └─ Update application immediately

Secure Storage Solutions:

HashiCorp Vault:
├─ Enterprise secret management
├─ Encryption, rotation, audit
├─ Recommended: Production environments
└─ Access via API

AWS Secrets Manager:
├─ AWS-native secret storage
├─ Encryption, rotation, audit
├─ Recommended: AWS environments
└─ IAM-based access control

Azure Key Vault:
├─ Azure-native solution
├─ Encryption, versioning
├─ Recommended: Azure environments
└─ RBAC access control

Environment Variables (Dev Only):
├─ .env file (development)
├─ Never commit to git
├─ NOT for production
├─ Simple for local development
└─ Use .gitignore

Docker Secrets:
├─ Container orchestration
├─ Swarm/Kubernetes
├─ Encrypted storage
└─ Recommended: Container deployments

Never Store:
❌ In application code
❌ In git repository
❌ In version control
❌ In logs
❌ In configuration files
❌ In plain text
❌ In comments
❌ In documentation
```

---

## OAuth Client Security

```
Security Best Practices:

Secret Rotation:

Timeline:
├─ Rotate monthly minimum
├─ Before employee departures
├─ After any exposure
├─ If suspected compromise
└─ Automated via CI/CD

Process:

1. Generate New Secret:
   ├─ Click "Generate new secret"
   ├─ Confirm action
   └─ New secret displayed once

2. Update Application:
   ├─ Update configuration
   ├─ Dual-use period: old + new both work
   ├─ Monitor for errors
   └─ Verify new secret works

3. Verify Working:
   ├─ Test authentication
   ├─ Check logs for success
   ├─ No 401 errors
   └─ All requests working

4. Remove Old Secret:
   ├─ Old automatically stops working
   ├─ After brief dual-use period
   ├─ No action needed
   └─ Can't revert to old

Audit Logging:

Log These Events:
├─ OAuth client created
├─ Secret regenerated
├─ Scopes added/removed
├─ Roles assigned/removed
├─ Client deleted
├─ Access failures
└─ Unusual activity

What to Log:
├─ Timestamp
├─ Admin user
├─ Action taken
├─ Client affected
├─ Result (success/failure)
└─ NOT the secret itself

Monitoring:

Monitor For:
├─ Unexpected client creation
├─ Secret rotation outside schedule
├─ Failed authentication attempts
├─ Unusual scope usage
├─ Access pattern changes
├─ Clients not used regularly
└─ Suspicious activity

Permissions:

Who Can Create Clients?
├─ Admin users with "oauth:client:add" permission
├─ Typically: Super Admin, OAuth Admin role
└─ Verify in your organization

Who Can View Clients?
├─ Admin users
├─ Users with "oauth:client:view" permission
└─ Consider minimizing access

Who Can Delete Clients?
├─ Admin users
├─ OAuth Admin role
└─ Approval process recommended

Compliance Requirements:

HIPAA:
├─ Requires MFA for admin access
├─ 15-minute idle timeout enforced
├─ Audit logging required
└─ Client rotation documented

PCI-DSS:
├─ Secure secret storage required
├─ No hardcoded secrets
├─ Regular rotation required
└─ Access control required

SOC 2:
├─ Audit trails for all changes
├─ Access control enforcement
├─ Change management process
└─ Incident response documented

GDPR:
├─ Data processing log required
├─ Right to access supported via API
├─ Data retention policies
└─ Deletion/export capabilities
```

---

## OAuth Client Lifecycle

```
Stages:

1. Creation
   ├─ Admin creates client
   ├─ Scopes assigned
   ├─ Roles assigned (if Client Credentials)
   ├─ Secret generated
   └─ Client ID provided

2. Configuration
   ├─ Redirect URIs registered (if Auth Code)
   ├─ Scopes finalized
   ├─ Token duration set
   └─ Roles/divisions confirmed

3. Usage
   ├─ Applications authenticate with client
   ├─ Users authorize app (if Code grant)
   ├─ Tokens issued and used
   ├─ API calls made
   └─ Regular operations

4. Monitoring
   ├─ Track usage patterns
   ├─ Monitor authentication success
   ├─ Alert on anomalies
   ├─ Quarterly scope review
   └─ Annual security audit

5. Maintenance
   ├─ Rotate secrets monthly
   ├─ Update scopes as needed
   ├─ Verify still in use
   ├─ Remove unused clients
   └─ Document changes

6. Deactivation
   ├─ Determine if still needed
   ├─ Plan removal
   ├─ Notify application owners
   ├─ Provide replacement if needed
   └─ Allow migration period

7. Deletion
   ├─ Remove old client
   ├─ Tokens immediately invalid
   ├─ Applications get 401 errors
   ├─ Audit log records deletion
   └─ Cannot be recovered

Timeline:

Creation → Configuration → Usage → Monitoring → Maintenance → Deactivation → Deletion
0 days    1 day          Day 1+     Day 30+      Day 30+        Day 365+        Day 380+
```

---

## Common OAuth Client Configurations

```
Configuration 1: Web Application (Node.js + React)

Grant Type: Authorization Code
Redirect URIs:
├─ https://yourapp.com/callback
├─ https://yourapp.com/auth
└─ http://localhost:3000/callback (dev)

Scopes:
├─ conversations:readonly
├─ users:readonly
└─ presence:manage

Token Duration: 3600 (1 hour)

Use Case:
├─ User logs in via browser
├─ Backend handles token exchange
├─ Backend stores refresh token
└─ User can revoke access anytime


Configuration 2: Service Integration (Salesforce Sync)

Grant Type: Client Credentials
Roles:
├─ External Contact Manager
└─ Scheduler (if needed)

Divisions: Home Division

Scopes:
├─ externalcontacts:manage
├─ users:readonly
└─ scheduling:readonly

Token Duration: 86400 (1 day)

Use Case:
├─ Automated sync service
├─ No user interaction
├─ Runs on schedule
└─ Application acts as itself


Configuration 3: Mobile App with Backend

Grant Type: Authorization Code + PKCE
Redirect URIs:
├─ myapp://oauth/callback
├─ https://myapp.com/callback
└─ http://localhost:3000/callback (dev)

Scopes:
├─ conversations:readonly
├─ conversations:call:control
├─ users:readonly
└─ presence:manage

Token Duration: 3600 (1 hour)

Use Case:
├─ Mobile app user login
├─ PKCE for public client security
├─ Backend stores refresh token
└─ App cannot store client_secret


Configuration 4: Single-Page Application (SPA)

Grant Type: Authorization Code + PKCE
Redirect URIs:
├─ https://yourapp.com/
├─ https://yourapp.com/callback
└─ http://localhost:3000/ (dev)

Scopes:
├─ conversations:readonly
├─ users:readonly
└─ presence:manage

Token Duration: 3600 (1 hour)

Use Case:
├─ JavaScript SPA
├─ No backend (serverless)
├─ PKCE prevents code interception
├─ Tokens stored in memory only


Configuration 5: Bot/Virtual Agent

Grant Type: Client Credentials
Roles:
├─ Agent
└─ Virtual Agent (if available)

Divisions: Home Division

Scopes:
├─ conversations:readonly
├─ conversations:external:contact:add
├─ knowledge:readonly
└─ users:readonly

Token Duration: 86400 (1 day)

Use Case:
├─ Chatbot integration
├─ No user context
├─ Reads knowledge base
└─ Fully automated


Configuration 6: Admin Tool/Dashboard

Grant Type: Authorization Code
Redirect URIs:
├─ https://admin.yourcompany.com/callback
└─ http://localhost:8080/callback (dev)

Scopes:
├─ users:manage
├─ roles:manage
├─ oauth:client:manage
└─ admin:org:manage

Token Duration: 3600 (1 hour)

Use Case:
├─ Admin portal
├─ Full management capabilities
├─ User authentication
└─ Administrative access control
```

---

## Troubleshooting OAuth Clients

```
Problem: Client Creation Fails

Check:
├─ Permission: Do you have oauth:client:add?
├─ Roles: Do you have the roles you're assigning?
├─ Scopes: Are scope names spelled correctly?
└─ Divisions: Do divisions exist?

Solution:
├─ Request oauth:client:add permission
├─ Use roles you have assigned
├─ Check scope names in API Explorer
└─ Use existing divisions


Problem: Client Secret Lost/Forgotten

Cannot Retrieve:
├─ Old secret: Cannot view (security feature)
├─ No recovery method
├─ No admin override
└─ Design for security

Solution:
├─ Generate new secret
├─ Update application
├─ Delete old client if not needed
└─ Document in future

Steps:
1. Click "Generate new secret"
2. Copy new secret
3. Update application config
4. Test authentication
5. Verify working


Problem: 401 Unauthorized on API Calls

Possible Causes:
├─ Token expired: Get fresh token
├─ Token revoked: Authenticate again
├─ Client credentials wrong: Check spelling
├─ Client no longer exists: Recreate
└─ Secret wrong: Regenerate

Troubleshooting:
1. Check token hasn't expired
2. Try authenticating again (fresh token)
3. Verify client_id and client_secret spelling
4. Check client exists in Admin UI
5. If regenerated secret, update application
6. Monitor logs for pattern


Problem: Scopes Not Working

User Still Can't Access API:

Causes:
├─ Wrong scope name
├─ User missing permission
├─ Token doesn't have scope
├─ Both scope and permission needed
└─ Other 403 reason

Check:
1. API Explorer: What scope required?
2. Token: Does it have that scope?
3. User: Does user have role permission?
4. Both: Scope AND permission needed
5. 403 error: One or both missing


Problem: Application Not Working After Update

Something Changed:

Check:
├─ Secret regenerated? Update app config
├─ Scopes changed? Users must re-authorize
├─ Roles changed? Token might lack permission
├─ Token duration changed? Should still work
└─ Redirect URI changed? Registration needed

Fix:
├─ If secret: Update app immediately
├─ If scopes: Get new token (user re-auth)
├─ If roles: Assign correct roles
└─ If URI: Re-register in Admin UI
```

---

## Best Practices: OAuth Client Management

```
Security:
□ Store secrets in secure vault
□ Rotate monthly minimum
□ Never commit to git
□ Use environment variables
□ Encrypt at rest and in transit
□ Audit all changes
□ Monitor for anomalies
□ Principle of least privilege

Operations:
□ Document each client's purpose
□ Keep contact info for app owner
□ Review quarterly
□ Remove unused clients
□ Plan secret rotation schedule
□ Test after any changes
□ Verify working regularly
□ Monitor token usage

Compliance:
□ Meet HIPAA requirements
□ Meet PCI-DSS requirements
□ Meet SOC 2 requirements
□ Document compliance steps
□ Keep audit logs
□ Review permissions quarterly
□ Maintain change log
□ Plan for incidents
```

---

## Key Takeaways: Chapter 6

- **Admin-Only Access** - Only admins can create OAuth clients
- **Secret View-Once** - Client secret only shown at creation (March 2026 change)
- **Secure Storage Required** - Use vault, not code/git/environment
- **Monthly Rotation** - Standard practice for secret updates
- **Dual Grant Types** - Can select multiple grant types per client
- **Role & Scope** - Both required for Client Credentials
- **Redirect URIs** - Must be exact match (case-sensitive)
- **Audit Everything** - Log client creation, secret rotation, deletions

---

## Interview Prep: OAuth Client Management

| Question | Answer |
|---|---|
| Where create OAuth client? | Admin → Integrations → OAuth → Add client |
| Who can create? | Users with oauth:client:add permission |
| Client secret visibility? | Only shown once at creation (March 2026 change) |
| If secret lost? | Generate new secret, update application |
| Secret storage? | Secure vault (HashiCorp, AWS, Azure) |
| Secret rotation? | Monthly minimum, before departures, after exposure |
| Redirect URIs? | Up to 125, must be HTTPS, exact match required |
| Scopes required? | Yes, principle of least privilege |
| Token duration? | Default 1 hour, configurable 300-172,800 seconds |
| Client deletion? | Immediate, tokens invalid, can't recover |

---

## Document Version
**Chapter**: 6 of 8  
**Last Updated**: March 2026  
**Status**: Current with OAuth 2.0 standards  
**Scope**: Client creation, management, security