The native Workday productivity integration connects Firstup directly to your organization’s Workday environment. Employees can view payslips, check time-off balances, view time-off requests, and submit time-off requests from the Firstup member experience.
This article outlines the setup responsibilities for you, as the Workday administrator, and Firstup.
These instructions apply to the native Workday integration, an alternative to connecting Workday through Merge. If your organization uses the Merge-based integration, refer to Enabling Workday Integration.
Before You Start
You must have a Workday administrator account with permission to:
- Register API clients.
- Create x509 public keys when using SAML Bearer authentication.
- Edit and activate business-process security policies.
Provide Firstup with your:
- API Host - Host of the Workday REST API server, taken from "Workday REST API Endpoint" on the API client (the *-services* host, without the /ccx/... path), e.g. https://impl-services1.wd12.myworkday.com. Not the host of the Workday UI.
- Tenant - Workday tenant name for this integration.
- Token Endpoint - From the Workday API client. When blank, defaults to {api_host}/ccx/oauth2/{tenant}/token.
- Workday Web URL - The Workday address employees sign in to in their browser, e.g. https://impl.wd12.myworkday.com/<tenant>. Used for the "Open Workday" link; the link is hidden when blank.
- Workday API Client ID - Workday API Client ID. Used as the OAuth client id, and as the Issuer of the SAML Bearer assertion, required for whichever authentication model is chosen.
Decide your authentication model:
- OAuth
- SAML Bearer
Depending on your chosen authentication model:
OAuth Authentication
- Workday API Client Secret - Workday API Client Secret.
- Authorization Endpoint - from the Workday API client.
- OAuth Redirect URI - Must exactly match the redirect URI registered on the Workday API client. Conventional shape: {callback_domain}/api/v1/integrations/workday_native/callback.
SAML Bearer
- SAML Service Provider UUID - UUID of the Firstup IAM SAML service provider registered for this tenant.
- Workday User ID Source - Field from Firstup used to identify the employee; mapped to the SAML assertion NameID.
Firstup configures the connection in Studio. You configure access in Workday and provide the required connection details.
Confirm feature availability and coordinate setup with your Firstup representative.
Choose an Authentication Method
The native integration supports two authentication methods. Firstup can help you choose the best option for your organization.
| Authentication method | Employee experience | Setup requirements |
|---|---|---|
| SAML Bearer | Employees access Workday information without a separate Workday login in the Firstup assistant. | You register Firstup’s signing certificate and configure a SAML Bearer API client. Each employee’s Workday User Name must also exist in a Firstup user field. |
| OAuth 2.0 Authorization Code | Employees select Connect in the Firstup assistant and sign in to Workday when they first use the integration. | You configure an Authorization Code API client and provide Firstup with the client credentials and connection details. |
Configure SAML Bearer Authentication
Obtain the Firstup Certificate
Firstup creates and provides a dedicated signing certificate for you.
Register the Certificate in Workday
- In Workday, search for and open Create x509 Public Key.
- Enter a recognizable name, such as Firstup Workday HR Signing Certificate.
- Paste the complete certificate supplied by Firstup, including the
-----BEGIN CERTIFICATE-----and-----END CERTIFICATE-----lines. - Save the public key.
Register the API Client
-
Search for and open Register API Client.
Note: You must use Register API Client. The Register API Client for Integrations task does not provide the required SAML Bearer grant.
- Configure the following settings:
| Setting | Value |
|---|---|
| Client Name | A recognizable name, such as Firstup Workday HR (SAML) |
| Client Grant Type | SAML Bearer Grant |
| Assertion Verification | The x509 certificate verification option |
| x509 Certificate | The public key created in the previous section |
| Access Token Type | Bearer |
| Allow Access to All System Users | Enabled |
| Integration System User | Blank |
| Scope (Functional Areas) |
Select the following functional areas:
|
| Allow User Delegation | Disabled |
- Confirm any additional client settings with Firstup and save the client.
- Open View API Clients, select the client, and provide Firstup with the following details through a secure channel:
- Client ID.
- Workday REST API Endpoint, using your tenant’s services host (
…-services…). - Token Endpoint.
- Workday tenant name.
- Workday web URL, if you want employees to open Workday from the integration.
- SAML Service Provider UUID.
- Workday User ID source (that identifies the employee; mapped to the SAML assertion NameID)
Confirm Employee Identifiers
SAML Bearer authentication requires a Firstup user field that contains each employee’s Workday User Name. The field must contain a value for every employee who uses the integration, and that value must match their Workday User Name exactly.
- In Workday, open the employee’s worker profile.
- Select Related Actions → Security Profile → View Workday Account.
- Identify the employee’s User Name.
- Confirm that the same value exists in one of the following Firstup fields:
- Employee ID.
- Federated identifier.
- A custom attribute, such as
workday_username.
- Tell Firstup which field contains the matching value.
Note: An employee’s Workday User Name may differ from their employee number or email address. The values must match exactly.
Configure OAuth Authentication
If you are using SAML Bearer authentication, you can skip this section.
- Obtain the OAuth redirect URI from Firstup.
- In Workday, search for and open Register API Client.
- Configure the following settings:
| Setting | Value |
|---|---|
| Client Name | A recognizable name, such as Firstup Workday HR (OAuth) |
| Client Grant Type | Authorization Code Grant |
| Access Token Type | Bearer |
| Redirection URI | The exact redirect URI supplied by Firstup |
| Non-Expiring Refresh Tokens | Enabled. If your organization requires refresh tokens to expire, disable this setting and configure the expiry period. |
| Scope (Functional Areas) |
Select the following functional areas:
|
- Save the client and record the Client Secret immediately. Workday displays the secret only once.
- Provide Firstup with the following details through a secure channel:
- Client ID and Client Secret.
- Workday REST API Endpoint, using your tenant’s services host (
…-services…). - Token Endpoint.
- Authorization Endpoint, using your Workday web interface host rather than the services host.
- Workday tenant name.
- Workday web URL, if required.
- OAuth redirect URI.
- The Workday client’s Redirection URI must exactly match the redirect URI that Firstup configures for the integration.
- If you configure refresh tokens to expire, employees must reconnect their Workday accounts when those tokens expire.
Allow Employees to Submit Time Off Requests
This configuration applies to both authentication methods when you enable time-off submissions.
These steps are only applicable if you are enabling the write commands.
- Search for and open Edit Business Process Security Policy.
- Select Request Time Off as the business process type.
- Locate the Request Time Off (REST Service) action.
- Add the appropriate employee security group, typically Employee As Self.
- Run Activate Pending Security Policy Changes to apply the changes.
Workday requires a separate permission for REST service submissions. Employees may already have permission to request time off in Workday while lacking permission to submit requests through the integration.
Firstup Configuration
After you complete the Workday setup, Firstup:
- Configures the Workday connection and authentication details in Studio.
- Selects the matching employee identifier field for SAML Bearer authentication.
- Enables the agreed commands.
- Enables the integration for your community.
Verify the Integration
Work with Firstup to verify the connection using a test employee account:
- Ask the test employee to open the Firstup assistant and select Time Off Balance.
- For OAuth authentication, ask the employee to select Connect and complete the Workday sign-in.
- Ask the employee to confirm that the integration displays their own time-off balance.
- Ask the employee to check Payslips and View Time Off Requests, where enabled.
- If your organization enables time-off submissions, ask the employee to submit an agreed test request for a future date.
- In Workday, confirm that the request appears under the correct employee.
Troubleshooting
Employees cannot connect through SAML Bearer authentication.
Work with Firstup to verify the certificate, API client settings, and Client ID.
An employee cannot access Workday information through SAML Bearer authentication.
Confirm that the selected Firstup field contains a value for the affected employee and that it exactly matches their Workday User Name. In Workday, open the employee’s worker profile and select Related Actions → Security Profile → View Workday Account to check their User Name.
Employees can view information but cannot submit time-off requests.
Verify the Request Time Off (REST Service) permission and activate pending security-policy changes.
One command returns a 403 error.
Confirm that the Workday API client has the scopes required for that command. Work with Firstup to identify and add any missing scopes. After you add scopes, employees using OAuth must reconnect their Workday accounts.
Workday displays a redirect error after OAuth sign-in.
Work with Firstup to confirm that the redirect URI registered in Workday exactly matches the URI configured for the integration.
Employees repeatedly receive a connection prompt.
Check the Workday API client’s refresh-token settings with Firstup. If refresh tokens expire too frequently, review the expiry period or enable Non-Expiring Refresh Tokens, in accordance with your organization’s requirements.
The assistant does not display Workday commands.
Contact Firstup to confirm that the integration and the required commands are enabled.
Comments
0 comments
Article is closed for comments.