Service Management REST API authentication fails with OAuth2

PLM Teamcenter
, , , , , , , ,
1

We’re experiencing OAuth2 authentication failures when trying to access Service Management operations through REST API in TC 12.3. The token validation works fine for standard PLM operations but consistently fails for service request automation workflows.

The issue occurs specifically with multi-tenant scenarios where scope mapping seems incorrect. Our API gateway configuration follows the standard OAuth2 flow, but tokens get rejected with “insufficient_scope” errors:


HTTP 403 Forbidden
{
  "error": "insufficient_scope",
  "error_description": "Token lacks required scope: tc.service.write"
}

We’ve verified the token includes service management scopes in the authorization request, but the gateway doesn’t seem to recognize them properly. Has anyone dealt with OAuth2 scope mapping issues for Service Management APIs in multi-tenant deployments?

system 2

This is a known configuration gap in TC 12.3 when combining OAuth2 with Service Management REST APIs in multi-tenant environments. Here’s the complete solution addressing all three critical areas:

OAuth2 Scope Mapping Configuration: First, update your OAuth2 client registration to explicitly include Service Management scopes. In your authorization server configuration, add the custom scope definitions:


tc.service.read=Read access to Service Management
tc.service.write=Write access to Service Management
tc.service.admin=Admin access to Service Management

Ensure these scopes are added to your client’s allowed scope list in the OAuth2 provider configuration.

Multi-Tenant Token Validation: The key issue is tenant context resolution. Your API gateway needs to extract tenant identification from the token (typically from a custom claim like ‘tenant_id’ or from the token’s audience claim) BEFORE performing scope validation. Configure your gateway’s authentication pipeline to:

  1. Extract tenant context from token claims
  2. Load tenant-specific scope mapping configuration
  3. Validate scopes against tenant-specific rules
  4. Apply tenant-specific permission mappings

In your gateway configuration file, add tenant-aware scope validation:

gateway.auth.tenant.claim=tenant_id
gateway.auth.tenant.scope.mapping.enabled=true
gateway.auth.scope.validation.order=tenant_context,scope_check

API Gateway Configuration: Update your gateway’s endpoint-to-scope mapping to include Service Management operations. The gateway needs explicit rules mapping OAuth2 scopes to actual API endpoints. Add these mappings to your gateway configuration:


/api/v1/service-requests/** = tc.service.write
/api/v1/service-requests/*/approve = tc.service.admin
/api/v1/service-requests/query = tc.service.read

Also critical: ensure your token introspection endpoint returns all custom scopes. Many OAuth2 providers only return standard scopes in introspection responses unless explicitly configured. Update your authorization server’s introspection endpoint configuration to include custom scope attributes in the response.

Verification Steps:

  1. Test token generation and verify custom scopes appear in the JWT payload
  2. Call the introspection endpoint and confirm all scopes are returned
  3. Check gateway logs to verify tenant context is resolved before scope validation
  4. Test Service Management API calls with properly scoped tokens

After implementing these changes, restart both your authorization server and API gateway. The insufficient_scope error should resolve once the gateway properly maps tenant-specific scopes to Service Management endpoints. This configuration ensures OAuth2 tokens are validated with full awareness of both tenant context and module-specific scope requirements.

This draft is based on general Teamcenter knowledge. It has not been verified against your specific version and environment. Practitioners: verify the steps and share your experience below.

3

I’ve seen similar scope validation issues. Check your OAuth2 client registration in Teamcenter - the service management scopes need to be explicitly granted at the client level, not just requested in the token. The multi-tenant configuration adds another layer where tenant-specific scope mappings must be defined in the gateway config.

4

We had this exact problem last quarter. The root cause was that Service Management module scopes weren’t being propagated correctly through the API gateway. You need to verify two things: first, that your OAuth2 provider is including the tc.service.write scope in the token payload, and second, that the gateway’s scope validation rules recognize service management operations as valid endpoints for that scope. In our case, the gateway was only mapping standard PLM scopes and ignoring module-specific ones.

5

The multi-tenant aspect is critical here. Each tenant needs its own scope mapping configuration in the API gateway. I’d recommend checking your tenant isolation settings - if the gateway isn’t properly routing requests based on tenant context, it might be applying the wrong scope validation rules. Also verify that your OAuth2 authorization server is issuing tenant-aware tokens with the correct audience claims.

6

Have you checked the OAuth2 token introspection endpoint? Sometimes the token is valid but the gateway’s introspection call fails to retrieve the full scope list. This happens when the authorization server’s introspection response doesn’t include custom scopes. You might need to configure the introspection endpoint to return all granted scopes, not just the standard OAuth2 ones.

mara_tc 7

Tested this on TC 12.3 with Azure AD as the OAuth2 authorization server, and explicitly adding the tc.service.read and tc.service.write scopes resolved the REST API authentication failures immediately.

8

I’d also look at the API gateway’s scope-to-permission mapping table. Service Management operations require specific permissions that map to OAuth2 scopes differently than standard CRUD operations. The gateway needs explicit rules that map tc.service.write to the actual Service Management API endpoints. Without these mappings, even valid tokens will be rejected because the gateway doesn’t know which endpoints the scope authorizes access to.

9

Check your token validation sequence in the gateway logs. The issue often stems from scope validation happening before tenant context resolution, causing the gateway to use default scope mappings instead of tenant-specific ones. You need to ensure tenant identification occurs first in the authentication pipeline.