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:

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:

{
  "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

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