OpenID System-to-System Authentication for Xytech – Fabric Help Center

This document explains how to configure and use OpenID Connect (OIDC) for system-to-system authentication against the Xytech REST API. It covers using the Client Credentials grant flow with tokens issued by standard OIDC providers such as Microsoft Entra ID (Azure Active Directory/AD), Google, Okta, etc. Applicable from release 11.2

1. Overview

Xytech supports the ability to validate JSON Web Tokens (JWT) issued by OpenID Connect providers. While interactive user flows typically rely on explicit user authentication (e.g., via a browser-based Single-Page Application), system-to-system scenarios rely on the Client Credentials flow.

In these system-to-system scenarios:

The calling service obtains a JWT from an OIDC provider by presenting client_id and client_secret.
The service supplies that JWT in the Authorization: Bearer <token> header when calling Xytech’s REST API.
Xytech validates the token against its OIDC configuration (including checking the sub/upn claim) and applies role-based permissions using the mapped user account within Xytech.
The OIDC user is mapped to a user with the configuration in the OpenID Mapping inside the Xytech system.

Diagram representing the authentication flow and token generation.

2. Prerequisites and Terminology

OIDC Provider: The identity provider (IdP) capable of issuing JWTs (e.g., Azure AD, Google, Okta).

Client Credentials Flow: An OAuth2 flow for server-to-server (non-interactive) communications.

sub (Subject) Claim: The unique identifier in the JWT representing the client or user.

UPN (User Principal Name) Claim: Commonly used in interactive user flows; not typically present for system accounts.

3. High-Level Setup Steps

Register an Application with Your Identity Provider (IdP).
1. Create (or identify) an application registration (e.g., in Azure AD).
2. Enable the Client Credentials grant type.
3. Record:
  1. Client ID
  2. Client Secret
  3. Discovery URL (e.g., https://login.microsoftonline.com/ <tenant>/.well-known/openid-configuration)
  4. Issuer (e.g., https://sts.windows.net/ <tenant>/)
  5. Audience (the Application ID URI or client ID)

Provide the following information to Xytech Tech Services so they can update the appropriate App Services configuration keys:

SPA_OPENID_DISCOVERY_URL = <e.g., https:="https:" login.microsoftonline.com="login.microsoftonline.com"></e.g.,>/.well-known/openid-configuration
SPA_OPENID_ISSUER = {e.g., https://sts.windows.net//}
SPA_OPENID_AUDIENCE = {the client_id or audience your IdP issues tokens for}

Map the sub Claim to a Xytech User.
1. Within the Xytech UI, locate the user record that will represent the system client.
2. In the user’s Ext Auth Key or Ext Auth Key 2 field, enter the exact claim value from the token, it can be the sub or upn claim.
3. This ensures that when Xytech receives a token, it can match that claim to the correct Xytech user account.
Obtain a Token from the IdP (Client Credentials Flow).
From your backend system, request a token from the IdP’s token endpoint:
```
grant_type=client_credentials
client_id=
client_secret=
scope=/.default (for Azure AD)
```
The IdP responds with an access token (JWT) containing a sub or upn claim.
Call the Xytech REST API with the Token.
Include the token in the Authorization header:
```
Authorization: Bearer {jwt_from_idp}
```
NOTE: Xytech will validate the token (issuer, audience, signature, etc.) and then map the sub to a Xytech user.
Handle Token Expiry.
Tokens issued via Client Credentials typically have a limited lifetime.
When the token expires, request a new one from the IdP using the same credentials.

4. Handling Multiple Application Registrations

If you have multiple backend services, each can have its own application registration. This allows more granular tracking and permissions. In Xytech:

Create Unique Users for Each Registration
1. Each application registration will have its own unique sub.
2. Assign each registration’s sub to a different Xytech user record with the roles/permissions that specific service requires.

IMPORTANT

Multiple Providers are not supported.
The current implementation can only connect to one OIDC provider configured in the mediapulseappserver.config.txt.

5. Single Page App (SPA) vs. System Access

The SPA_OPENID features, introduced in Xytech v11.2, allow tokens from interactive user flows (e.g., SPAs) and system-to-system flows to be validated the same way:

Interactive (User) Flow: Users log in, and the IdP includes a UPN claim.
System-to-System (Client Credentials) Flow: Tokens may lack UPN but contain a sub claim unique to the application registration.

Both flows can coexist. The primary difference is how you map the claims to Xytech user records (i.e., using upn vs. sub) and what scope to include while requesting the token.

6. Configuration Management

mediapulseappserver.config.txt Entries
Use the following keys in the mediapulseappserver.config.txt file:
```
  SPA_OPENID_DISCOVERY_URL = <discovery_url>
  SPA_OPENID_ISSUER = <issuer_url>
  SPA_OPENID_AUDIENCE = <audience_or_client_id>
```
SPA_OPENID_DISCOVERY_URL: Points to the .well-known/openid-configuration for your IdP.
SPA_OPENID_ISSUER: The expected iss (issuer) claim in the token.
SPA_OPENID_AUDIENCE: The aud claim in the token must match this value.

7. Responding to IdP Changes

Changed sub or upn Claim
- If your IdP changes the sub or upn claim for a registered application or user, update the corresponding Xytech user record to match.
Revoked or Deleted Application Registration
- If an application registration is revoked in the IdP, it will no longer obtain valid tokens.
- You may optionally remove or disable its user mapping in Xytech.
Secret Rotation
- When the IdP requires client secret rotation, update your token-requesting service with the new secret.
- Xytech requires no additional changes as long as the sub, iss, and aud remain consistent in the JWT.

8. Existing Functionality (v11.1)

For customers on version 11.1 or earlier, the SPA_OPENID configuration entries do not exist yet (they were introduced in 11.2).

An alternative could be using the Xytech JWT access token. That can be generated with the DB credentials. To know more about this alternative consult the documentation.

9. Example: Microsoft Entra (Azure AD) Client Credentials

Below is a simplified example of how to set up system-to-system authentication with Azure AD:

Obtain Token (e.g., with Postman or code):

POST https://login.microsoftonline.com/<tenant>/oauth2/v2.0/token

Content-Type: application/x-www-form-urlencoded
  
grant_type=client_credentials
client_id=<your_client_id>
client_secret=<your_client_secret>1
scope=<your_client_id>/.default

Configure Xytech
In mediapulseappserver.config.txt:

SPA_OPENID_DISCOVERY_URL = https://login.microsoftonline.com/<tenant>/.well-known/openid-configuration
SPA_OPENID_ISSUER = https://sts.windows.net/<tenant>/
SPA_OPENID_AUDIENCE = <your_client_id>

Map the sub Claim
1. Decode the returned JWT (e.g., using jwt.io ) and find the sub or upn claim.
2. In the Xytech user record, set the Ext Auth Key or Ext Auth Key 2 field to this
  value.
Call Xytech REST API, and include the token in your header:
```
Authorization: Bearer <jwt_from_idp>
```

Xytech validates the token and authorizes you as the mapped Xytech user.

10. Conclusion and Next Steps

System-to-system OIDC authentication in Xytech leverages the same underlying token validation logic introduced for SPA in v11.2. By adding the correct entries to mediapulseappserver.config.txt and mapping the sub/upn claim to the correct Xytech user, you can securely automate REST API interactions without needing an interactive login.