Skip to content

Commit 64b755a

Browse files
ssanand2kssanand2k
authored
Update SCIM workload identity federation docs for Entra v2 tokens (#160)
* Updates to use azp * Make doc consistent
1 parent 9dcac9c commit 64b755a

1 file changed

Lines changed: 30 additions & 27 deletions

File tree

‎Workload-Identity-Federation-for-SCIM-Provisioning.md‎

Lines changed: 30 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -82,20 +82,20 @@ After selecting **Workload Identity Federation**, the administrator chooses **Se
8282
|---|---|
8383
| ![Register a new workload identity in Entra](media/workload-identity-federation/register-new-workload-identity.jpg) | ![Select an existing workload identity in Entra](media/workload-identity-federation/select-existing-workload-identity.jpg) |
8484

85-
After the access app is configured, the UX displays the following values to be **copied to the ISV Portal**:
85+
After the workload identity app is configured, the UX displays the following values to be **copied to the ISV Portal**:
8686

8787
| Value | Format |
8888
|---|---|
8989
| **Issuer (iss)** | `https://login.microsoftonline.com/<TenantID>/v2.0` |
9090
| **JWKS URL** | `https://login.microsoftonline.com/<TenantID>/discovery/v2.0/keys` |
91-
| **Subject (sub)** | `<Sync Fabric Workload Identity 1P app object ID>` |
92-
| **Audience (aud)** | `api://{WorkloadIdentity_appid}/.default` |
91+
| **Audience (aud)** | `<WorkloadIdentity_appid>` |
92+
| **Authorized Party (azp)** | `<Provisioning Client 1P app ID>` |
9393

9494
![Copy WIF claims and JWKS URL from Entra to the ISV portal](media/workload-identity-federation/copy-wif-claims-to-isv.png)
9595

9696
### Step 2: Set up SCIM Client with JWKS in ISV Portal
9797

98-
In the ISV portal, the administrator sets up a client for the ISV's SCIM endpoint. As part of setting up the auth integration, the administrator copies the values from Step 1 (issuer, JWKS URL, subject, audience) into the ISV portal.
98+
In the ISV portal, the administrator sets up a client for the ISV's SCIM endpoint. As part of setting up the auth integration, the administrator copies the values from Step 1 (issuer, JWKS URL, audience, and authorized party) into the ISV portal.
9999

100100
The ISV portal will then display the following values, needed for Step 3:
101101

@@ -146,7 +146,7 @@ Back in the Entra App Gallery:
146146

147147
2. **ISV's Token Endpoint** validates the JWT assertion:
148148
- Verifies the JWT signature using Microsoft's public OIDC keys
149-
- Validates the `issuer`, `audience`, and `subject` claims
149+
- Validates the `iss`, `aud`, and `azp` claims and the token timestamps
150150
- Issues an **access token** back to the Entra provisioning service
151151

152152
3. **Entra Provisioning Service** uses the issued access token as a **Bearer token** in SCIM API calls (GET, POST, PATCH, DELETE) to the ISV's SCIM endpoint
@@ -161,18 +161,19 @@ When Entra ID sends the JWT bearer assertion request, the **JWT assertion (clien
161161

162162
### JWT Claims in the Entra-Issued Assertion
163163

164-
| Claim | Description | Example Value |
165-
|---|---|---|
166-
| `aud` (Audience) | Workload Identity App ID | `api://b5ba7a93-4452-4522-aeb4-a2b5da870c16` |
167-
| `iss` (Issuer) | Customer tenant v2 issuer endpoint | `https://login.microsoftonline.com/ce5f061f-abe6-4e40-9615-301f87bcb7f0/v2.0` |
168-
| `sub` (Subject) | Sync Fabric Workload Identity 1P app object ID | `<Sync Fabric Workload Identity 1P app object ID>` |
169-
| `oid` (Object ID) | Workload Identity Object ID | `d2f8ee76-c549-45b8-a143-f5b640669704` |
170-
| `appid` | Workload Identity App ID | `b5ba7a93-4452-4522-aeb4-a2b5da870c16` |
171-
| `tid` (Tenant ID) | Customer Tenant ID | `ce5f061f-abe6-4e40-9615-301f87bcb7f0` |
172-
| `iat` (Issued At) | Token issue timestamp | `1772175916` |
173-
| `nbf` (Not Before) | Token not valid before | `1772175916` |
174-
| `exp` (Expiration) | Token expiry timestamp | `1772179816` |
175-
| `ver` | Token version | `2.0` |
164+
| Claim | Description | Should Validate? | Example Value |
165+
|---|---|---|---|
166+
| `aud` (Audience) | Workload Identity App ID | Yes, Identifies the client app for this integration | `api://b5ba7a93-4452-4522-aeb4-a2b5da870c16` |
167+
| `iss` (Issuer) | Customer tenant v2 issuer endpoint | Yes, Identifies the tenant in Entra for this integration | `https://login.microsoftonline.com/ce5f061f-abe6-4e40-9615-301f87bcb7f0/v2.0` |
168+
| `sub` (Subject) | Sync Fabric Workload Identity 1P app object ID | May be, already covered by iss. sub will have same value for all integrations in a tenant | `<Sync Fabric Workload Identity 1P app object ID>` |
169+
| `oid` (Object ID) | Workload Identity Object ID | |`d2f8ee76-c549-45b8-a143-f5b640669704` |
170+
| `azp` (Authorized Party) | Provisioning Client 1P App ID | Yes, Unique Id for Provisioning Client, proves that this token was requested by Provisioning Client | `cb1d50fe-8ed0-4944-9e7d-5981aad3bc4b` |
171+
| `azpacr` | Authentication method used for the Workload Identity | |`2` |
172+
| `tid` (Tenant ID) | Customer Tenant ID | | `ce5f061f-abe6-4e40-9615-301f87bcb7f0` |
173+
| `iat` (Issued At) | Token issue timestamp | Yes | `1772175916` |
174+
| `nbf` (Not Before) | Token not valid before | Yes | `1772175916` |
175+
| `exp` (Expiration) | Token expiry timestamp | Yes | `1772179816` |
176+
| `ver` | Token version | | `2.0` |
176177

177178
### Example Token Payload
178179

@@ -183,9 +184,8 @@ When Entra ID sends the JWT bearer assertion request, the **JWT assertion (clien
183184
"iat": 1772175916,
184185
"nbf": 1772175916,
185186
"exp": 1772179816,
186-
"appid": "b5ba7a93-4452-4522-aeb4-a2b5da870c16",
187-
"appidacr": "2",
188-
"idp": "https://login.microsoftonline.com/ce5f061f-abe6-4e40-9615-301f87bcb7f0/v2.0",
187+
"azp": "cb1d50fe-8ed0-4944-9e7d-5981aad3bc4b",
188+
"azpacr": "2",
189189
"oid": "d2f8ee76-c549-45b8-a143-f5b640669704",
190190
"sub": "<Sync Fabric Workload Identity 1P app object ID>",
191191
"tid": "ce5f061f-abe6-4e40-9615-301f87bcb7f0",
@@ -194,7 +194,7 @@ When Entra ID sends the JWT bearer assertion request, the **JWT assertion (clien
194194
```
195195

196196
> [!NOTE]
197-
> The `iss` and `sub` claims in the Entra-issued token identify the **customer's tenant** and the **Sync Fabric Workload Identity 1P app object**, respectively. The ISV validates these against the values provided during the 3-step configuration.
197+
> The ISV validates `aud`, `iss`, and `azp` against the values provided during the 3-step configuration. The `sub` claim identifies the **Sync Fabric Workload Identity 1P app object**, but validating it is optional because its value is shared by all integrations in the tenant.
198198
199199
### Additional Context Provided
200200

@@ -223,7 +223,8 @@ ISVs must validate the Entra-issued JWT assertion using Microsoft's published JW
223223
The ISV portal must allow administrators to configure the expected claim values for each integration:
224224

225225
- **`aud` (Audience)** — the audience value the ISV expects in incoming JWTs
226-
- **`sub` (Subject)** — the subject identifier for the Sync Fabric Workload Identity 1P app
226+
- **`azp` (Authorized Party)** — the ID of the Provisioning Client 1P app
227+
- **`iss` (Issuer)** — the customer tenant v2 issuer endpoint
227228
- **JWKS URL** — the endpoint to fetch Microsoft's signing keys
228229

229230
These values are provided by the Entra portal during Step 1 of the configuration flow and entered by the administrator in Step 2.
@@ -275,7 +276,7 @@ SAP SuccessFactors is the first application to support this new authentication m
275276
2. **Selects "Provisioning"** and chooses **Workload Identity Federation** as the authentication method (instead of basic auth or bearer token)
276277
3. **Entra ID automatically**:
277278
- Creates a federated identity credential on the provisioning app's service principal
278-
- Configures the JWT bearer assertion parameters (audience, issuer, subject mapping)
279+
- Configures the JWT bearer assertion parameters (audience, issuer, and authorized party)
279280
4. **No secrets to manage** — the admin only provides the SuccessFactors SCIM endpoint URL
280281
5. **Provisioning cycles** automatically perform JWT bearer assertion authentication before each sync
281282

@@ -371,13 +372,15 @@ Authorization: Bearer sl.Adf8sHg7jKl3nM...
371372

372373
3. **Issuer Validation**: Confirm the `iss` claim matches the expected Microsoft Entra ID v2 issuer format: `https://login.microsoftonline.com/{tenantId}/v2.0`
373374

374-
4. **Token Expiry**: Always check `exp` and `nbf` claims. Reject expired or not-yet-valid tokens.
375+
4. **Authorized Party Validation**: Verify the `azp` claim matches the Provisioning Client 1P app ID. Reject tokens requested by an unexpected client.
376+
377+
5. **Token Lifetime Validation**: Check the `iat`, `nbf`, and `exp` claims. Reject tokens issued unexpectedly far in the past or future, expired tokens, and tokens that are not yet valid.
375378

376-
5. **Tenant Isolation**: Use the `tid` claim to ensure provisioning operations are scoped to the correct customer tenant. Cross-tenant data leaks are a critical risk if this is not enforced.
379+
6. **Tenant Isolation**: Validate the complete tenant-specific `iss` value to ensure provisioning operations are scoped to the correct customer tenant. Do not rely on an unvalidated `tid` claim for tenant isolation.
377380

378-
6. **Rate Limiting**: Implement rate limiting on the token endpoint to prevent abuse.
381+
7. **Rate Limiting**: Implement rate limiting on the token endpoint to prevent abuse.
379382

380-
7. **TLS Requirement**: All JWT assertion and SCIM communications MUST use TLS 1.2 or higher.
383+
8. **TLS Requirement**: All JWT assertion and SCIM communications MUST use TLS 1.2 or higher.
381384

382385
---
383386

0 commit comments

Comments
 (0)