Dynamic Monitoring Using the ECID and RID HTTP Headers

Dynamic monitoring is the mechanism by which HTTP requests can be uniquely identified and thus tracked as they flow through the system.

It also provides a means by which context information can be communicated between cooperating Identity Cloud Service components involved in fulfilling requests. The Execution Context ID (ECID) and the Relationship ID (RID) are useful in tracking the sequence of events between services.

• The ECID: A unique identifier. The ECID is unique for each new root task. This number remains the same as it is shared across the tree of tasks associated with the root task.

• The RID: A relationship identifier. The RID is an ordered set of numbers that describes the location of each task in the tree of tasks. The leading number is typically a zero, and then the numbers increase for each additional subtask.

The X-ORACLE-DMS-ECID and the X-ORACLE-DMS-RID HTTP headers are returned as part of the REST response from Oracle Identity Cloud Service. These HTTP headers correspond to the ECID and the RID of the request. The values for these headers are set by Oracle Identity Cloud Service when returning the response. The caller can use the ECID and the RID to track and correlate requests that originate with events that arise from Oracle Identity Cloud Service.

For example, the client may include these values as part of an error message, since it is important to correlate events on the client side with errors on the server side. The Oracle standard format for logging involves a field dedicated to the ECID. After the ECID is known, when it is read from an error level log message, for example, it is possible to locate all other log messages associated with that task by querying the log files for messages that contain that ECID.

Use the Oracle Identity Cloud Service Diagnostic Data reports to view logging data captured for diagnostic purposes. You can locate the ECID and the RID in the report, and then correlate those identifiers to the ECID and the RID that are returned by the Oracle Identity Cloud Service REST calls that your applications make. See Running the Diagnostic Data Report.

Examples

This section contains examples that show the following:

• A POST request on the /Users endpoint.

• The cURL command headers that are a result of executing the POST on the /Users endpoint.

• A return response of a GET on the /AuditEvents endpoint that shows that the ECID is the same as what was used by the server to create the user.

• A section of the diagnostic report that was generated when the POST request on the /Users endpoint was run.

POST Request to /Users

curl -X POST -D dumpedHeadersPostUsers.txt
http://tenant-base-url/admin/v1/Users
-H 'Authorization: Bearer eyJ4NXQjUzI....poYw'
-H 'Cache-Control: no-cache'
-H 'Content-Type: application/json'
-d '{
   "schemas": [ 
    "urn:ietf:params:scim:schemas:core:2.0:User"
   ],
   "name": {
 	"givenName": "Clarence",
 	"familyName": "Saladna"
   },
   "userName": "[e-mail]",
   "emails": [
 	{
 	  "value": "[e-mail]",
 	  "type": "work",
 	  "primary": true
 	},
 	{
 	  "value": "[e-mail]",
 	  "primary": false,
 	  "type": "recovery" 
	}
   ]
 }'

cURL Command Headers in the Response

HTTP/1.1 201 Created
Date: Thu, 04 Jan 2018 12:57:37 GMT
Content-Type: application/json;charset=utf-8
Content-Length: 1227
Proxy-Connection: Keep-Alive
X-ORACLE-DMS-RID: 0
X-ORACLE-DMS-ECID: 0000M31FtLAFo2H6yvR_6G1QJ7Wl0000K

Response to the GET Request to /AuditEvents

Note: This example shows that the ECID is the same as what was used by the server to create the user.

Request

http://tenant-base-url/admin/v1/AuditEvents?filter=actorName sw "adm" and ecId eq "0000M31FtLAFo2H6yvR_6G1QJ7Wl0000K^"

Response

{
  "schemas": [
    "urn:scim:api:messages:2.0:ListResponse"
  ],
  "totalResults": 1,
  "Resources": [
    {
      "idcsCreatedBy": {
        "type": "User",
        "display": "admin opc",
        "value": "39e0f6b0654e45459f637fecb3cca25f",
        "$ref": "https://tenant-base-url/admin/v1/Users/39e0f6b0654e45459f637fecb3cca25f"
      },
      "actorName": "[e-mail]",
      "id": "2a02fb8bc9a548edb21fe1c80ff6ada0",
      "actorDisplayName": "admin opc",
      "meta": {
        "created": "2018-01-04T12:57:46.314Z",
        "lastModified": "2018-01-04T12:57:46.314Z",
        "resourceType": "AuditEvent",
        "location": "https://tenant-base-url/admin/v1/AuditEvents/2a02fb8bc9a548edb21fe1c80ff6ada0"
      },
      "actorId": "39e0f6b0654e45459f637fecb3cca25f",
      "adminResourceId": "a06ff8169b3640a29792a15ece75c906",
      "adminResourceName": "[e-mail]",
      "timestamp": "2018-01-04T12:57:46.312Z",
      "idcsLastModifiedBy": {
        "value": "39e0f6b0654e45459f637fecb3cca25f",
        "display": "admin opc",
        "type": "User",
        "$ref": "https://tenant-base-url/admin/v1/Users/39e0f6b0654e45459f637fecb3cca25f"
      },
      "quotaCount": 0,
      "ecId": "0000M31FtLAFo2H6yvR_6G1QJ7Wl0000K^",
      "rId": "0",
      "eventId": "admin.user.create.success",
      "ssoAuthnLevel": 0,
      "adminResourceType": "User",
      "actorType": "User",
      "serviceName": "Admin",
      "adminValuesAdded": "{\"schemas\":[\"urn:ietf:params:scim:schemas:core:2.0:User\"],\"name\":{\"familyName\":\"Saladna\",\"givenName\":\"Clarence\",\"formatted\":\"Clarence Saladna\"},\"userName\":\"[e-mail]\",\"emails\":[{\"value\":\"[e-mail]\",\"primary\":\"true\",\"type\":\"work\",\"verified\":\"false\"},{\"value\":\"[e-mail]\",\"primary\":\"false\",\"type\":\"recovery\",\"verified\":\"false\"}],\"id\":\"a06ff8169b3640a29792a15ece75c906\",\"displayName\":\"Clarence Saladna\",\"urn:ietf:params:scim:schemas:oracle:idcs:extension:user:User\":{\"status\":\"verified\"},\"active\":\"true\",\"password\":\"*********\",\"urn:ietf:params:scim:schemas:oracle:idcs:extension:passwordState:User\":{\"mustChange\":\"true\",\"lastSuccessfulSetDate\":\"2018-01-04T12:57:37.940Z\",\"cantChange\":\"false\",\"expired\":\"false\",\"passwordHistory\":[{\"sequenceNumber\":\"1\",\"value\":\"*********\"}]},\"urn:ietf:params:scim:schemas:oracle:idcs:extension:userState:User\":{\"locked\":{\"on\":\"false\"},\"loginAttempts\":\"0\"},\"meta\":{\"created\":\"2018-01-04T12:57:37.951Z\",\"lastModified\":\"2018-01-04T12:57:37.951Z\"},\"idcsCreatedBy\":{\"value\":\"39e0f6b0654e45459f637fecb3cca25f\",\"type\":\"User\",\"display\":\"admin opc\"},\"idcsLastModifiedBy\":{\"value\":\"39e0f6b0654e45459f637fecb3cca25f\",\"type\":\"User\",\"display\":\"admin opc\"}}",
      "schemas": [
        "urn:ietf:params:scim:schemas:oracle:idcs:AuditEvent"
      ]
    }
  ],
  "startIndex": 1,
  "itemsPerPage": 50
}

Diagnostic Report Sample