Guide to developing client applications with the ForgeRock® Identity Edge Controller (IEC).

To register a device:

1. Your client application must include the libiecclient.h library and a call to iec_device_register().

   See the sample client application register_device.c. This sample application includes dynamic client initialization, shown in "Initializing a Client Dynamically".

2. If you are working in the training environment, the sample application is already present in ~/forgerock/examples/register_device. If you are not working in the training environment, create a new directory in the ~/forgerock/examples directory, with the same name as your client application and place the C application in that directory.

   For example, copy register_device.c into a new directory named register_device:

   mkdir ~/forgerock/examples/register_device
   cp register_device.c ~/forgerock/examples/register_device

3. Set the device ID and any custom registration data. In the example, the device ID is Narwhal. ^[2]

   Note

   The registration data is discarded as soon as the device is registered. No registration data is stored in AM.

4. Run the build script to set the build variables and build the application:

   ~/forgerock/build-examples.sh

   The build script creates the application register_device in the ~/forgerock/examples/register_device directory:

   ls examples/register_device/
   register_device register_device.c
   

5. Run the example application:

   cd ~/forgerock/examples/register_device
   ./register_device
   *** Registering a device
   *** SDK function(s): iec_initialise, iec_device_register
   
   Setting dynamic attributes... Done
   
   Initialising sdk... Done
   
   Registering device (id: Narwhal)... Done

   If the registration was successful, you should see the Narwhal identity in the Edge Identity Manager Console. The reg-dev-client identity is the identity of your client application, set with the IEC_CLIENT_ID dynamic attribute.

To get the configuration for a device:

1. Your client application must include the libiecclient.h library and a call to iec_device_configuration(), with the deviceId parameter.

   See the sample client application get_device_configuration.c.

   The sample application includes "Initializing a Client Dynamically" and "Registering a Device".

2. If you are working in the training environment, the sample application is already present in ~/forgerock/examples/get_device_configuration.

   If you are not working in the training environment, create a new directory in the ~/forgerock/examples directory, with the same name as your client application and place the C application in that directory.

   For example, copy get_device_configuration.c into a new directory named get_device_configuration:

   mkdir ~/forgerock/examples/get_device_configuration
   cp get_device_configuration.c ~/forgerock/examples/get_device_configuration

3. Set the deviceId. In the example, the deviceId is Ibex.

4. Make sure that the build script is executable, then run the script to set the build variables and build the application:

   ~/forgerock/build-examples.sh

5. The build script creates the application get_device_configuration in the ~/forgerock/examples/get_device_configuration directory:

   ls examples/get_device_configuration/
   get_device_configuration get_device_configuration.c

6. Run the example application:

   cd ~/forgerock/examples/get_device_configuration
   ./get_device_configuration
   *** Registering a device
   *** SDK function(s): iec_initialise, iec_device_register, iec_device_configuration, iec_json_*
   
   Setting dynamic attributes... Done
   
   Initialising sdk... Done
   
   Registering device (id: Ibex)... Done
   
   Requesting configuration for device (id: Ibex)... Done
   
   Parsing configuration: {  }... Done
   
   Extract the "minimum" value from the configuration...Not set

   If the initialization and registration were successful, you should see the get-config-client and Ibex device identities in the Edge Identity Manager Console.

   Initially there is no device configuration so the sample client returns an empty JSON object as the value of Parsing configuration: { }.

7. In the Edge Identity Manager console, Set the Device Configuration under the IEC profile, in JSON format, for example:

   {
     "display": "mountain goat",
     "minimum": 123
   }

   The sample application returns the value of the minimum property, if set.

8. Run the example application again:

   ./get_device_configuration
   *** Registering a device
   *** SDK function(s): iec_initialise, iec_device_register, iec_device_configuration, iec_json_*
   
   Setting dynamic attributes... Done
   
   Initialising sdk... Done
   
   Registering device (id: Ibex)... Done
   
   Requesting configuration for device (id: Ibex)... Done
   
   Parsing configuration: { "display": "mountain goat", "minimum": 123 }... Done
   
   Extract the "minimum" value from the configuration...123

   Notice that the configuration that you entered in the Edge Identity Manager console is now returned by the client.

   In a real application, the client would place this configuration in the specified memory area on the device.

