Authentication by Token
Included in iTop Community from
3.1.0
- name:
- Authentication by Token
- description:
- User and Application authentication using a token
- version:
- 2.1.1
- release:
- 2023-07-13
- itop-version-min:
- 2.7
- state:
- stable
- php-version-max:
- PHP 8.1
This extension adds iTop authentication for web services via Personal tokens and Application token instead of login/password.
Features
This module provides two ways to use authentication token for API calls:
-
Application token is a particular type of user in iTop.
-
It authenticates using a token and cannot connect to iTop UIs (Console, portal …)
-
It has its own profiles and allowed organizations
-
It can access all APIs (REST, Synchro, Export ..) with no possible restriction
-
-
Personal token is linked to an iTop user
-
It authenticates using a token and cannot connect to iTop UIs (Console, portal …)
-
It inherits from its associated user, profiles and allowed organizations
-
It can be restricted to some of AOI (Just REST and Export for eg.)
-
Management of its own personal token can be delegate to users with particular profile
-
If your company security policy forces every users to authenticate through SSO SAML, then Personal Token is the solution to access iTop APIs, which do not support SSO SAML. Export used by Excel or PowerBI dynamic report, is one of those APIs.
Revision History
Version | Release Date | Comments |
---|---|---|
2023-07-13 | 2.1.1 | * N°6521 - PHP 8.1: Fix deprecated notice for null value passed to string parameter of strlen() |
2023-07-03 | 2.1.0 | * N°6358 - Add support for login in REST
API using
tokens * N°6449 - Add support for personal tokens on iTop 3.1+ * German translation from Lars Kaltefleiter |
2023-07-23 | 2.0.0 | * Personal tokens handled via scopes and
expiration dates * My account menu added to handle your personal tokens and also your current user/contact * UserTokens renamed as ApplicationTokens |
2023-01-23 | 1.0.0 | * First version with application tokens called UserTokens (released as a module in combodo-intercom-integration/1.1.0) |
Limitations
authent-token v2.0.0 is compatible with below versions:
-
2.7: Offers only
Application token
, noPersonal token
-
3.0: Personal token can't be used on IMPORT/EXPORT
-
3.1: No limitation.
Requirements
Installation
How to install your extension
Configuration
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
Parameter | Description | Default |
---|---|---|
allowed_login_types | To log in via personal token you have to add token to _allowed_login_types_ option (rest-token also accepted with the same meaning for backward compatibility). This will enable this authentication mode among others (like the classical via login/password). | token mode not configured by default |
allow_rest_services_via_tokens | RestProfile are not mandatory anymore to reach and use Rest APIs or Data synchro CLI scripts. you can do it through PersonalTokens by using iTop below option (available since 3.0.3) | not configured by default |
authent-token configuration
Parameter | Description | Default |
---|---|---|
enable_myaccount_menu | To enable my account menu for everyone (by default invisible otherwise) You have to set enable_myaccount_menu to true. | false |
personal_tokens_allowed_profiles | To define which iTop profiles are allowed to manage and use personal tokens to authenticate. With this option, users with listed profiles can manage their personal tokens from 'My Account' menu along with their current user/contact. By default only Administrators can do it | none |
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, ),
Usage
Managing Application Token
-
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
Managing Personal Token
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 hasREST 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.
Manage your own
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 any more. If you forgot to do so, just regenerate the token.
Manage others
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:
REST with token
If you use a Personal token:
-
the User must have
REST Services
profile or the configuration parameterallow_rest_services_via_tokens
must be set totrue
-
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" }'
Export-v2 with token
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"
Troubleshooting
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.