This document outlines the steps required to integrate Single Sign-On (SSO) using PaidHR. It details how to register your client app, generate credentials, and leverage our backend to authenticate users and redirect them seamlessly.

Overview

The SSO integration allows users who already have a PaidHR account to be authenticated on our platform without additional login prompts. After verifying your credentials and user information, our backend generates an access token and redirects the user as an authenticated session on PaidHR.

Prerequisites

Before integrating SSO, ensure that:

PaidHR Account: The customer must have an active account on PaidHR.
Allowed Origin: The domain from which the API call is made.
Client Name: A unique name for your client application.
Logout URL (Optional): The URL to which users will be redirected after the session ends on PaidHR.

Step 1: Client App Registration

Access SSO Settings:
- Log in to your PaidHR account.
- Navigate to Settings > SSO.
Registration Page
Create a Client Application:
- Click “Create Client App.”
- Provide the following details:
  - Allowed Origin: The domain where your API requests originate.
  - Client Name: Your unique application name.
  - Email Address : The admin's email address
- Logout URL (Optional): URL to redirect users after the session ends.
Client Secret generation page
Generate Client Credentials:
- Upon registration, the system generates a Client ID and Client Secret.
- Note: The Client Secret is shown only once. You have the option to regenerate or delete the client app if needed.

Step 2: Client App Registration

After your client app is registered and you have the generated credentials, your integration process is simplified to a single redirection link.

SSO Button on Your Platform:
- Place a button (or hyperlink) on your platform that links directly to our SSO endpoint.
SSO URL Format:
- The URL includes the following query parameters:
  - email: The user's email address.
  - clientId: Your generated Client ID.
  - clientSecret: Your generated Client Secret.
For Example:
```
https://api.paidhr.com/v1/client-auth/authenticate/[email protected]&clientId=64128148569A&clientSecret=a365b965d4ab20badf3ce5aebd60d8c7b12aba90bb9e1dfccba4b9da89940c5d
```
Redirection and Authentication:
- When the user clicks the SSO button, they are redirected to the above URL.
- Our backend performs the following:
  - Credential Verification: Validates that the provided Client ID matches the Client Secret.
  - Origin Check: Confirms the request is from an allowed domain.
  - User Verification: Checks if the user email exists on PaidHR.
  - Token Generation: Generates an access token for the user.
- After successful authentication, the user is automatically logged in on the PaidHR platform with an active session.
Session Termination and Final Redirection:
- Once the session expires, users are redirected back to the originating domain or the specified Logout URL, if provided.

Error Handling

In the event of an error during the SSO process, appropriate HTTP status codes and error messages are returned. Common error scenarios include:

401 Unauthorized: Invalid credentials or unrecognized user email.
403 Forbidden: Request originating from a non-allowed domain.
400 Bad Request: Missing or invalid request parameters.

If an error occurs, the user will not be redirected and will receive an error message prompting corrective action.

Dashboard and Monitoring

Client Dashboard:
- Manage your registered client apps.
- View or regenerate client credentials.
- Delete apps if necessary.
API Usage Logs:
- Monitor API call details and SSO interactions.
- Troubleshoot errors via the detailed logs provided on your dashboard.

Conclusion

This SSO integration enables a seamless and secure authentication process by leveraging PaidHR’s backend to generate access tokens and redirect users as authenticated sessions. If you have any questions or require additional support, please consult our support documentation or contact our support team ([email protected]) directly.