To request an OAuth2 token:

1. Your client application must include the libiecclient.h library and a call to iec_device_tokens(), with the deviceId parameter.

   See the sample client application get_device_tokens.c.

   The sample application includes "Initializing a Client Dynamically" and "Registering a Device".

2. If you are working in the training environment, the sample application is already present in ~/forgerock/examples/get_device_tokens. If you are not working in the training environment, create a new directory in the ~/forgerock/examples directory, with the same name as your client application and place the C application in that directory.

   For example, copy get_device_tokens.c into a new directory named get_device_tokens:

   mkdir ~/forgerock/examples/get_device_tokens
   cp get_device_tokens.c ~/forgerock/examples/get_device_tokens

3. Set the device ID and any custom registration data. In the example, the device ID is Rhino.

4. Make sure that the build script is executable, then run the script to set the build variables and build the application:

   ~/forgerock/build-examples.sh

5. The build script creates the application get_device_tokens in the ~/forgerock/examples/get_device_tokens directory:

   ls examples/get_device_tokens/
   get_device_tokens  get_device_tokens.c

6. Run the example application:

   cd ~/forgerock/examples/get_device_tokens
   ./get_device_tokens
   *** Getting OAuth 2.0 access and ID tokens for a device
   *** SDK function(s): iec_initialise, iec_device_register, iec_device_tokens, iec_json_*
   
   Setting dynamic attributes... Done
   
   Initialising sdk... Done
   
   Registering device (id: Rhino)... Done
   
   Requesting OAuth 2.0 ID token for device (id: Rhino)... Done
   
   Extracting access and id tokens...
   	access token: 8-Nfp1wH_ws41Cmgut_aImRXBsQ
   	id token: eyJ0eXAiOiJKV1QiLCJraWQiOiJ3VTNpZklJYUxPVUFSZVJCL0ZHNmVNMVAxUU...H4GrQ

   If the initialization and registration were successful, you should see the get-device-tokens-client and Rhino device identities in the Edge Identity Manager Console.

   The client returns the access and id tokens for the device. In a real application, the client would place these tokens in the specified memory area on the device.

To pair the user with a device:

1. Your client application must include the libiecclient.h library and calls to iec_user_code() and iec_user_tokens() with the deviceId parameter.

   See the sample client application get_user_tokens.c.

   The sample application includes "Initializing a Client Dynamically" and "Registering a Device".

2. If you are working in the training environment, the sample application is already present in ~/forgerock/examples/get_user_tokens.

   If you are not working in the training environment, create a new directory in the ~/forgerock/examples directory, with the same name as your client application and place the C application in that directory.

   For example, copy get_user_tokens.c into a new directory named get_user_tokens:

   mkdir ~/forgerock/examples/get_user_tokens
   cp get_user_tokens.c ~/forgerock/examples/get_user_tokens

3. Set the deviceId. In the example, the deviceId is Springbok.

4. Make sure that the build script is executable, then run the script to set the build variables and build the application:

   ~/forgerock/build-examples.sh

5. The build script creates the application get_user_tokens in the ~/forgerock/examples/get_user_tokens directory:

   ls examples/get_user_tokens/
   get_user_tokens  get_user_tokens.c

6. Run the example application:

   cd ~/forgerock/examples/get_user_tokens
   ./get_user_tokens
   *** Getting OAuth 2.0 user tokens via device flow
   *** SDK function(s): iec_initialise, iec_device_register, iec_user_code, iec_user_tokens, iec_json_*
   
   Setting dynamic attributes... Done
   
   Initialising sdk... Done
   
   Registering device (id: Springbok)... Done
   
   Requesting a user code for device (id: Springbok)... Done
   
   Please instruct the user to visit:
   	http://am.iec.com:8080/openam/oauth2/realms/root/realms/edge/device/user?nonce=0
   and enter user code: XDQm3PXK
   
   Requesting user tokens for device (id: Springbok)...

   The client outputs an instruction to the user to visit the Verification URL with the specified code. The Verification URL corresponds to the URL that is set in the OAuth2 Provider service in AM. In the training environment, this URL is http://am.iec.com:8080/openam/oauth2/realms/root/realms/edge/device/user?nonce=0.

