FME Version
Introduction
Security is always a significant consideration when working with any online service. The REST API works with security in two ways: authorization and authentication. Authentication proves that the user is who they say they are. Authorization verifies that the user is authorized to make the call.
Most calls to FME Server require authorization. The REST API uses tokens to prove the user is permitted to make the call to the server. A token is a string of encrypted information that is sent between the client and the server. Token Security will not be as secure as other methods, as the security of the system depends on controlling access to the tokens.
While creating tokens to use with the REST API, try to limit the permissions the token is given. If the token is exposed, there will be limited access to the rest of the server.
If you are looking to create/manage tokens for FME Server 2018 or older, please see the documentation.
Types of Tokens
There are two types of tokens in FME Server: API and Session.
API Tokens
API Tokens should be used to provide applications with unauthenticated access to components in FME Server. One example of using an API Token is if you would like to share your workspace either through an FME Server App or Webhook URL. Depending on what method you choose, you may need to generate the token separately through the Token Management page or the token creation may be included as a step in the share workspace process.
From the Token Management page, API Tokens can be enabled, disabled, duplicated, or removed and all expired tokens will also be listed.
Session Tokens
Session Tokens are assigned all the permissions that the user who created them has. These should be short-lived and are designed to be used by FME Server’s internal services and for testing purposes. Session tokens have fewer actions available than API tokens: they cannot be duplicated and once expired, these cannot be re-activated.
Token Type | Created By | Default Expiry Time |
---|---|---|
Web Application (SSO) Login | Log in to FME Server Web UI | 30 minutes (FME Server automatically extends this period if you remain logged in for more than 25 minutes) |
Token Service Login | Created using fmetoken/generate endpoint | 5 minutes (unless otherwise specified in the query string parameters) |
FME REST API | When you 'get token' from FME Server REST API V3 | 1 hour |
It is possible this list may expand in the future.
These tokens should not be used in applications or shared between users. Expired Session Tokens have a clean-up task and by default, will be removed once they are a week old.
Obtaining API Tokens
API Tokens can be obtained manually via the Token Management page. These tokens can be downloaded and used in external applications. Additionally, tokens can be automatically created when building an FME Server App or creating a webhook. How to manually create a token will be outlined below.
Obtaining a Token Through the Token Management Page
1. Log into FME Server
Open the FME Server Web Interface, and log into an account that has permissions to create a new user as well as create tokens.
2. Open the Tokens Management Page
In the top-right corner, click on the user icon, and from the drop-down select Manage Tokens.
Depending on your level of permissions, you may see API Tokens, Session Tokens, All Tokens as tabs across the top of the Token Management page. For this demo, we will be focusing on API tokens. To learn more about the other options, see the documentation.
3. Create a New Token - Metadata
In the API Token section, click on New to create a new token.
On the Create New API Token page, enter the following parameters:
Token Name: REST API Demo
Description: Token to be used during training
Expiration: 1 week
Enabled: On
All Permissions: Off
4. Assign Permissions to Token
Next, we need to assign permissions to the token. We can use this token for the REST API training course or most of the REST API articles on the Knowledge Base. If you have a specific use case, please set your permissions accordingly. To learn more about what each permission includes, see the documentation: expand To Create an API Token > About permissions in FME Server, then expand the permission of interest.
Permission | Level of Permission |
---|---|
Repositories | Access |
Individual Repositories - Click the drop-down arrow to expand the section | Samples = Download, Read, Run |
Resources | Access |
Run Workspace | Access |
Note: If you are creating a web application, the permissions for the token should be limited to a specific repository.
Once the permissions have been set, click OK.
5. Download Token
Once the token has been created, you will see a page with your token visible. This is the only time you’ll be able to see this token within FME Server. To access it later, click the Download button to download the token.
The token is downloaded in an unsecured text (.txt) file.
Grant Additional Permissions
There are a lot of features within FME Server that are intertwined and rely on permissions for other features to work, such as Automations. After clicking OK depending on which permissions were set, a popup dialog may appear asking to grant additional permissions for other features. When creating the token, it is important to evaluate whether or not the token user will actually need access to these features.
Using a Token
Tokens can be included in the authorization header or in the query parameter
Authorization Header
Including the token inside of the Request Header is the preferred method. This is because the token will be hidden inside the call.
The name of the header would be Authorization and the Value would be:
fmetoken token=<yourTOKEN>
Replace everything after the = with your token that you downloaded from FME Server.
Query Parameter
You may include the token right in the Request URL of the call. This is a quick and easy way to use a call that requires a token.
http://<yourServerHost>/fmerest/v3/info?fmetoken=<yourToken>
However, this is not recommended because the token will be visible in the URL.
FME Token Service
The FME Token Service was deprecated in 2019. This service will remain in the product for backward compatibility and will continue to work for creating new tokens, however, it will not be able to update or retrieve existing Tokens. If used, this service generates a session token so permissions cannot be restricted.
Response from http://<fmeserver>/fmetoken for 2019.
Instead, generate a token from within an application; this can be done using the tokens endpoint in FME Server REST API. If you do not already have a session token that can authorize this request, you can use basic authentication to submit your user credentials through a header:
- Combine your username and password with a colon e.g. admin:admin
- Encode this string as Base64 e.g. YWRtaW46YWRtaW4=
- Set the Header e.g. Authorization: Basic YWRtaW46YWRtaW4=
Every token has a unique name, so once created, you can use this in various REST API requests to perform additional actions including retrieve, update and delete tokens, as through the FME Server Web UI.
Additional Resources
Tutorial: Getting Started with APIs
FME Server REST API training course
REST API Documentation
Managing Security Tokens Documentation
2018 or older Token Service Documentation Note the way tokens are managed was changed in 2019.
Comments
0 comments
Please sign in to leave a comment.