This document outlines the steps required to establish a secure connection between Wisq and your SAP SuccessFactors environment.

CONTENTS

1. Authentication Options Overview
2. Basic Authentication Setup
3. OAuth2 (SAML 2.0 Bearer) Setup
4. Assign Required Permissions (Role-Based Permissions)
5. Confirm API Endpoint (Base URL)
6. Secure Credential Transmission
7. Final Checklist

1. Authentication Options Overview

Wisq supports two authentication methods:

🔐 Option 1 — Basic Authentication

• Uses dedicated integration username + password

✅ Option 2 — OAuth2 (SAML 2.0 Bearer)

• Uses enterprise-grade assertion-based authentication
• Requires registering an OAuth client in SuccessFactors using a certificate provided by Wisq
• Wisq handles token management — no ongoing action required after setup

2. Basic Authentication Setup

Follow these steps to setup the access required for a connection using Basic Authentication:

2.1 Required Credentials

2.2 Create a Dedicated Integration User

We strongly recommend creating a dedicated technical user rather than using a personal admin account.

1. Log into Admin Center.
2. Create a new integration user per your organization's standard process for technical or API accounts.
3. Assign a strong, system-generated password.
4. Ensure password expiration policies will not interrupt the integration.

If your organization requires periodic credential rotation, please notify Wisq before rotating so the connection can be updated without downtime.

3. OAuth2 (SAML 2.0 Bearer) Setup

Wisq uses a platform-managed SAML Bearer assertion flow.

1. Wisq provides you with a public X.509 certificate.
2. You register an OAuth client in SuccessFactors using that certificate.
3. You send Wisq the resulting configuration details (API Key, Company ID, User ID).
4. Wisq uses its private key to generate signed SAML assertions and exchange them for short-lived access tokens automatically.

No signing keys or certificates need to be shared back to Wisq — Wisq already holds the corresponding private key.

3.1 Overview of Required Information

To configure OAuth2, Wisq requires the following:

3.2 Obtain the Wisq Certificate

Before registering an OAuth client in SuccessFactors, you need the Wisq public certificate. This will be sent by the Wisq Agent Operations team.

3.3 Register an OAuth2 Client Application

1. Log into SAP SuccessFactors as an administrator.
2. Navigate to: Admin Center → Manage OAuth2 Client Applications (You can also search "Manage OAuth2 Client Applications" in Action Search.)
3. Click Register Client Application.
4. Enter the following:
   • Application Name: Wisq Integration (or similar)
   • Application URL: Enter any valid HTTPS URL (e.g., https://www.wisq.com). This field is required by SuccessFactors but is not used in the integration flow.
   • Bind to Users: Enable this option and enter the User ID of the dedicated integration user (see Section 4 for permissions setup).
5. In the X.509 Certificate field, paste the contents of the certificate provided by Wisq (obtained in Step 2.2). Do not click "Generate X.509 Certificate" — use the Wisq-provided certificate instead.
6. Click Register.
7. After registration, the API Key (Client ID) is displayed. Copy and save this value.

Send the following to Wisq (see Section 6 for secure transmission):

• API Key (Client ID)
• User ID bound to the OAuth client
• Company ID (found under Profile menu → "Show Version Information")
• Base URL (see Section 5)

3.4 How Authentication Works After Setup

Once configured, Wisq manages the authentication lifecycle automatically:

1. Wisq generates a signed SAML assertion using its private key, your Company ID, and User ID.
2. The assertion is sent to your SuccessFactors token endpoint along with the API Key.
3. SuccessFactors validates the assertion against the registered certificate and returns a short-lived access token.
4. Wisq uses the access token for API requests and automatically generates new assertions when tokens expire.

No ongoing action is required from your team unless the OAuth client registration is modified or the integration user's permissions change.

4. Assign Required Permissions — OAuth2 or Basic Authentication

Regardless of authentication method, the integration user (or OAuth principal) must have appropriate Role-Based Permissions (RBP).

Step 4.1 — Create a Permission Role

1. Navigate to: Admin Center → Manage Permission Roles
2. Create a new role (recommended name: Wisq API Role).
3. Click Permission… to open the permission editor.

Step 4.2 — Grant API Permissions

Under Administrator Permissions → Manage Integration Tools, enable:

• ✅ Allow Admin to Access OData API

This is the permission that unlocks API access and is commonly missed during setup.

Additionally, grant read access to:

• Employee Data
• People Profile fields required by the integration
• Any additional modules within the agreed integration scope

We recommend least-privilege access aligned to the integration requirements.

Step 4.3 — Assign Role to Integration User

1. Navigate to: Admin Center → Manage Permission Groups
2. Create a group that includes only the Wisq integration user.
3. Assign the Wisq API Role to this group.

5. Confirm API Endpoint (Base URL)

Provide the base domain only:

<https://apiXX.successfactors.com>

Do not include /odata/v2/ — Wisq appends API paths internally.

How to find your API server

There is no direct way to retrieve the API URL from within the SuccessFactors UI. To determine your API server:

1. Match your login subdomain. If you log in at performancemanager4.successfactors.com, your API server is likely api4.successfactors.com.
2. Refer to SAP's published API server list. SAP maintains a list of API server URLs by data center in KBA 2215682.
3. Confirm with your SAP consultant if you are unsure which data center hosts your instance.

For OAuth2, the Token URL uses the same data center. For example:

Base URL:  <https://api4.successfactors.com>
Token URL: <https://api4.successfactors.com/oauth/token>

6. Secure Credential Transmission

Because this integration involves privileged access, credentials must be transmitted securely.

For OAuth2 setup, the information you send (API Key, User ID, Company ID, Base URL) does not include any signing keys or passwords. These values are lower-sensitivity than raw credentials, but should still be transmitted securely as they define the scope of API access.

For Basic Authentication, you are transmitting a username and password. Please use one of the secure methods below.

✅ Preferred Method: Encrypted Email

Examples:

• Proton Mail
• Microsoft Purview Message Encryption
• Mimecast Secure Messaging

Send to your Wisq Agent Strategist contact.

Subject line:

[Company Name] – SuccessFactors Integration Credentials (Encrypted)

Acceptable Alternatives

• Secure password managers (1Password, Bitwarden, etc.)
• Secure file transfer portal
• Enterprise encrypted messaging platform

❌ Please do not send credentials in plain text email, chat platforms, or ticket systems.

Final Checklist

Basic Authentication

• [ ] Integration user created
• [ ] "Allow Admin to Access OData API" permission enabled
• [ ] Required RBP access granted (least privilege)
• [ ] Base URL confirmed (base domain only)
• [ ] Credentials transmitted securely to Wisq

OAuth2 (SAML 2.0 Bearer)

• [x] Wisq certificate obtained (Step 3.2)
• [ ] OAuth client registered in SuccessFactors using Wisq certificate (Step 3.3)
• [ ] API Key (Client ID) recorded
• [ ] Integration user created and User ID recorded
• [ ] Company ID recorded
• [ ] "Allow Admin to Access OData API" permission enabled
• [ ] Required RBP access granted (least privilege)
• [ ] Base URL confirmed (base domain only)
• [ ] Configuration details transmitted securely to Wisq

Need Assistance?

If your IT team would like support during configuration, Wisq's Agent Operations team is happy to join a working session.

Confidential — For Client IT Teams Only