Configuring identity management for FAPI

FAPI requires additional managed object types to store API client information.

This page explains how to add the managed object types over REST using a PingOne Advanced Identity Cloud service account. Although it’s possible to add managed object types through the Advanced Identity Cloud admin UI, using the REST API is less error-prone.

Create a user account

Create a PingGateway user account with the Advanced Identity Cloud identity management service. This account has administrative access to the identity management service. It lets PingGateway access FAPI client information to verify digital signatures.

In the Advanced Identity Cloud admin UI, go to open_in_new Native Consoles > Identity Management > to open the IDM admin console.

Go to Manage Users > New Alpha realm - User and create the user account:

Field Description Example

Field	Description	Example
Username	PingGateway uses this account to access API client profiles in the identity management service.	`gateway-idm-user`
First Name	The account schema requires a first name.	`PingGateway`
Last Name	The account schema requires a last name.	`Service Account`
Email address	The account schema requires an email address.	Your email address
Password	A strong password. Record the password as `gateway.idm.password` to use when configuring PingGateway.	`Secret12!` (base64-encoding: `U2VjcmV0MTIhCg==`)

Username

PingGateway uses this account to access API client profiles in the identity management service.

gateway-idm-user

First Name

The account schema requires a first name.

PingGateway

Last Name

The account schema requires a last name.

Service Account

Email address

The account schema requires an email address.

Your email address

Password

A strong password.

Record the password as gateway.idm.password to use when configuring PingGateway.

Secret12! (base64-encoding: U2VjcmV0MTIhCg==)

Click Save to display the new user account.
Click the Authorization Roles > Add Authorization Roles, assign the openidm-admin role to the service account, and click Add.

This role lets PingGateway read API client information.

You have successfully created the identity management user account for PingGateway.

Update the PingGateway OAuth 2.0 client

PingGateway uses the client account created during access management configuration for calls to identity management service APIs. This requires the client account to have the fr:idm:* scope.

In the Advanced Identity Cloud admin UI, go to web_asset OAuth2 Clients > gateway-oauth2-client > Sign On > General Settings.
In Scopes, add fr:idm:*.
Click Save.

You have successfully updated the OAuth 2.0 client account for PingGateway.

Prepare the update

PingOne Advanced Identity Cloud holds the managed object type configuration as a single JSON array of all managed object types.

To update the configuration, you’ll add your definitions to the array and replace the JSON resource. Don’t do this while someone else is changing the managed object type configuration.

Get an access token with scope fr:idm:* using the Resource Owner Password Credentials grant and the OAuth 2.0 client and identity management user accounts:

$ curl \
--request POST \
--user 'gateway-oauth2-client:password' \
--data 'grant_type=password' \
--data 'username=gateway-idm-user' \
--data 'password=Secret12!' \
--data 'scope=fr:idm:*' \
'https://myTenant.forgeblocks.com/am/oauth2/realms/root/realms/alpha/access_token'

Use the access token to get the current managed object configuration as a JSON file:

$ curl \
--request GET \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--header 'Content-Api-Version: protocol=2.1,resource=1.0' \
--output managed.json \
'https://myTenant.forgeblocks.com/openidm/config/managed'

The command saves the configuration as managed.json in the current folder.

In a text editor with support for JSON files, open the managed.json file.

Copy the following JSON objects to the "objects" array, taking care to add commas between objects.

apiClient.json

(Source: apiClient.json)

