Altova MapForce 2025 Enterprise Edition

To run a mapping that requires OAuth 2.0 authorization in MapForce, you will need to create an OAuth 2.0 credential, using the Credentials Manager, fill in the OAuth 2.0 details, and go through a manual authorization process as described below. The Add/Edit Credential dialog shown below appears when you create an OAuth 2.0 credential or when you edit an existing OAuth 2.0 credential. For information about each property, see the Available Parameters subsection below.

mf_oauth2_credential

About OAuth 2.0 workflow

OAuth stands for Open Authorization and is an open-standard authorization framework that allows applications to access a set of user resources on behalf of a user. The broad procedures associated with the OAuth 2.0 workflow are described below:

 

1.A third-party application (Client) registers with an authorization server. The authorization server issues a client ID and, if applicable, a client secret.

2.The Client indicates a redirection URI, to which a User will be redirected after granting or denying permission to the Client.

3.The User initiates an action in the client application, which requires access to the User's resources. For example, the User may want to log into the client application, using their Facebook account.

4.The Client sends a request to the authorization server and redirects the User to the authorization endpoint of the authorization server, where the User logs in and grants or denies permission to the Client. The Client's request to the authorization server contains the client ID, requested privileges, and the redirect URI.

5.If the the User has granted permission to the Client, the Client receives an authorization grant and exchanges the user credentials or authorization details (this depends on the grant type) for an access token and, if applicable, a refresh token.

6.The Client then uses the access token to access the User's resources on the resource server.

7.If the access token has expired, the Client can use the refresh token to continue using the User's resources without the User's re-authentication. Whether the Client uses the refresh token or not depends on the grant type you have selected. See the Access Token property below for more details.

 

Available parameters

The fields associated with an OAuth 2.0 credential object are listed below. To obtain these values, you must first register with a Web service provider (e.g., Google API Console, Facebook API, Bitbucket API).

 

 

After you have filled in the fields above, click Request Access Token to obtain an access token required to run the mapping. The exact authorization process depends on the Web service provider and grant type. For example, if you have selected the Authorization Code grant type, the authorization process will typically require that you manually confirm in a browser window that you grant access to the Web service to establish your identity (e.g., your Google account if the mapping calls a Google API). At the end of the process, MapForce displays a confirmation message that the access token has been obtained from the server.

 

Note that the access token will be saved only if you select the Save encrypted in MFD file check box (see Credentials). If you do not select the Save encrypted in MFD file check box, you will need to manually authorize each time when you run the mapping.

 

How tokens are refreshed

The access token may expire after some time. The period after which the token expires depends on the Web service provider. The access token may explicitly be revoked by the Web service provider. When this happens, the Messages window will display authorization errors when you attempt to preview the mapping.

 

Note that MapForce does not refresh OAuth 2.0 tokens. If the access token has expired, you can request a new access token, irrespective of the grant type, by using the Request Access Token button and going through the authorization process again before you can run the mapping. If you run your mapping under FlowForce Server management, FlowForce Server will attempt to refresh the token under certain circumstances that depend on the grant type you have selected (see subsections below).

 

Authorization Code grant type

If you run your mapping under FlowForce Server management and have set the Authorization Code grant type, FlowForce Server will attempt to refresh the token only under the following conditions:

 

A mapping that uses an OAuth 2.0 credential must be deployed to FlowForce Server.

The OAuth 2.0 credential linked to the mapping must be deployed to FlowForce Server, or you can create this OAuth 2.0 credential object directly in FlowForce Server.

A FlowForce job that executes the mapping must refer to the relevant OAuth 2.0 credential that you deployed to or created previously on FlowForce Server (screenshot below). This way, the OAuth 2.0 credential object will be linked to the mapping step.

MF_OAuth2CredentialForMapping

The OAuth 2.0 credential object must have a valid non-empty Refresh token value in FlowForce Server.

 

Client Credentials and Resource Password Credentials grant types

If you have selected the Client Credentials or the Resource Password Credentials grant type, FlowForce Server will attempt to get a new token only under the following conditions:

 

All the relevant authorization details of the selected grant type must be provided (e.g., Client ID, Client Secret, etc.).

A mapping that uses an OAuth 2.0 credential must be deployed to FlowForce Server.

The OAuth 2.0 credential linked to the mapping must be deployed to FlowForce Server, or you can create this OAuth 2.0 credential object directly in FlowForce Server.

A FlowForce job that executes the mapping must refer to the relevant OAuth 2.0 credential that you deployed to or created previously on FlowForce Server (screenshot above). This way, the OAuth 2.0 credential object will be linked to the mapping step.

 

If the token has expired, FlowForce Server will try to obtain a new one, by sending a request to the token endpoint.

 

© 2018-2024 Altova GmbH