Re_Backend/docs/OKTA_USERS_API_INTEGRATION.md

# Okta Users API Integration

## Overview

The authentication service now uses the Okta Users API (`/api/v1/users/{userId}`) to fetch complete user profile information including manager, employeeID, designation, and other fields that may not be available in the standard OAuth2 userinfo endpoint.

## Configuration

Add the following environment variable to your `.env` file:

```env
OKTA_API_TOKEN=your_okta_api_token_here
```

This is the SSWS (Server-Side Web Service) token for Okta API access. You can generate this token from your Okta Admin Console under **Security > API > Tokens**.

## How It Works

### 1. Primary Method: Okta Users API

When a user logs in for the first time:

1. The system exchanges the authorization code for tokens (OAuth2 flow)
2. Gets the `oktaSub` (subject identifier) from the userinfo endpoint
3. **Attempts to fetch full user profile from Users API** using:
   - First: Email address (as shown in curl example)
   - Fallback: oktaSub (user ID) if email lookup fails
4. Extracts complete user information including:
   - `profile.employeeID` - Employee ID
   - `profile.manager` - Manager name
   - `profile.title` - Job title/designation
   - `profile.department` - Department
   - `profile.mobilePhone` - Phone number
   - `profile.firstName`, `profile.lastName`, `profile.displayName`
   - And other profile fields

### 2. Fallback Method: OAuth2 Userinfo Endpoint

If the Users API:
- Is not configured (missing `OKTA_API_TOKEN`)
- Returns an error (4xx/5xx)
- Fails for any reason

The system automatically falls back to the standard OAuth2 userinfo endpoint (`/oauth2/default/v1/userinfo`) which provides basic user information.

## API Endpoint

```
GET https://{oktaDomain}/api/v1/users/{userId}
Authorization: SSWS {OKTA_API_TOKEN}
Accept: application/json
```

Where `{userId}` can be:
- Email address (e.g., `testuser10@eichergroup.com`)
- Okta user ID (e.g., `00u1e1japegDV2DkP0h8`)

## Response Structure

The Users API returns a complete user object:

```json
{
  "id": "00u1e1japegDV2DkP0h8",
  "status": "ACTIVE",
  "profile": {
    "firstName": "Sanjay",
    "lastName": "Sahu",
    "manager": "Ezhilan subramanian",
    "mobilePhone": "8826740087",
    "displayName": "Sanjay Sahu",
    "employeeID": "E09994",
    "title": "Supports Business Applications (SAP) portfolio",
    "department": "Deputy Manager - Digital & IT",
    "login": "sanjaysahu@Royalenfield.com",
    "email": "sanjaysahu@royalenfield.com"
  },
  ...
}
```

## Field Mapping

| Users API Field | Database Field | Notes |
|----------------|----------------|-------|
| `profile.employeeID` | `employeeId` | Employee ID from HR system |
| `profile.manager` | `manager` | Manager name |
| `profile.title` | `designation` | Job title/designation |
| `profile.department` | `department` | Department name |
| `profile.mobilePhone` | `phone` | Phone number |
| `profile.firstName` | `firstName` | First name |
| `profile.lastName` | `lastName` | Last name |
| `profile.displayName` | `displayName` | Display name |
| `profile.email` | `email` | Email address |
| `id` | `oktaSub` | Okta subject identifier |

## Benefits

1. **Complete User Profile**: Gets all available user information including manager, employeeID, and other custom attributes
2. **Automatic Fallback**: If Users API is unavailable, gracefully falls back to userinfo endpoint
3. **No Breaking Changes**: Existing functionality continues to work even without API token
4. **Better Data Quality**: Reduces missing user information (manager, employeeID, etc.)

## Logging

The service logs:
- When Users API is used vs. userinfo fallback
- Which lookup method succeeded (email or oktaSub)
- Extracted fields (employeeId, manager, department, etc.)
- Any errors or warnings

Example log:
```
[AuthService] Fetching user from Okta Users API (using email)
[AuthService] Successfully fetched user from Okta Users API (using email)
[AuthService] Extracted user data from Okta Users API
  - oktaSub: 00u1e1japegDV2DkP0h8
  - email: testuser10@eichergroup.com
  - employeeId: E09994
  - hasManager: true
  - hasDepartment: true
  - hasDesignation: true
```

## Testing

### Test with curl

```bash
curl --location 'https://dev-830839.oktapreview.com/api/v1/users/testuser10@eichergroup.com' \
  --header 'Authorization: SSWS YOUR_OKTA_API_TOKEN' \
  --header 'Accept: application/json'
```

### Test in Application

1. Set `OKTA_API_TOKEN` in `.env`
2. Log in with a user
3. Check logs to see if Users API was used
4. Verify user record in database has complete information (manager, employeeID, etc.)

## Troubleshooting

### Users API Not Being Used

- Check if `OKTA_API_TOKEN` is set in `.env`
- Check logs for warnings about missing API token
- Verify API token has correct permissions in Okta

### Users API Returns 404

- User may not exist in Okta
- Email format may be incorrect
- Try using oktaSub (user ID) instead

### Missing Fields in Database

- Check if fields exist in Okta user profile
- Verify field mapping in `extractUserDataFromUsersAPI` method
- Check logs to see which fields were extracted

## Security Notes

- **API Token Security**: Store `OKTA_API_TOKEN` securely, never commit to version control
- **Token Permissions**: Ensure API token has read access to user profiles
- **Rate Limiting**: Be aware of Okta API rate limits when fetching user data