Web Connections and FME

Web Connections are a convenient and secure way of storing web service credentials in FME so they can be reused. Web connections can be shared from FME Form to FME Flow. 

FME supports a wide variety of web connections. You can also download additional ones from the FME Hub.

This article will cover the Configuring and Creating Web Services in FME, as well as the three authorization protocols we support for creating web connections:
OAuth 2.0
Token
HTTP

A web service and web connection are different objects in FME:

Web Service

A Web Service definition contains all the information the FME needs to connect to that service and how that service expects to authorize FME. There are a few different authorization protocols we support: OAuth 2.0, Token, and HTTP Authentication.

Web Connection

The Web Connection is where you enter user credentials to connect to a web service as per the web service definition. Once a web service is defined in FME, many web connections can be created from it.

Configuring and Creating Web Services in FME

Many web connections in FME work out of the box. This means that when you’re using a particular Connector transformer for your web service, or the HTTPCaller, you can create your web connection without editing the web service definition. This is because Safe Software has already registered applications with those web services, and for OAuth 2.0 we are using Safe’s Client ID and Client Secret. 

If you’re beginning to author your workspace and testing it out these ‘out of the box’ connections are great to use. However, if you’re authoring a workflow that will be used repeatedly or in production workflows we recommend registering your own application with the web service. This is because Safe’s authorization credentials could be revoked or subject to service outages at any time, which would impact any users who haven’t registered their own application with the web service. If you plan to use the web connection on FME Flow, you must register your own application, or the web connection will stop working after a brief period.

Web Connections and Web Services are managed from Tools > FME Options.

Learn more about each of the authorization protocols we support:

OAuth 2.0

OAuth 2.0 is an authorization protocol, which allows an application to act on behalf of a user. This is done using an access token. Depending on the web service used, a user will normally be required to authenticate with that service to generate an access token (behind the scenes). The client application, in this case FME, will use that access token going forward to connect to the web service. Access tokens are short-lived: when the access token expires, the client application will use a second token, the refresh token, to obtain a new one.

For more detailed information on OAuth 2.0, see oauth2.net. This article intends to explain OAuth 2.0 in the context of FME Web Connections and is not intended to fully explain how OAuth 2.0 works.

Refer to your web service provider's documentation when configuring an OAuth 2.0 web service in FME.
You will need the following:

1 Client ID 

Public identifier for your registered application

2 Client Secret

Secret string (like a password) that is only known to your application and the authorization server

3 Redirect URI 

This is where the service will redirect the user after they have authorized the application. This must be the same in the web service definition as what is specified in the registered application. If your web service doesn’t provide one, you can typically use https://localhost/ for FME Form and https://<public FME Flow address>/fmeoauth for FME Flow. ArcGIS Online and some other services may allow you to use the string urn:ietf:wg:oauth:2.0:oob which tells the service to redirect back to the application that made the call. Always refer to your web service's documentation.

4 Authorization URL

The authorization URL, or endpoint, directs you to the right location to authorize. This URL or endpoint will contain a scope. If you’re registering your own application with a web service you will need to make sure the correct scope is specified. The scope determines what permissions or access the application will have to that web service.

5 Retrieve Token URL

URL used by the application to obtain an access token

6 Refresh Token URL

URL used by the application to refresh the access token

Please see Creating an OAuth 2.0 Web Service Connection in FME for more detailed instructions. 

Token

Token authorization is used in place of a username and password. You will normally either obtain a token when registering an application with your web service or by passing your username and password so the application can generate its own token.

The token may need to be given specific permissions for authorization with the web service. 

The token should be protected and not made publicly available. It's recommended to store it in a password or secrets manager.

There is also an OAuth 2.0 Client Credentials grant type that follows the same flow as a Token Web Service. If your web service provider uses the OAuth 2.0 Client Credentials grant type, create a token web service instead of an OAuth 2.0 web service service in FME.  

Refer to your web service provider's documentation when configuring a token web service in FME.
You will need the following:

1 Access Token Request

This Request URL and Request Data (parameters) will be used by FME to request an access token.

2 Access Token Response

Key names returned by the Request URL that identify the token and expiry time

3 API Call Parameters

Once FME receives an access token, the API Call Parameters tell FME how to use it when authenticating to the web service. The web service may expect the token to be provided in the HTTP header, the query string, or both. The web service will also expect the HTTP header or query string to be formatted a certain way. Consult your web service provider's documentation.

The article Creating a Token based Web Service in FME - Yelp provides an example of setting up a Token. We also have an example of setting up a token service with Cityworks

HTTP

HTTP Authentication is a simple technique for gaining access to web services as the user only provides a username and password. This is often referred to as basic authentication.

This would likely be used in the HTTPCaller transformer where the URL entered will accept a username and password to grant access to a web service or API.