{
  "iconClass": "fa fa-database",
  "name": "apiClient",
  "onRead": {
    "globals": {},
    "source": "if (object.softwareId == null) {\n  object.softwareId = object.id\n}",
    "type": "text/javascript"
  },
  "schema": {
    "$schema": "http://forgerock.org/json-schema#",
    "description": "FAPI apiClient",
    "icon": "fa-cogs",
    "mat-icon": null,
    "order": [
      "_id",
      "softwareId",
      "name",
      "description",
      "deleted",
      "logoUri",
      "jwksUri",
      "ssa",
      "apiClientOrg",
      "oauth2ClientId"
    ],
    "properties": {
      "_id": {
        "deleteQueryConfig": false,
        "description": null,
        "isVirtual": false,
        "searchable": true,
        "title": "IDM Internal ID",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "apiClientOrg": {
        "deleteQueryConfig": false,
        "description": null,
        "isVirtual": false,
        "notifySelf": false,
        "properties": {
          "_ref": {
            "type": "string"
          },
          "_refProperties": {
            "properties": {
              "_id": {
                "propName": "_id",
                "required": false,
                "type": "string"
              }
            },
            "type": "object"
          }
        },
        "referencedObjectFields": null,
        "referencedRelationshipFields": null,
        "requiredByParent": false,
        "resourceCollection": [
          {
            "label": "apiClientorg",
            "notify": false,
            "path": "managed/apiClientOrg",
            "query": {
              "fields": [
                "id",
                "name"
              ],
              "queryFilter": "true",
              "sortKeys": []
            }
          }
        ],
        "returnByDefault": false,
        "reversePropertyName": "apiClients",
        "reverseRelationship": true,
        "searchable": false,
        "title": "API Client Organization",
        "type": "relationship",
        "userEditable": false,
        "validate": false,
        "viewable": true
      },
      "deleted": {
        "default": false,
        "description": "Has the ApiClient record been deleted",
        "isVirtual": false,
        "searchable": true,
        "title": "Deleted",
        "type": "boolean",
        "userEditable": true,
        "viewable": true
      },
      "description": {
        "searchable": true,
        "title": "Description",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "id": {
        "deleteQueryConfig": false,
        "description": null,
        "isVirtual": false,
        "searchable": true,
        "title": "API Client ID",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "jwks": {
        "searchable": false,
        "title": "JWK Set",
        "type": "object",
        "userEditable": false,
        "viewable": true
      },
      "jwksUri": {
        "searchable": true,
        "title": "JWKS URI",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "logoUri": {
        "searchable": true,
        "title": "Logo URI",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "name": {
        "searchable": true,
        "title": "API Client Name",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "oauth2ClientId": {
        "deleteQueryConfig": false,
        "description": "OAuth2 Client ID",
        "isVirtual": false,
        "searchable": true,
        "title": "OAuth2 Client ID",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "roles": {
        "items": {
          "type": "string"
        },
        "searchable": false,
        "title": "Roles",
        "type": "array",
        "userEditable": true,
        "viewable": true
      },
      "softwareId": {
        "deleteQueryConfig": false,
        "description": null,
        "isVirtual": false,
        "searchable": true,
        "title": "Software ID",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "ssa": {
        "description": null,
        "isVirtual": false,
        "minLength": null,
        "searchable": true,
        "title": "Software Statement Assertion",
        "type": "string",
        "userEditable": true,
        "viewable": true
      }
    },
    "required": [
      "name",
      "oauth2ClientId",
      "ssa",
      "deleted"
    ],
    "title": "apiClient",
    "type": "object"
  },
  "type": "Managed Object"
}

apiClientOrg.json

(Source: apiClientOrg.json)

{
  "iconClass": "fa fa-database",
  "name": "apiClientOrg",
  "schema": {
    "$schema": "http://forgerock.org/json-schema#",
    "description": "apiClientOrg Details",
    "icon": "fa-bank",
    "mat-icon": "",
    "order": [
      "name",
      "id",
      "created",
      "_id",
      "apiClients"
    ],
    "properties": {
      "_id": {
        "description": null,
        "isVirtual": false,
        "minLength": null,
        "searchable": false,
        "title": "Internal IDM Identifier",
        "type": "string",
        "userEditable": false,
        "viewable": true
      },
      "apiClients": {
        "deleteQueryConfig": false,
        "description": null,
        "isVirtual": false,
        "items": {
          "notifySelf": false,
          "properties": {
            "_ref": {
              "type": "string"
            },
            "_refProperties": {
              "properties": {
                "_id": {
                  "propName": "_id",
                  "required": false,
                  "type": "string"
                }
              },
              "type": "object"
            }
          },
          "resourceCollection": [
            {
              "label": "apiClient",
              "notify": false,
              "path": "managed/apiClient",
              "query": {
                "fields": [],
                "queryFilter": "true",
                "sortKeys": []
              }
            }
          ],
          "reversePropertyName": "apiClientOrg",
          "reverseRelationship": true,
          "type": "relationship",
          "validate": false
        },
        "minLength": null,
        "policies": [],
        "referencedObjectFields": null,
        "referencedRelationshipFields": null,
        "requiredByParent": false,
        "returnByDefault": false,
        "searchable": false,
        "title": "API Clients",
        "type": "array",
        "userEditable": false,
        "viewable": true
      },
      "created": {
        "searchable": true,
        "title": "Timestamp",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "id": {
        "deleteQueryConfig": false,
        "description": "API Client Organization ID",
        "isVirtual": false,
        "policies": [
          {
            "params": {},
            "policyId": "unique"
          }
        ],
        "searchable": true,
        "title": "API Client Organization ID",
        "type": "string",
        "userEditable": true,
        "viewable": true
      },
      "name": {
        "deleteQueryConfig": false,
        "description": "API Client Organization Name",
        "isVirtual": false,
        "searchable": true,
        "title": "API Client Organization Name",
        "type": "string",
        "userEditable": true,
        "viewable": true
      }
    },
    "required": [],
    "title": "apiClientOrg",
    "type": "object"
  },
  "type": "Managed Object"
}

Verify the objects are top-level objects in the array and check the JSON is syntactically correct.
Save your changes to the managed.json file.

Update the managed object configuration

To update the configuration, replace the JSON resource with the JSON from the managed.json file.

If the access token has expired, use the PingOne Advanced Identity Cloud service account to get a new access token with scope fr:idm:*.

Use the access token to update the managed object configuration with the JSON file you prepared:

$ curl \
--request PUT \
--header 'Authorization: Bearer <access-token>' \
--header 'Content-Type: application/json' \
--header 'Content-Api-Version: protocol=2.1,resource=1.0' \
--data @managed.json \
'https://myTenant.forgeblocks.com/openidm/config/managed'

PingOne Advanced Identity Cloud returns the JSON resource for the updated managed object configuration.

Validation

Review your updates through the Advanced Identity Cloud admin UI.

Sign on to the Advanced Identity Cloud admin UI as an administrator.
Go to open_in_new Native Consoles > Identity Management > Configure > Managed Objects.
Find your new managed object types in the list:

You have successfully added the managed object types to store API client and API client organization objects.