ADO.NET Provider for Workday

Build 24.0.9060

Creating a Custom API Client Application

Creating a Custom API Client Application

As noted in Establishing a Connection, the Workday provider does not embed Workday user or role credentials. Unless the user is using Basic authentication (which does not require authentication with an API client), you must create a custom OAuth application for them to authenticate.

This page describes:

  • how to build a custom OAuth application for standard users or Integration System Users (ISUs), and
  • how to build a custom Azure AD application for Azure AD users in an enterprise SSO environment.

Note: Because they facilitate authentication to Workday APIs, this document frequently refers to custom OAuth applications as custom API Clients.

Creating a Custom OAuth Application

Custom OAuth applications are used to connect by both Standard users and Integration System Users (ISUs) with a variety of AuthSchemes.

Standard Users

The following steps create an API Client that can be used by normal users with the OAuth authentication scheme.

Note: Be aware that Workday restricts each custom application to a single redirection URI. Therefore, if you have a mix of Desktop and Web users, you will probably need to create more than one custom application.

  1. Log into Workday.
  2. Open the Register API Client form and fill in the following fields:
    • Client Name: A name for the application.
    • Grant Type: Authorization Code.
    • Access Token Type: Bearer.
  3. Specify a Redirection URI for the custom application:
    • If this is a Desktop application: the recommendthe URI is https://localhost:33333. (If no CallbackURL is provided, the provider uses this as the redirection URI automatically.)
    • If this is a Web application, use any URI desired; for example, https://my-website.com/oauth.
  4. Configure scopes to be used with this application:
    • In the Scope section, enable the following scopes:
      • Custom Objects > System
      • Custom Objects > Integration
      • Workday REST API > Tenant Non-Configurable
    • Add any additional desired scopes for the provider to have access to. If there is any uncertainty regarding which scopes to include, all the scopes under each subsection can be enabled.
    • Enable the Include Workday Owned Scope option.
  5. Click OK.

After the application is created, Workday loads the View API Client page with all the information for the new application. Save the Client ID and Client Secret so they can be used with the OAuthClientId and OAuthClientSecret connection properties.

Standard Users with Azure AD

The following steps create an API Client that can be used by normal users with the AzureAD authentication scheme.

  1. Open the Register API Client form and fill in the following fields:
    • Cient Name: A name for the application.
    • Assertion Verification: SAML Bearer Grant.
    • Grant Type: Use Configured IdPs.
    • Access Token Type: Bearer.
  2. Enable the Allow Access to All System Users option. This option is required so that normal users can authenticate to the client, not just ISUs.
  3. Enable the Grant Administrative Consent option. This option is required so that normal users can authenticate to the client, not just ISUs.
  4. Configure scopes to be used with this application:
    • In the Scope section, enable the following scopes:
      • Custom Objects > System
      • Custom Objects > Integration
      • Workday REST API > Tenant Non-Configurable
    • Add any additional desired scopes that you want the provider to have. If there is any uncertainty regarding which scopes to include, enable all of the scopes under each subsection.
    • Enable the Include Workday Owned Scope option.
  5. Click OK.

ISUs

Facilitating ISU authentication involves two steps:

  1. Create an API client that can authenticate via OAuth 2.0.
  2. Register the ISU with the API client.

Create the API Client

The following steps create an API Client that can be used by ISUs with the OAuth authentication scheme.

  1. Log into Workday.
  2. Open the Register API Client for Integrations form.
  3. At the Client Name field, enter a name for the application.
  4. Configure scopes to be used with this application:
    • In the Scope section, enable the following scopes:
      • Custom Objects > System
      • Custom Objects > Integration
      • Workday REST API > Tenant Non-Configurable
    • Add any additional desired scopes for the provider to have access to. If there is any uncertainty regarding which scopes to include, all the scopes under each subsection can be enabled.
    • Enable the Include Workday Owned Scope option.
  5. Click OK.

After the application is created, Workday loads the View API Client page with all the information for the new app. Save the Client ID and Client Secret so they can be used with the OAuthClientId and OAuthClientSecret connection properties.

Register an ISU with the API Client

An API Client for Integrations has to be registered with a specific ISU before that ISU can use the API Client to authenticate. If you do not already have an ISU, you need to create one first. (See Creating an Integration System User (ISU).)

The following steps register an ISU with the API client you just created.

  1. Log into Workday.
  2. Navigate to the View API Client page for the API Client you just created.
  3. Next to the API Client name, click the ellipsis (...).
  4. Select Choose API Client > Manage Refresh Tokens for Integrations. A pop-up menu displays.
  5. Under Workday Account, find and select the ISU you want to register with the API Client.
  6. Click OK.
  7. Enable the Generate New Refresh Token option.
  8. Click OK.

