Use subject delegation for long-running repetitive workflows (Class #3)

Overview

For workflows with an overall duration of more than one hour that are repetitive, use the subject delegation grant type. This allows applications to obtain on-behalf-of tokens when the primary identity is not present, supporting scheduled jobs and recurring syncs.

Security & Access Requirements

• The subject delegation grant type is not available to all applications. Your application must be reviewed and approved by the TID governance group. Usage is logged and subject to ongoing review.
• Client authentication with mTLS is required (not basic authentication), ensuring only the application with the private key can authenticate.
• DPoP is required for all token and resource requests, binding tokens to the client and request.
• Only applications that demonstrate a valid use case and follow best practices in cloud architecture, security, and data management will be considered.

When to Use This Flow

Requirements	Description
Long-running, repetitive workflows	Scheduled jobs, recurring syncs, or workflows with growing subject sets
Privileged applications	Requires approval from TID governing committee and must pass governance review. Application must show a valid use case and compliance with security and data management best practices.
Delegated access	Host and application can act on behalf of users or other apps through IAM
Accounts	Credentials generated for the subject delegation grant type must be in the context of an account. As a result, the subject delegation grant type is only available for identities that are part of an account in IAM/CDH. Accounts should be available for all identities associated with products that have been onboarded through DX.

How It Works

1. Application is approved for subject delegation by TID after governance review.
2. Privileged application obtains a certificate and uses mTLS for authentication.
3. Application requests tokens on behalf of users or other apps using the subject delegation grant type. All requests must include a DPoP proof header.
4. TID issues DPoP-bound access tokens for secure, sender-constrained access.

Note: Refresh tokens are not available for the subject-delegation grant type. A new access token must be obtained when a token expires.

Requesting Access

Request the subject delegation grant type to be enabled for your application by submitting a support request. Your request must include the following information:

• The nature of the workflow and the chain of applications involved in the workflow.
• Why the workflow should be treated as Class #3 (long and repetitive).
• A completed self-assessment to confirm your application and use case are eligible.

Before submitting a request, please thoroughly review the requirements and complete the self-assessment checklist to ensure your application is eligible for this grant type.

After submission, the TID governing committee reviews and approves the request. Applications must demonstrate a valid use case and compliance with security and data management best practices.

---

Self-Hosted vs Host Environment Applications

Feature	Self-Hosted Applications (Class #3.1)	Host Environment Applications (Class #3.2)
Deployment	Stand-alone application	Runs inside a host application’s environment
Token Request Actor	Requesting application	Host application acts on behalf of the app
Required Parameters	grant_type, subject_id, scope, account_id, client_id	grant_type, subject_id, scope, delegated_azp, account_id, client_id
Token Claims: azp	Application ID (requesting app)	Host application ID
Token Claims: act	{ “sub”: application_id }	{ “sub”: application_id } (from delegated_azp)
Use Case	Most users, direct subject delegation	Three-legged, host acts for embedded/hosted apps

For both application types, subject delegation workflows require privileged application access along with the following security mandates:

• Use the mTLS token endpoint with a TID-issued certificate.
• DPoP proof is required for all token and resource requests.

---

Self-Hosted Applications (Class #3.1)

A stand-alone application that directly uses the subject delegation grant type. This use case will apply to most users.

Token Request

Use mTLS and DPoP proof to call the /oauth/token endpoint.

• API CALL:

  • POST {mTLS endpoint}/oauth/token

• HEADER:

  • Accept: application/json
  • DPoP: {DPoP proof JWT}

• REQUEST BODY:

  • grant_type = urn:ietf:params:oauth:grant-type:subject-delegation
  • subject_id = User ID, device ID, or application ID (the subject)
  • account_id = Account ID for the subject
  • client_id = {Application ID registered in TID/IAM with subject delegation privileges}
  • scope = {Target application or API name}

mTLS token endpoints:

• Staging: https://mtls.stage.id.trimblecloud.com
• Production: https://mtls.id.trimble.com

Example Request

POST /oauth/token
Host: mtls.stage.id.trimblecloud.com
Accept: application/json
DPoP: eyJ0eXAiOiJkcG9w.....H8-u9gaK2-oIj8ipg
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:subject-delegation&subject_id=73eb11b5-87f3-4253-ad93-368a2acb4128&scope=openid profile email iam&account_id=3983a7bc-beaa-54ba-8d7e-ee640c082f3a&client_id=6783952d-12f0-4257-ac26-ce16355736c2

Token Response

The response includes the following claims:

Claim	Value
token_type	DPoP
expires_in	Token lifetime in seconds
issued_token_type	urn:ietf:params:oauth:token-type:jwt
access_token	The JWT access token
sub	subject_id
aud	Target application/API ID
azp	Application ID (the application making the token request)
act	{ "sub": application_id }
account_id	Account ID from the request
cnf	Hash of the public key (from DPoP proof)

Example Response

{
  "token_type"        : "DPoP",
  "expires_in"        : 3600,
  "access_token"      : "eyJhbG...<JWT truncated for brevity>",
  "issued_token_type" : "urn:ietf:params:oauth:token-type:jwt"
}

• To decode and verify the TID JWT Token, refer to Decode JWT.

---

Host Environment Applications (Class #3.2)

Used when the application wanting to use the subject delegation grant type is running in an environment provided by a host application. This requires a three-legged process where the host acts on behalf of the application to obtain the token for the specified subject.

Token Request

Use mTLS and DPoP proof to call the /oauth/token endpoint.

• API CALL:

  • POST {mTLS endpoint}/oauth/token

• HEADER:

  • Accept: application/json
  • DPoP: {DPoP proof JWT}

• REQUEST BODY:

  • grant_type = urn:ietf:params:oauth:grant-type:subject-delegation
  • subject_id = User ID, device ID, or application ID
  • account_id = ID of the account the subject belongs to
  • client_id = Application ID registered in TID/IAM with subject delegation privileges
  • scope = Target application or API name
  • delegated_azp = Client ID of the application the host is acting for

mTLS token endpoints:

• Staging: https://mtls.stage.id.trimblecloud.com
• Production: https://mtls.id.trimble.com

Example Request

POST /oauth/token
Host: mtls.stage.id.trimblecloud.com
Accept: application/json
DPoP: eyJ0eXAiOiJkcG9w.....H8-u9gaK2-oIj8ipg
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:subject-delegation&subject_id=73eb11b5-87f3-4253-ad93-368a2acb4128&scope=openid profile email iam&account_id=3983a7bc-beaa-54ba-8d7e-ee640c082f3a&client_id=6783952d-12f0-4257-ac26-ce16355736c2&delegated_azp=feb66b1e-f5f3-4b68-9c29-4c35752d10ea

Token Response

The response includes the following claims:

Claim	Value
token_type	DPoP
expires_in	Token lifetime in seconds
issued_token_type	urn:ietf:params:oauth:token-type:jwt
access_token	The JWT access token
sub	subject_id
aud	Target application/API ID
azp	Host application ID
act	{ "sub": application_id } (from delegated_azp)
account_id	Account ID from the request
cnf	Hash of the public key (from DPoP proof)

Example Response

{
  "token_type"        : "DPoP",
  "expires_in"        : 3600,
  "access_token"      : "eyJhbG...<JWT truncated for brevity>",
  "issued_token_type" : "urn:ietf:params:oauth:token-type:jwt"
}

• To decode and verify the TID JWT Token, refer to Decode JWT.

---

DPoP and Token Usage

• All tokens are DPoP-bound (sender-constrained).
• DPoP proof JWT must be included in each request.
• Resource servers validate DPoP proof and match the public key hash to the cnf claim in the access token.

---

Revoking the Subject Delegation Grant Type

The delegated authorization feature through the subject delegation grant type follows an opt-out model:

• By default, the subject delegation grant type is permitted for all accounts and must be specifically revoked.
• Users do not need to approve an application’s ability to use delegated authorization on their behalf.
• An application’s usage of delegated authorization is logged and visible to administrators of the user’s account.
• Administrators can revoke an application’s ability to use the subject delegation grant type for all identities in the account if they determine that the access is not appropriate.

Note

• The ability for an administrator to view and revoke access is not currently available.
• The plan is to introduce a customer-accessible portal where administrators can review delegated authorization permissions and revoke access directly.
• If an identity belongs to multiple accounts, delegated authorization may be allowed in one account and disallowed in another.

---

Best Practices & Troubleshooting

• Only use subject delegation for approved, repetitive workflows.
• Store certificates and private keys securely.
• Monitor token and certificate expiry.
• Review error responses for approval or protocol issues.

---

Related

• Asynchronous workflows with Trimble ID
• On Behalf Grant / Token Exchange
• Use refresh tokens for on-behalf-of tokens
• Certificate-Based Authentication (mTLS)
• Use DPoP for enhanced security