REST API Authentication

The Authentication and API Keys
2
Clarity
REST APIs support the following methods for authenticating user requests:
    • This method lets you obtain the authentication token for a session, and pass the token for subsequent API requests. The token remains active until the session ends.
    • This method lets you pass the user credentials in base64 encoding, with every API request. We recommend that you use this method for testing purposes.
    • This method lets you generate an API key based on a user's credentials, access rights, and status settings. Use this method for integrating
      Clarity
      with other client applications or if you have SSO implementation for
      Clarity
       
Authorization - Access Rights Required to Consume APIs
Irrespective of the authentication method you choose, you need the following access rights to use the APIs:
  • API-Access
    - Ensure that you have this access right to be able to send requests to the
    Clarity
    APIs.
  • Functional access rights
    - Ensure that you have appropriate access rights to view or update the specific functional areas in the product. For example, if you have the
    API - Access
    right but do not have the
    Projects - Create
    access right, your POST request for the Project resource will return a 401 unauthorized error message.
Token-Based Authentication with Login and Logout API End Points
The Login and Logout API endpoints are used to implement token-based login. You can access the endpoints using
/auth
context.
Generate the Token using Login API
The Login API requires you to pass the user name and password in a basic authentication header with Base64 encoding. The API returns an authorization token that can be passed as a header parameter to identify the user in subsequent REST calls to
Clarity
.
Request URL
:
POST http://<servername>:<port>/ppm/rest/v1/auth/login Authorization: Basic YWRtaW46YWRtaW4=
Response Body
The response body includes the authToken that can be passed to subsequent API requests:
{ "authToken": "5096019__059A218A-360D-455B-8E6C-7625B7500A4A", "_self": "http://<servername>:8080/ppm/rest/v1/auth/login" }
Use the AuthToken to Make a REST Call
After the authToken is generated, you can use it to call the resources that you have access to. In the REST client, pass the authToken in the Authorization header as follows:
Delete the Token Using Logout API
The Logout API invalidates an auth token and prevents the user from making further calls using the token.
Request URL
:
DELETE http(s)://<servername>:<port>/ppm/rest/v1/auth/logout Header : Name = authToken, value = <authToken value from login>
If the request is successful, you will get a blank response body with a response code as 200.
Basic Authentication
For Basic authentication, provide the username and password with Base64 encoding for every REST API request.
Key-Based Authentication
Key-based authentication uses a personal API key that is generated for a specific client based on a user's SSO credentials, access rights, and status settings. Key authentication eliminates the need to generate and pass credentials or token for every session. Use key authentication in the following scenarios:
  • You want to integrate data between
    Clarity
    and other client applications. Integration architectures can allow users to authenticate through the REST API and accomplish certain
    Clarity
    actions without going into the user interface.
  • Your
    Clarity
    instance is using SSO for authentication.
For example,
Rally
integration could make webhook calls to read
Clarity
project data personalized for the current user. For project managers, third-party integration could read and update resource allocation data in
Clarity
based on external application triggers such as other users updating a JIRA Kanban board.
The process of generating and using the API key for authentication involves the following steps:
Administrator: Create an Integration User and Grant Access Rights
To access
Clarity
data from another application, the API developers will require an integration account with the appropriate access rights. For information on creating user accounts, see the Create a New User section.
The integration user must have the following access rights:
  • API-Access
  • Functional access rights. For example, if the developer is trying to read the project data from
    Clarity
    and display it in their application, the integration user needs to be given read access to Projects. For more information, see in the Reference section.
