Authentication¶

The Polarion REST API supports authentication via Personal Access Token (PAT), JSON Web Token (JWT), and Teamcenter SSO (TCSSO) token.

Every call is individually authenticated, there are no persistent sessions.

• Use Personal Access Tokens (PATs).

• Use the Polarion portal.

• Use JSON Web Token.

• Use Teamcenter SSO (TCSSO) token.

Authentication with PAT¶

When you try to access Polarion's REST API you must provide a Polarion Personal Access Token in the Authorization header of each request.

Authorization: Bearer {personal_access_token}

If the token is missing or invalid, a 401 Unauthorized response is returned.

Test REST Endpoints using the Swagger UI¶

To test the Polarion REST endpoints using the Swagger UI, click Authorize and authorize yourself using your Polarion Personal Access Token.

(Personal Access Tokens are already used for SOAP Web Services.)

• Any Polarion user can create and manage their own tokens.

• Polarion administrators can immediately revoke another user's tokens in an emergency.

• Personal Access Tokens can also be renewed.

  • Polarion users can renew their own (expired or valid) tokens.
  • Privileged users (with MANAGE USER permissions in the Global context) can also renew the expired/valid tokens of other users.
  • Administrators can set the number of days before a renewed token expires with the following property in the polarion.properties file: com.siemens.polarion.security.personalAccessToken.maxDaysBeforeRenewedTokenExpiry (The default value is 90 days.)

Renew PAT via API¶

You can renew Personal Access Tokens through the com.polarion.platform.security.accesstoken.IUserAccessTokenService.renewToken(String, String) Java API.

Example of a custom script executed via a job to renew a Personal Access Token:

<script>
    // Function to renew all access tokens for a specific user
function renewUserAccessTokens(userId) {
    // Retrieving the User Access Token Service
    var userAccessTokenService = com.polarion.platform.core.PlatformContext.getPlatform().lookupService(com.polarion.platform.security.accesstoken.IUserAccessTokenService.class);

    // Retrieving the Transaction Service
    var transactionService = com.polarion.platform.core.PlatformContext.getPlatform().lookupService(com.polarion.platform.ITransactionService.class);

    // Start a new transaction
    transactionService.beginTx();

    // Fetch the list of user access tokens for the provided userId
    var tokens = userAccessTokenService.getUserAccessTokens(userId);

    // Iterate over each token and renew it
    tokens.forEach(function(token) {
        var tokenId = token.getId();
        userAccessTokenService.renewToken(token.getUserId(), tokenId);
    });

    // endTx(false) will commit the transaction
    transactionService.endTx(false); 

    // Return success
    return true;
}

// Example usage: Renewing access tokens for the user "aSeller"
var result = renewUserAccessTokens("aSeller");
</script>

Authentication from Polarion without PAT¶

To access the Polarion REST API, you can issue an HTTP request using JavaScript while within an active Polarion session without having to generate a Personal Access Token (PAT).

To authenticate through the Polarion REST API, you can use the X-Polarion-Rest-Token header, which is bound to the authenticated session and follows the same lifecycle.

The generated X-Polarion-REST-Token is only valid for the current session and becomes invalid when you log out.

To use the X-Polarion-REST-Token, add the following property to the polarion.properties file:

com.siemens.polarion.rest.security.restApiToken.enabled=true

• The Polarion REST API using the X-Polarion-REST-Token can perform read/write operations on behalf of the user viewing a Polarion Report Page.
• To prevent malicious code from running secretly, administrators should ensure that WRITE Page permissions are defined correctly and are only enabled for trusted users.

To authenticate your Polarion REST API call, supply the X-Polarion-REST-Token header in each Polarion REST API request.

The value of the header is obtained from the top.getRestApiToken() function, which generates the session-bound token.

The function is available in the Polarion UI and can be called directly using top.getRestApiToken(), window.getRestApiToken().

The getRestApiToken() function is available on:

• Live Report Pages (In the scripting widgets like "Script - Block".)

• Velocity and Java Widgets

• Classic Wiki Pages

• LiveDoc Documents (In the Wiki Content sections.)

• Any other place with direct access to Polarion's UI DOM where JavaScript can be executed.

The getRestApiToken() function is NOT available on:

• Work Item/Document Sidebars (JavaScript execution support is not yet implemented.)

• Workflow Scripts (Since there is no UI with a DOM to access the function.)

