Credentials
Credential objects provide a way to make authentication data (such as usernames, passwords, and OAuth authentication details) portable across various mapping execution environments, in a secure way. Credentials are useful in mappings that require basic HTTP authentication or OAuth 2.0 authorization. You can define credentials in MapForce and also in FlowForce Server. If credentials were defined in MapForce, you can optionally deploy them to FlowForce Server, similar to how mappings are deployed.
After you compile the mapping to a MapForce Server execution file (.mfx), MapForce Server will run the .mfx file depending on your choices at mapping design time.
If you selected the Include in MapForce Server Execution File and Mapping Deployment check box when creating the credential in MapForce, MapForce Server will use at mapping runtime any credentials that were stored in the .mfx file. This means that you can run the mapping with a command such as:
<exec> run mapping.mfx |
Where <exec> is the path to the MapForce Server executable. This path can be either absolute or, if the current directory is the same as the executable, you can enter just the executable name.
If you entered only the credential name (without username and password) in MapForce, then you must explicitly provide these details at mapping runtime, with the help of the --credential command line option available for the run command. This way, you can use, for example, a different set of credentials in production, as opposed to those used when you designed the mapping. The --credential option has the form --credential=KEY:VALUE., where
•KEY is the name of the credential as it was defined in MapForce.
•VALUE is a credential property, or a list of properties separated by ampersand (&). For credentials of type "password", the possible properties are username and password. For credentials of type OAuth 2.0, the only supported property is oauth:token.
•The actual property values are supplied just like query parameters in a URL, using the "=" sign.
For example:
<exec> run mapping.mfx --credential="mycredential:username=admin&password=4xJ38dnx7" |
In the code listing above, the value of the --credential option was enclosed within quotes in order to treat the value literally, since the username and password are separated by an ampersand character.
If your mapping needs multiple sets of named credentials to run, you can specify the --credential option multiple times.
The credentials supplied as command line options take precedence over stored credentials. |
If you did not select the Include in MapForce Server Execution File and Mapping Deployment check box, the sensitive fields are missing. This means that you must supply the password at the command line while still referring the credential by its name, for example:
<exec> run mapping.mfx --credential=mycredential:password=4xJ38dnx7 |
The following fields are considered sensitive data:
•Password (for credentials of type "Password") •Client Secret, Access Token, and Refresh Token (for credentials of type "OAuth 2.0") |
For mappings that require OAuth 2.0 authorization, the MapForce Server command line accepts an OAuth 2.0 access token as input at the mapping runtime. Note that the MapForce Server command line does not provide an interactive GUI by design, so you will need to obtain the OAuth 2.0 access token by external means (for example, by requesting it with MapForce) when using the command line specifically. This is, however, not necessary if MapForce Server runs under FlowForce Server management, since the latter is capable of acquiring a new OAuth 2.0 access token at runtime by itself.
At the command line, running the mapping with stored credentials is possible as long as the stored OAuth 2.0 token has not expired or has not been revoked by the Web service provider. To address this, supply a new OAuth 2.0 access token (obtained by some external means) by using the --credential option, for example:
<exec> run mapping.mfx --credential=my_oauth_credential:oauth:token=jdsaflkajlkewsaiurthczv904215-jhd |
Where:
•my_oauth_credential is the name of the OAuth 2.0 credential created from MapForce.
•oauth:token is the way to indicate to MapForce Server that a new OAuth 2.0 access token is being supplied at runtime.
MapForce Server API
The MapForce Server API provides methods to create credentials, add properties to credentials, and close credentials after you finished declaring them. The following code listing illustrates the typical way of declaring password credentials in a C# program that runs a mapping:
//Create a MapForce Server object |
To perform OAuth 2.0 authorizations from a program that runs a mapping, the credential property name must be set to oauth:token, as illustrated below:
//Create a MapForce Server object // Add the credential properties // Close the credential |
If the mapping needs multiple credential sets, use the methods above to add as many sets of credentials as required. Once you have declared all the required credentials, you can run the mapping execution file in a standard way, by calling the Run() method. For more information, see the API Reference.