After you have created the user account and granted access rights, send the user information to the developer.
Administrator: Enable API Key Authentication
Key-based authentication is disabled by default. As a
Clarity
administrator, enable key-based authentication so that your API developers can generate API keys and use it for authentication.
If you are using the
Clarity
SaaS, non-GCP environment, open a support ticket to enable the API Key authentication feature in your environment. If you are on the GCP environment, follow the steps below to enable the feature.
Follow these steps
:
  1. In
    PPM classique
    , click
    Administration
    ,
    General Settings
    ,
    System Options
    .
  2. Scroll down to the
    API
    section and specify the following configuration:
    • Select
      Enable API key-based access
      . If you clear this option later, users can no longer generate API keys and all the existing keys are invalidated.
    • Change the value in the
      Salt for Encrypting API Keys
      field. By default, each new installation receives a preset salt value for key encryption. We recommend that you change the value after an installation or upgrade to satisfy the security requirements in place at your organization.
      Be careful to minimize future changes to the salt field. If you change the salt value after the keys are created, you must regenerate all the keys.
    • Set the expiration limit for the API keys in the
      Maximum expiration in days for API keys
      field. You can adjust the default value of 90 days to set your own maximum number of days. The value that you set determines the maximum possible duration or lifespan for each active key from its creation date. When a user generates a key, they will have an option to set the
      Expiration Date
        for that specific key, but it cannot exceed the limit set in this field.  Keys expire automatically when the expiration date arrives.
    • In the
      Maximum number of keys allowed per user
      field, specify the maximum number of active keys that a user can generate for all clients defined in the system. For any single client, no more than 20 keys can be created and stored for each user.
  3. Click
    Save
    .
enable_keys.jpg
Administrator: Define REST API Client Applications
Define a client for each application that you want to integrate with
Clarity
. This process helps
Clarity
to allow only authorized clients to access data through REST APIs.
Follow these steps
:
  1. Log in to
    Clarity
    .
  2. In the main menu, click 
    Administration
    .
  3. Click
    Authentication & Keys
    .
  4. Click
    CLIENTS
    .
  5. Click
    Add Row
    to define a new client.
    1. Specify a unique identifier and name for the client application that you want to integrate.
      The following image shows an integration client:
      image2019-2-28_15-59-12.png
  • Your client ID must be passed with the API key in future REST API calls.
  • This release does not support deleting a client. Instead, you can deactivate it.
  • If you clear the
    Active
    checkbox, the client is now inactive and all keys created by all users for that client are temporarily disabled. Users cannot generate new keys while a client is disabled. When the administrator reactivates the client, the previous keys start working again.
API Developer: Generate API Key for your Client
REST API keys serve as tokens that permit authorized users to exchange data between
Clarity
and a pre-defined client application. As a developer, you can use the integration user account that your administrator had created, for generating the keys. 
At any given time, each authorized user can only store up to 20 active keys for each client. The maximum number of keys that a user can generate across clients is defined in the
Maximum number of keys
allowed per user field in
System Options
.
The following diagram depicts how the clients and keys are associated:
rest_api_hier.png
Follow these steps
:
  1. Log in to
    Clarity
    using the integration user account.
  2. Click the name and avatar image in the top-right corner.
    The application menu appears.
  3. In the application menu, click
    API KEYS
    .
    image2019-2-28_14-28-11.png
  4. On the
    API Keys
    page, click 
    New Row
    .
    1. In the required
      Access Type
      field, select the type of access you want to allow with this key:
      • All Access
        :
        All Access
        means that the key authorizes each user to perform the maximum amount of functionality as determined by their
        Clarity
        access rights. Even users with
        Delete
        access rights on one or more objects (such as projects or resources) cannot delete items through an integration unless they have an
        All Access
        key.
      • Read/Edit
        : This type of access allows users to read, create, and update Clarity data.
      • Read-Only
        : With this access type, users can only read data in
        Clarity
        ; they cannot make any changes.
    2. In the
      Client
      field, select an integrated client application to pair with this API key. Get the client name for your applications from your administrator.
    3. Enter a required
      Name
      for this integration (
      key-client
      pair) and an
      Expiration Date
      for the key. This date cannot exceed the global expiration limit set by the administrator. The system prompts you if you exceed the limit.
    4. The application selects the
      Active
      checkbox for you. You cannot disable a key.
    5. The application fills in your name in the
      Owner
      field. You cannot change the owner.
      image2019-3-12_17-23-10.png
  5. After all required fields are complete, your API key appears (see the image below).
    This exclusive appearance of the
    New API Key
    modal pop-up is the one and only time you can view and copy your key.
  6. Click
    COPY KEY
    .