7. Navigate to that URL and enter the code returned by the client (XDQm3PXK in this example).

   Important

   If you have the AM console open, use a private browser session to test this step, otherwise the AM takes the credentials of the existing logged in user.

8. Log in to AM as the sample user you created at the beginning of this procedure (bjensen).

   AM returns a message indicating that the specified device (springbok) is requesting access to your account. Select Allow.

9. The client returns the user tokens in the output:

   Requesting user tokens for device (id: Springbok)...
   Done: {
       "access_token": "rwZDFemw-xK2hRvkcG1bJusACuU",
       "id_token": "eyJ0eXAiOiJKV1QiLCJraWQiOiJ3VTNpZklJYUxPVUFSZVJCL0...",
       "token_type": "Bearer",
       "expires_in": 3599
       }

   In a real application, the client would place these tokens in the specified memory area on the device, authorizing the device to access the specified user resources.

Before you start this example, write a custom IEC Command Handler script and map it to a command key in IEC. The following procedure sets up a Hello World script:

1. In the AM console, in the edge realm, select Scripts > New Script.

2. Set the script Name to Hello World and the Script Type to IEC Command Handler then select Create.

3. In the Script field, paste the following Groovy script:

   import groovy.json.JsonOutput
   import groovy.json.JsonSlurper
   
   logger.info("Running custom command handler script")
   
   // Pre-defined variables passed to the script
   def jsonSlurper = new JsonSlurper()
   def reqJson = jsonSlurper.parseText(request)
   
   if (reqJson.command == "HELLO_WORLD") {
   	response = JsonOutput.toJson([response: 'Hello World from an AM Command Script'])
   } else {
       def errorMessage = "Unexpected '${reqJson.command}' command"
       logger.error(errorMessage)
       response = JsonOutput.toJson([response: 'error', message: errorMessage])
   }

4. Select Validate to check the script syntax, then select Save Changes.

5. Copy the script ID from banner at the top of the page (for example Scripts > 20d894e8-a645-4128-a5d1-e561c249db9a).

6. Select Services > IEC Service.

7. Under Command Script Mapping, enter HELLO_WORLD as the Key and the script ID (20d894e8-a645-4128-a5d1-e561c249db9a) as the Value.

8. Select Add and Save Changes.

1. Your client application must include the libiecclient.h library and a call to iec_device_custom_command() with the deviceId and the command key (HELLO_WORLD) as parameters.

   See the sample client application run_device_custom_command.c.

   The sample application includes "Initializing a Client Dynamically" and "Registering a Device".

2. If you are working in the training environment, the sample application is already present in ~/forgerock/examples/run_device_custom_command.

   If you are not working in the training environment, create a new directory in the ~/forgerock/examples directory, with the same name as your client application and place the C application in that directory.

   For example, copy run_device_custom_command.c into a new directory named run_device_custom_command:

   mkdir ~/forgerock/examples/run_device_custom_command
   cp run_device_custom_command.c ~/forgerock/examples/run_device_custom_command

3. Set the deviceId. In the example, the deviceId is Yak.

4. Make sure that the build script is executable, then run the script to set the build variables and build the application:

   ~/forgerock/build-examples.sh

5. The build script creates the application run_device_custom_command in the ~/forgerock/examples/run_device_custom_command directory:

   ls examples/run_device_custom_command/
   run_device_custom_command  run_device_custom_command.c

6. Run the example application:

   cd ~/forgerock/examples/run_device_custom_command
   ./run_device_custom_command
   *** Running a device custom command
   *** SDK function(s): iec_initialise, iec_device_register, iec_device_custom_command, iec_json_*
   
   Setting dynamic attributes... Done
   
   Initialising sdk... Done
   
   Registering device (id: Yak)... Done
   
   Executing 'Hello World' custom command... Done
   
   Received response: Hello World from an AM Command Script

   The client outputs the Hello World text.