• Jobs (same as Scripts),

• Any other place where the Polarion UI is not directly accessible.

Here's an example of how to authenticate using the X-Polarion-REST-Token token:

<script>
  // Declaration
  function fetchRestAPI() {
    var fetchUrl = "/polarion/rest/v1/projects/drivepilot/workitems/DP-584";
    var restToken = top.getRestApiToken();

    fetch(fetchUrl, {
      headers: {
        'Accept': 'application/json',
        'X-Polarion-REST-Token': restToken
      }
    })
    .then(response => {
      console.log("fetchRestAPI response: ", response);
      if (!response.ok) {
        throw new Error(`HTTP error! Status: ${response.status}`);
      }
      return response.json();
    })
    .then(json => {
      console.log("fetchRestAPI json: ", json);
    });
  }

  // Invocation
  fetchRestAPI();
</script> 

The following example shows how to use the Polarion REST API to create a new test Work Item using the X-Polarion-REST-Token token.

When the script is used on a Classic Wiki Page (or in the Wiki Content section of a LiveDoc Document), you must apply special handling via {pre} tags.

If not, Polarion processes the xWiki syntax, which changes and breaks the JavaScript code.

## This script creates a new Work Item in the current project from Classic Wiki Page, 
Document page, LiveReport Pages & Work Item Velocity/Java Form Extensions   

{pre} 
<button onclick="createWorkItem()">Create Test Work Item</button> 
#set($projectId = "") 
#if($document.getProjectId() != "") 
#set($projectId = $document.getProjectId()) 
#elseif ($page.getProject() != "") 
#set($projectId = $page.getProject()) 
#elseif ($page.getReference().projectId() != "") 
#set($projectId = $page.getReference().projectId()) 
#elseif ($object.getContextId().getContextName() != "") 
#set($projectId = $object.getContextId().getContextName()) 
#end   

<script>
  function createWorkItem() {
    var jsProject = '$projectId';
    if (jsProject == "") {
      alert("Please Select Project to Create Work Item");
      return;
    }
    var restToken = top.getRestApiToken();
    var fetchUrl = '/polarion/rest/v1/projects/' + jsProject + '/workitems';

    fetch(fetchUrl, {
      method: 'POST',
      headers: {
        'Accept': 'application/json',
        'X-Polarion-REST-Token': restToken,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        'data': [
          {
            'type': 'workitems',
            'attributes': {
              'description': {
                'type': 'text/html',
                'value': 'My Work Item Description'
              },
              'title': 'My Test Work Item Title',
              'type': 'task'
            }
          }
        ]
      })
    })
    .then(response => {
      console.log('createWorkItem() response: ', response);
      if (!response.ok) {
        alert('Status ' + response.status + ': HTTP error!');
      } else {
        alert('Status ' + response.status + ': Test Work Item successfully created.');
      }
      return response.json();
    });
  }
</script>
{/pre}

Authentication via JSON Web Token (JWT)¶

Polarion supports JSON Web Token (JWT) authentication for its REST API, offering flexibility and enhanced security by allowing configuration with various Identity Providers (IDPs) and supporting both symmetric and asymmetric signing methods, with detailed setup instructions provided for generating and processing JWTs.

JSON Web Token (JWT) is a widely used mechanism for authentication and authorization. Polarion supports JWT as an authentication mechanism for the REST API layer in addition to the PAT. You can configure Polarion to accept JWTs generated by various Identity Providers (IDPs). This offers more flexibility compared to PAT, especially for integrations.

In this section we discuss the following JWT authentication-related topics:

• Generating a JWT
• Configuring the authenticator to process JWT

Generating a JWT¶

JWTs are generated by various IDPs, for example Google, Facebook, Twitter, Keycloak, and so on. The structure of the JWT has to have information about the Polarion user who would be executing Polarion functionalities when authenticated with the supplied token.

The following configuration is needed to process the supplied JWT. This configuration is made as a JWT authenticator element in the authentication.xml file.

Sample JWT structure:

Header:
{
  "alg": "RS256",
  "kid": "key-1",
  "typ": "JWT"
}

Payload:
{
  "iss": "https://accounts.google.com",
  "sub": "admin",
  "name": "bharat",
  "role": "admin",
  "iat": 1744887113,
  "exp": 1744894313
}

Signature: JWT signature

