Concept: External Agent ASU Considerations

The ASU client credentials that are provided after agent configuration should be used for OAuth 2.0 Authorization Code Grant Flow to enable your agent to get access during agent runtime.

When manually testing the authorization code grant flow of an external agent, use the client details and endpoint URLs provided during agent configuration as inputs for these steps:

Retrieve the authorization code by pasting this URL into a new window:
https://<providedAuthorizeEndpoint>?response_type=code&client_id=<clientID>&state=<agentName>&redirect_uri=<redirectionURI>
.
The URL redirects you to a login page where you must manually provide your user credentials that the agent will be acting on behalf of.
After successfully logging in, you're redirected to an
Allow/Deny
page where you grant the agent access to your Workday account. Select
Allow
to be redirected to your provided Redirection URI with an appended code which you can use to call the next API.
Retrieve the ASU token by creating a new request using an external API client using the authorization code provided in the previous API call.
Example: Bruno:
POST https://<providedTokenURL>
Body:grant_type=authorization_code&code=<authorizationCode>&client_id=<clientID>&client_secret=<ClientSecret>
This generates an access token and a refresh token that you can use to test calls your agent makes to Workday services.

In the body of the response back from the token endpoint, the

expires_in

parameter is expected to be returned as type Integer. In different test environments, this parameter type can differ between Integer and String, so Workday recommends that the external client is able to handle both string and int types.

When you need to update an agent definition, you can supply the same agent name, version, and provider to the POST AgentDefinition API, and it will update. If there isn't a match, Workday creates a new agent registration.

When your agent sends the request to the token endpoint using AuthCode and client credentials, both the access token and refresh tokens are created and sent back.

The access token expiry time is 3600 sec (60 min). The refresh token expiry time is 24 hr.

When an access token expires, the refresh token creates a new one.

Typical OAuth clients should only need:

Client Secret
and
Client ID
: Obtained during the agent configuration process.
Authorize Endpoint
:
https://us.agent.workday.com/auth/authorize/ <Tenant Alias>
Token Endpoint
:
https://us.agent.workday.com/auth/oauth2/<Tenant_Alias>/token
Redirect URL
: Provided by the agent developer during the agent configuration process.

The ASU Client ID and username that are provided after agent configuration should be used to perform JWT assertion and token generation.

Issuer must be the Client ID.
Subject must be the ASU username.

The x509 corresponding keypair that is required during ambient skill registration is used during agent runtime to perform JWT assertion.

Update your agent’s code so that during agent runtime, when a request is submitted to the agent, the agent checks if it has a valid access token cached. If it doesn't, or if the token is expired, we:

Create a new JWT assertion
Fetch a JWT Bearer token
Cache token for Workday API requests