Authenticate system users

System users

A system user is an automated program, or an application, that sends or receives data by specifying a service ID/API key token combination. A system user can be a combination of multiple programs, or applications, in which case they share the same token. Registering multiple system users with IBM Food Trust can be useful for managing distinct workloads, such as processing documents and sending messages, and to separate information types on your local system.

To configure a new system user, you must first create a new service ID/API key pair. You will then register the system user with IBM Food Trust by defining its service ID and API key in the Users module. Once registered, the system user will generate an IBM Food Trust service token, in order to make authenticated API calls, using the following sequence:

1. Specify the API key to request an IBM Cloud IAM token.
2. Exchange the IBM Cloud IAM token for an IBM Food Trust service token, which contains the service ID and password.
3. Specify the service token in the authorization header of API calls to IBM Food Trust.
4. Because service tokens expire one hour after being issued, either renew the token before expiration or repeat this process to generate a new service token.

Configure a system user

A one-time initial registration is required to allow a new system user to authenticate to IBM Food Trust. Only an Account Administrator for your organization can register system users. An Organization administrator must first create a unique service ID and API key pair for each system user, as follows:

1. Log in to IBM Food Trust and select the Users module.
2. Select System IDs and then click Add System ID:
   
3. Enter a name for your new System ID, and then click the text link to create a new service ID on IBM Cloud:
   
4. Log in to IBM Cloud using your IBMid (email address registered with IBM):
   
5. Select the Service IDs tab from the left menu:
   
6. Click the Create + button:
   
7. Enter a Name and Description for your service ID:
   
8. Select the API keys tab and click the Create + button:
   
9. Enter a name and description for your API key and click the Create + button:
   
10. Click the eye icon and copy and save the API key value to your local system! This is your only opportunity to save and record the API key value, which you will need later for automation:
    Your downloaded and saved API key (JSON) should look similar to the following example:

json
  {
      "name": "Solution API key",
      "description": "My Solution API key",
      "createdAt": "2018-05-03T16:00+0000",
      "apiKey": "wZvu952...gcci"
  }

1. Close the API key window. From the subsequent Manage Mysystem ID window, copy the service ID value ServiceId-######:
   
2. Return to the IBM Food Trust Add System ID dialog. Paste the service ID value copied from the previous step into the service ID field, and then click the Add System ID button:
   
3. The new System ID will be displayed in your IBM Food Trust Users panel:
   

Obtain an IBM Cloud IAM token

After you have registered the new service ID, the system user must generate an IBM Cloud IAM token using the following steps (an automated process):

1. Copies the following cURL command:
   bash curl -X POST --header "Content-Type: application/x-www-form-urlencoded" --data "grant_type=urn:ibm:params:oauth:grant-type:apikey" --data "apikey=<API_KEY>" https://iam.cloud.ibm.com/identity/token
2. Replaces <API_KEY> with the apiKey value from the JSON key file, and runs the command.
3. Receives a response similar to the following example:

{
  "access_token" : "eyJraWQiOiIyMDE3M...",
  "token_type"   : "Bearer",
  "expires_in"   : 3600,
  "expiration"   : 1523646898
}

Exchange an IBM Cloud IAM token for a service token

After obtaining an IBM Cloud IAM token, the system user must exchange it for an IBM Food Trust service token:

Windows users: Use an application such as Cygwin to run the following curl commands.

1. The system user copies the following cURL command:
   bash curl -X POST -H 'Content-Type: application/json' -d 'IAM_RESP_BODY' https://food.ibm.com/ift/api/identity-proxy/exchange_token/v1/organization/{ProductionOrganizationId}
2. The system user replaces IAM_RESP_BODY with the IBM Cloud IAM JSON object ("access_token" value) returned from the previous Obtain an IBM Cloud IAM token step.
3. The system user replaces {organizationId} with the organization ID and runs the command:
   Example: (expanded JSON)
   North America:

curl - X POST - H 'Content-Type: application/json' - d '
{
	"access_token": "eyJraWQ...",
	"refresh_token": "J1AV0...",
	"token_type": "Bearer",
	"expires_in": 3600,
	"expiration": 1525367304
}
' https://food.ibm.com/ift/api/identity-proxy/exchange_token/v1/organization/38d1...

Note: The organization ID is available from the SYSTEM IDS tab in the Users Module:

1. The system user receives a response similar to the following example: { "onboarding_token" : "eyJhbGciOiJSUzI1NiIsInR...", }
2. In the authorization header of API calls, the system user specifies the onboarding_token key (in the JSON object returned by the command), as Bearer <token>. The token expires one hour after being issued:

Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR...

Token expiration

Both the IBM Cloud IAM token and the IBM Food Trust service token are encoded with an expiration time. During the token exchange, the expiration time is copied from the IBM Cloud IAM token and applied to the IBM Food Trust service token, so they will both expire at the same time.

If an expired IBM Cloud IAM token is sent with an exchange token request, it will be rejected. If an expired IBM Food Trust service token is submitted with an API call, it will be rejected.

Code samples

The following code samples create an IBM Cloud IAM token and exchange it for an IBM Food Trust service token. You can use these examples to configure automation:

• Java sample
• IIB sample
• TypeScript sample

Troubleshooting

To resolve issues with system user configuration, use the following steps:

Issue: Receiving a 404 response when exchanging an IBM Cloud IAM token for an IBM Food Trust service token:

Example response:

{
  “ok”: false,
  “statusCode”: 404,
  “error”: “User Id: {SERVICE_ID} not found with solution Id: {SOLUTION_ID} and organization Id: {ORGANIZATION_ID}”
}

Action:

1. Verify that the service ID is registered as a system user in the IBM Food Trust Users module.
   If the system ID is not registered, follow the instructions to Register a system user.
2. Verify that the correct URL is being targeted in the CURL command: Command:

   curl -X POST -H 'Content-Type: application/json' -d 'IAM_RESP_BODY' https://food.ibm.com/ift/api/identity-proxy/exchange_token/v1/organization/{ProductionOrganizationId}

3. Verify that the correct organization ID is being specified in the CURL command. There are separate organization IDs for each corresponding zone. For example, if targeting the Integration zone, you must provide the Integration zone organization ID. If the organization ID is unknown for the corresponding zone, it can be found in the SYSTEM IDS tab under the Users section of the UI.