The above JWT has an issuer ("https://accounts.google.com") and a custom attribute ("role" : "admin"), which could be used to supply user information to the Polarion REST API.

Authenticator configuration:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?><authentication
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://polarion.com/PolarionAuthentication"
xsi:schemaLocation="http://polarion.com/PolarionAuthentication
[Your_polarion_url_here]/authentication.xsd">
    <!-- jwt authenticator showing usage of jwks -->
    <jwt usage="rest-api">
        <iss>idp-with-jwks</iss>
        <verification>
            <jwks>https://polarion-idp.com/jwks</jwks>
            <publicKey>
                <key></key>
                <algo>RS256</algo>
            </publicKey>
        </verification>
        <mapping>
            <id>$.role</id>
            <name>username</name>
        </mapping>
        <responseParser>jsonpath</responseParser>
    </jwt>
</authentication>

The JWT authenticator (jwt) must have an issuer, for example issuer. The applicable JWT authenticator for a given JWT is selected by matching the issuer on the token with that of the iss element on the JWT authenticator. The given JWT can be verified in two ways:

• Retrieving the relevant JSON Web Key Set (JWKS) from the configured jwks URL under the jwks element.

• Using a local key, either HS256 (symmetric signing) or RS256 (asymmetric signing), which can be configured in the key element.

Both HS256 and RS256 algorithms are supported and have to be configured in the algo element. Due to shared key vulnerabilities, it is always suggested to use RS256 (asymmetric signing). The JWT configuration also provides an additional layer of security when the key is configured in the authentication.xml file through storage of the key in the User Account Vault. You can configure the JWT to store the key in the user account vault via specifying the userAccountVaultKey in the key element instead of the key. The usage attribute on the JWT authenticator specifies that the authenticator is to be used for the REST API. For the JWT authenticator, this is the only supported use case.

Example:

<key userAccountVaultKey="mySecretKey"></key>

Here the actual key is in the user account vault with the following key: "mySecretKey".

The user information specified in the supplied JWT is retrieved by making use of the expression specified in the id element under the mapping element of the relevant JWT authenticator. The information (content) specified under id has to be parsed by the specified responseParser. The responseParser can be jsonpath (the default) or attr.

Example:

<mapping>
     <id>$.role</id>
     <name>username</name>
</mapping>

The example implies that the userid to be used for the Polarion REST API calls is found by retrieving the role element in the JSON payload, which is specified as admin. The specified user must exist in Polarion for the user to be authenticated.

The JWT authentication attempts are logged in the log file with the "JWT: AUTH :" prefix. Each unique issuer can only be associated with one JWT authenticator, although multiple authenticators can be configured across different issuers. The REST API call must include the X-Polarion-token-type custom header with jwt value. The token must be supplied as an Authorization Bearer token.

Authentication via Teamcenter SSO (TCSSO) token¶

Polarion's REST API supports Teamcenter SSO (TCSSO) tokens for authentication, requiring configuration of the authentication.xml file with a TCSS authenticator element and specific custom headers in API calls, while ensuring that the user IDs exist in both Polarion and Teamcenter systems for secure interaction.

Teamcenter SSO (TCSSO) tokens are supported by the Polarion REST API authentication. To use TCSSO-based authentication, you must configure the authentication.xml file by adding a tcss authenticator element, in addition to the usual tcss configuration steps.

When using TCSSO authentication for the REST API, the API call must include the following custom headers:

• X-Polarion-token-type with tcss value and

• X-Polarion-user-id with the required user-id as value.

The token must be supplied as an Authorization Bearer token.

The user with the supplied user-id in the header is used to interact with Polarion, and so this user must exist in the Polarion system. Adequate security measures have to be taken by the Teamcenter administrators to restrict the users who can interact with Polarion, as the same user-id needs to exist in both systems in the absence of a mapped user mechanism for generating TCSSO tokens by Teamcenter Security Services.

The tcss authentication attempts are logged in the log file with a "TCSS: AUTH :" prefix.

Sample TCSS authenticator configuration:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<authentication
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://polarion.com/PolarionAuthentication"
xsi:schemaLocation="http://polarion.com/PolarionAuthentication
[Your_polarion_url_here]/authentication.xsd">
    <tcss usage="rest-api">
        <loginUrl>http://tcss-server/login/sa</loginUrl>
        <serviceUrl>http://tcss-server/identity</serviceUrl>
    </tcss>
</authentication>