OAuth 2.0 Credentials
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.
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).
OAuth grant types determine how a client application (in this case, MapForce) communicates with the OAuth service and gets an access token. The following grant types are supported:
•Resource Owner Password Credentials
Depending on the selected grant type, different properties become available. For more information about each property, see the options below.
|
An authorization endpoint is a URI to which a resource owner (i.e., a user) is redirected to initiate authentication, consent, and authorization. The authorization endpoint is provided by an authorization server. When MapForce wants to get access to the user's resources, MapForce redirects the user's browser to the authentication endpoint. After authentication, the user decides whether to grant or deny permission to MapForce. After the authorization decision has been taken, the authorization server redirects the user to the path specified in the Redirect URI parameter.
You can obtain the authorization endpoint after registering with the Web service provider.
|
A token endpoint is a location where a client application (in this case, MapForce) makes a request to get an access token in exchange for certain credentials or authorization details. You can get this value after registering with the Web service provider.
|
A client ID is a unique public identifier of a client application (MapForce in this case). The client ID is issued by an authorization server. The authorization server uses the client ID and secret (described below) to verify the client's identity. You can get this value after registering with the Web service provider.
|
A client secret is a confidential bit of information that a client application (in this case, MapForce) uses for authentication. The client secret is issued by an authorization server. The authorization server uses the client ID and secret to verify the client's identity. The client secret helps prevent unauthorized applications from impersonating clients and accessing users' resources. You can get the client secret after registering with the Web service provider.
|
A scope defines the extent of access to a user's resources that a client (in this case, MapForce) requests (e.g., read and write privileges). You can get this value after registering with the Web service provider.
|
An access token is a piece of data that the client (i.e, MapForce) receives from an authorization sever after the authorization process has been completed successfully. The access token allows MapForce to access the user's resources. The mapping will be executed successfully only if the resource server determines that the access token is correct and valid. The access token expires after a period of time set by the Web service provider. For the token to be refreshed, certain conditions must be satisfied (see details in How Token Are Refreshed below).
|
Access tokens (see above) are short-lived for security reasons. The expiration time of an access token is determined by an authorization server. If the authorization server supports refresh tokens, it will issue a refresh token together with an access token during the authorization process. For details about how tokens are refreshed, see the subsection called How Tokens Are Refreshed below.
|
The Username and Password fields become available when you select the Resource Owner Password Credentials grant type. In this grant type, the client application directly exchanges the user's credentials (username and password) for an access token and, optionally, for a refresh token. As soon as the client gets the user's credentials, the client sends a POST request to the authorization server. If the request is successful, the authorization server will issue an access token that the client can use to access the user's resources.
|
The Authorization section provides information about a redirect URI and enables you to specify how to submit authentication details.
Redirection URIA redirect URI is the location to which an authorization sever redirects a user after the user has granted or denied permission to a client (in this case, MapForce). It is also the location to which the authorization server sends an authorization code that is required to get an access token. By default, MapForce automatically sets a URI for communicating with the authorization server. If the authorization server requires a different port, select the Specific port check box and enter the relevant port.
Make sure to copy the redirection URI and add it to the list of allowed redirection URIs on the platform where you register your client application.
Token Endpoint AuthenticationToken endpoint authentication (also known as client authentication) refers to the process of verifying the identity of a client application (i.e., MapForce) by an authorization server. The authorization server then decides whether to grant or deny the client permission to get an access token form the token endpoint. Client authentication ensures that the authorization server issues an access token only to a legitimate client.
Most OAuth 2.0 authorization servers require that authentication details be submitted in the POST request header. Some OAuth 2.0 authorization servers accept authentication details only in the body of the POST request. Depending on the requirements of the authorization server, select the relevant option from the drop-down list.
|
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.
•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.