image2019-3-13_16-40-7.png
Also make a note of the
Clarity
server URL and your
Client ID
for this key. If you have a credentials application or secure password database, you can use it to store your server URL, client ID, and API key. You may also want to make a note of the expiration date. If you paste your key into a temporary application such as Notepad, be sure to use it in your client application.
  • Keys are self-contained entities and include their associated client, owner, expiration date, and user access type.
  • Keys in queries run in the context of their owner.
    Clarity
    access rights for the owner apply dynamically and are loaded from the database for each instance of a REST API call.
  • Keys are only available once. If you lose a key, regenerate a new one.
  • Keys are not stored in the database. Only the metadata about the key is available in the database.
  • Keys from Company A cannot be used with the
    Clarity
    server for Company B. The encrypted keys contain their own key-level salt codes for added security.
When you upgrade or refresh a
Clarity
SaaS hosted instance (for example, from staging to production), the key metadata moves from the source environment to your new target environment; however, the keys from the previous environment no longer work. A new salt value takes the place of any older value and only new keys will work. As part of your post-refresh cleanup activities, administrators must manually delete the old keys for users. Another option is to deactivate the client for those old keys. Then, create new clients and keys.
API Developer: Use the API Key to Integrate with the Client
After you have generated the API key, you can use it to securely access
Clarity
data from the client.
If you have a
Clarity
On-Premise setup with SSO, review the Using REST API Key in SSO Environments (On-Premise only) section before you perform the steps in this section.
Follow these steps:
  1. Keep the following information handy:
    1. Client ID
    2. API Key
    3. Clarity URL
    4. REST API object path. For example, http://clarity.xyz.com:8080/ppm/rest/v1/projects
  2. To verify the calls, use a REST client with the following settings:
    Setting
    Parameter
    Value
    Basic REST Structure
    Method
    GET
    Request URL
    http://<ppm_server>:<port>/ppm/rest/v1/<object_class>
    Example
    : http://clarity.xyz.com:8080/ppm/rest/v1/projects
    Headers
    x-api-ppm-client
    <my_client_ID>
    Authorization
    Bearer <MY_REST_API_KEY>
    ContentType
    application/json
  3. Click
    Send
    .
  4. Verify that the response Status shows 200 OK.
The following two screenshots show an example of a REST API GET call for a list of projects using Postman:
image2019-6-5_15-48-43.png
In Postman, set the
Authorization Type
to
Bearer Token
and paste your key into the
Token
field.
image2019-6-5_15-52-25.png
The following image shows a similar example using Advanced REST Client:
image2019-6-5_15-38-44.png
The following sections show the request headers for an integration call with a client named CLIENT_MY-APP-2:
Request Header
x-api-ppm-client: CLIENT_MY-APP-2 Authorization: Bearer J0eXAiOiJKV1QiLCJhbGciOiJeyJzdWIiOiJhZG1pbiIs...0MTU2NTMyMzIwMCwCcUxxvX260ObmURVRzzY
Response Body
{ "_pageSize": 25, "_self": "https://ppmstage02:8043/ppm/rest/v1/projects", "_totalCount": 50, "_next": "https://ppmstage02:8043/ppm/rest/v1/projects?offset=25", "_results": [ { "_internalId": 5012672, "code": "csk.appChange", "name": "Application Change Template", "_self": "https://ppmstage02:8043/ppm/rest/v1/projects/5012672" }, }, { "_internalId": 5013763, "code": "PR1027", "name": "Data Warehouse Performance Tuning", "_self": "https://ppmstage02:8043/ppm/rest/v1/projects/5013763" }, }
Using REST API Key in SSO Environments (On-Premise only)
Some of the key points you need to remember while using API keys in an SSO environment are:
  • You should make REST calls to
    Clarity
    by using the
    http://hostname:port/tokens/rest/v1
    request. The “/tokens” parameter works only in an SSO environment. When you use the “/tokens” parameter in an SSO environment,
    Clarity
    adds additional headers to force token-based authorization and then forwards the request to "/ppm/rest" thus allowing access to the same rest API endpoints.
  • You need to create a new SSO policy to ensure that any request directed to the
    http://hostname:port/tokens/rest/v1
    endpoint is not protected. This will allow requests that use tokens to bypass SSO and enable users to be authenticated based on
    Clarity
    API keys.
  • Unprotecting the
    http://hostname:port/ppm
    endpoint will not enable you to use REST APIs and API keys in an SSO environment.