After the ISU is registered, Workday load sa page showing the Refresh Token for the ISU. Save this value so it can be used with the OAuthRefreshToken property.

ISUs with OAuth JWT

Facilitating ISU authentication with OAuth JWT involves two steps:

  1. Create and register a certificate that the provider can use.
  2. Create the API client.

Create and Register a Certificate

Before you begin, you must have a certificate registered with Workday that the provider can use. The certificate, which should use PCKS12 (.pfx) format, can be created using tools like OpenSSL or Java keytool.

To register the certificate in Workday:

  1. Open the Create x509 Public Key form.
  2. Enter a name for the key in Name. This name will be used later when adding the certificate to the API Client.
  3. Copy and paste the public key into Certificate. The certificate must be encoded in PEM format.

Create the API Client

After the certificate has been registered, you are ready to create the API Client:

  1. Open the Register API Client form and fill in the following fields:
    • Client Name: A name for the application.
    • Grant Type: JWT Bearer Grant.
    • 509 Certificate: specify the certificate you uploaded previously.
    • Access Token Type: Bearer.
  2. Configure scopes to be used with this application:
    • In the Scope section, enable the following scopes:
      • Custom Objects > System
      • Custom Objects > Integration
      • Workday REST API > Tenant Non-Configurable
    • Add any additional desired scopes for the provider to have access to. If there is any uncertainty regarding which scopes to include, all the scopes under each subsection can be enabled.
    • Enable the Include Workday Owned Scope option.
  3. Click OK.

Note: If you want to authenticate with OAuthJWT, you need to register an API Client for Integrations has to be registered with a specific ISU. After it is registered you can use the API Client to authenticate. If you do not already have an ISU, you must create one first, as described in Creating an Integration System User (ISU).

Creating a Custom Azure AD Application for SSO

Logging into Workday using Azure credentials, in an enterprise SSO environment, is a two-step process. Since provider cannot use the enterprise SSO application directly, it must use a custom OAuth application as a pass-through: the custom OAuth application asks the SSO application to log you into Workday on behalf of the provider.

Thus, authenticating with Azure Active Directory requires two applications to be configured in your Azure tenant:

  • An enterprise SSO application that is linked with Workday, so you can log into Workday using your Azure credentials. This application already exists if you are using Workday with Azure AD but requires extra configuration to work with the provider.
  • An OAuth application specific to the provider, created specifically for your Azure tenant.

Create the OAuth Application

  1. Log into the Azure Portal and navigate to the App Registrations screen.
  2. Create a New Registration and provide the following details:
    • Supported Account Types: Single Tenant. This ensures that only your users can use this application to log into Workday.
    • Redirect URI: specify Web as the platform ,and enter http://localhost:33333 as the URI.

After the application is created:

  1. Navigate to the new application's Overview screen.
  2. Record the Application Client ID. You will need to provide this value to your users.
  3. Navigate to the application's Certificates and Secrets page.
  4. Create a new Client Secret. Provide a useful description and choose whatever expiration you are comfortable with. Keep in mind that when this secret expires you must create a new secret and provide it to your users. We recommend an expiration period of 24 months.
  5. Copy the Client Secret and store it somewhere safe; Azure will not display it again after it is created.

Configure the Enterprise Application

  1. Ensure that you have the Application Client ID for the application you just created, above. (If you did not record it before, you can find it in the application's Overview section.)
  2. In the Azure Portal, navigate to the App Registrations screen.
  3. Open the SSO application's configuration page. (Note that the SSO application settings are not available from the Enterprise Applications secreen.)
  4. Open the Expose an API tab.
  5. In the Add a Scope, enter the following details:
    • Scope Name: user_impersonation.
    • Consent: Admins and Users.
    • Provide a Display Name and Display Description to be displayed to your users the first time they log in.
  6. Under Add a Client Application, at Client ID, enter the Application Client ID you copied from the OAuth application in Step 1.
  7. Enable the user_impersonation scope you just added.

Configuration Values For Your Users

After configuring the two applications, you must collect some configuration values to provide to your users. The provider uses the following to access the Azure apps so your users can sign in with them:

  • The OAuth application's Application Client ID and Client Secret.
  • The enterprise SSO application's Application ID URI. (This is usually http://www.workday.com.)
  • The Azure AD Tenant ID. To find this, go to the Azure Portal, select the Azure Active Directory page, and open the Overview tab. In most cases, this value is a GUID.

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 24.0.9060