Authentication by Token

Included in iTop Community from 3.1.0

This extension adds iTop authentication for web services via Personal tokens and Application token instead of login/password.

This module provides two ways to use authentication token for API calls:

• An application token is a particular type of user in iTop.
  • It authenticates using a token and cannot connect to the iTop user interface (Console, portal …)
  • It has its own profiles and allowed organizations
  • It can access all APIs (REST, Synchro, Export ..) with no possible restriction
• A personal token is linked to an iTop user
  • It authenticates using a token and cannot connect to the iTop user interface (Console, portal …)
  • It inherits the profiles and allowed organizations from its associated user
  • It can be restricted to some a subset of the APIs (for example only REST/SJON and Export)
  • Only users with a (configurable) set of profiles are allowed to create and manage personal tokens.

If your company security policy forces every user to authenticate through a SSO (SAML, OpenID…), then Personal Tokens are the solution to access the iTop APIs, since non-interactive scripts do not support SSO mechanisms.

Personal tokens can also be used for creating spreadsheet (like Excel) or PowerBI dynamic reports.

authent-token v2.0.0 is compatible with below versions:

• 2.7: Offers only Application token, no Personal token
• 3.0: Personal token can't be used on IMPORT/EXPORT
• 3.1: No limitation.

How to install your extension

Those features are not enabled by default. You have to some following parameters to activate it.

Enrich iTop core configuration, with additional value on existing parameter

authent-token configuration

Sample configuration

config-itop.php

'allowed_login_types' => 'form|token|external|basic',
'allow_rest_services_via_tokens' => true,

config-itop.php

'authent-token' => array (
        'personal_tokens_allowed_profiles' => array (
                 0 => 'Administrator',
                 1 => 'Configuration Manager',
        ),
        'enable_myaccount_menu ' => true,
),

• Application Token is a new type of User in iTop.
• It is managed by the Administrator (or any user allowed to manage Users) via the User accounts menu
• Such user is not identified by a login and a password but via a Token, which is automatically generated at User creation

This user is linked to a Contact and identified by a name stored in Remote application field.

• This name is used in the Change history of iTop when such user create or modify elements
• This User must have profiles and can have Allowed organisations as any other user
• This User cannot connect to the iTop UIs (console, portals)
• This type of User is designed to access webservices pages (import and export), data synchronization and rest services
• As any User, it requires REST Services profile to access the REST API
• Token must be recorded after it as been generated as it cannot be displayed later
• Token can be rebuild, but in that case the old token would work anymore and the remote application must be changed to use the new token value

Personal Token is a separate object, automatically linked to an existing user.

• Personal Token gets automatically the Profiles and the Allowed organizations of its associated User, and they cannot be different.
• It allows connection to iTop Webservices (import and export), data synchro services and rest services
• Personal token cannot be used to connect to the iTop UIs (console, portals)
• If allow_rest_services_via_tokens is true, then all Personal Tokens can be used to access rest services, otherwise, rest is only accessible if the corresponding User has REST Services profile.
• Token must be recorded after it as been generated as it cannot be displayed later
• Token can be rebuild, but in that case the old token would work anymore and the remote application must be changed to use the new token value

They are two ways to manage personal token: either your allowed by your profil to manage the token by yourself, using the My Account Menu, or an Administrator will generate it for you.

To manage it by yourself, follow the my account menu, which is available as soon as you are allowed to manage Personal Tokens. If you don't have it, ask your iTop administrator either to give you a profile allowed to edit Personal tokens or ask him to create the token for you.

This page contains 3 sections:

• on the left : your current user (login/organization/profiles)
• on the right: your current contact (email, name,…)
• below: your personal tokens to authenticate as your current user under specified contexts (import, export, data synchro and rest)

In the token section you can:

• add a new token via '+' button on the right
• edit each existing token with pen button
• refresh each existing token to generate another token for authentication, for eg. if you lost it or if it was compromised (previous one is no more usable)
• delete any existing token with dustbin button

Personal Token fields

• application: name of the token
• scopes: context in which iTop authentication will work
• expiration date: if set, date after which token will expire and will not work anymore
• count: number of successful authentications with current token
• use date: date of the last successful authentication

When you create or rebuild a Token, copy the generated token to be used by your script as it won't be display anymore. If you forgot to do so, just regenerate the token.

As an administrator or with a profile allowed to edit PersonalToken class, you can manage all personal tokens.
For this uses below menu:

Then you can handle any token operation (add/modify/refresh/delete) for any User:

If you use a Personal token:

• the User must have REST Services profile or the configuration parameter allow_rest_services_via_tokens must be set to true
• the personal token must have REST API in its scope

If you use an Application token, it must have REST Services profile.

To call the Rest API and provide the token, you can either put it in the header or in a post parameter.

• in the header: 'Auth-Token: YOURTOKEN'
• in a POST parameter: auth_token=YOURTOKEN

curl example with token provided in the header

curl --location -g --request POST 'https://localhost/itop/Develop/webservices/rest.php?version=1.3&json_data={
"operation": "core/get",
"class": "Person",
"key": "SELECT Person WHERE email LIKE '\''%.fr'\''",
"output_fields": "friendlyname, email"
}' \
--header 'Auth-Token: YOURTOKEN'

curl example with token provided in the query

curl --location -g --request POST 'https://localhost/itop/Develop/webservices/rest.php?version=1.3&auth_token=YOURTOKEN&json_data={
"operation": "core/get",
"class": "Person",
"key": "SELECT Person WHERE email LIKE '\''%.fr'\''",
"output_fields": "friendlyname, email"
}'

Limitation: Authentication with a Personal token on Import and Export can only be used since release 3.1 of iTop.

The export-v2.php API is useful to extract data that are stored in QueryPhrasebbok for eg.

• With a Personal token, be sure that the Export is set in the Personal token scope.
• With an Application token, this part is automatic.

Below examples on how to export iTop data using wget and curl:

export-v2.php with wget

wget -q --server-response --post-data='auth_token=YOURTOKEN' --no-check-certificate -O - "http://xxx/itop31/webservices/export-v2.php?format=csv&login_mode=token&date_format=Y-m-d+H%3Ai%3As&query=14"

export-v2.php with curl

curl -X POST -F 'auth_token=YOURTOKEN' "http://xxx/itop31/webservices/export-v2.php?format=csv&login_mode=token&date_format=Y-m-d+H%3Ai%3As&query=14"

This authentication can fail for below reasons:

• token (credential) passed is not the write one
  • It can be due to a wrong copy-paste of the token
  • If someone refreshed the token object. Regenerate the token and copy-paste the new value before testing again

• token object (Personal token and Application token) has been deleted in iTop
• token (Personal token) has an expiration date and it is indeed expired
• token (Personal token) does not have the proper scope to handle the ongoing operation
• User associated with the Personal token is disabled in iTop
• Application token is disabled in iTop

Other possible root cause

• for a REST API call, Personal token does not have REST in its scope.
• same for collector calls without Synchro in the Personal token scope.
• For Personal token, maybe your user does not have the required profiles, check if you can query those objects in the console with your User.

Token handles authentication, authorizations uses iTop core mechanism based on Profiles.

• The fact that you can log in via a token to call REST APIs, does not guarantee that you will get a result. For this you must be privileged enough to execute it.