How to Perform Searches with innerHit criteria via API

7 Kudos

Search in the IdentityNow user interface offers robust visibility into a tenant's data, but sometimes it is necessary to perform a search via the POST v3/search API endpoint to get the search results returned exactly as desired.

For example, the @access array nested within the top level identity searchable object contains all the access that a identity holds, including entitlements, access profiles, and roles. If we want to search for all the entitlements that an identity has on a particular source, we can certainly do that in the IdentityNow search UI with a search query like this:

attributes.uid:douglas.flores AND @access(type:ENTITLEMENT AND source.name:Finance)

But to see the actual entitlements that the douglas.flores identity holds on the Finance source, we have to click on the identity object that is returned in the results and then scroll through all of that identity's entitlements in the pop up box to find the entitlements on that particular source:

innerHit search.png

We have the option to download a report in csv format from the search UI, including the access details, but we will still have to filter through the all the returned data for the exact data that we are looking for:

innerHit search 5.png

innerHit search 6.png

Performing the exact same search via the POST v3/search API in Postman, returns the same data in the raw JSON. We can see that the JSON definition of the entire identity object is returned for the douglas.flores identity. Once again, we must scroll through the results, this time in JSON, to see the entitlements that the douglas.flores identity has on the Finance source.

innerHit search 2.png

innerHit search 3.png

Instead, we can do the same search via the POST v3/search API using innerHit criteria that will return only the entitlements we are searching for in the JSON response body, not the entire JSON definition of the douglas.flores identity.

We modify the JSON request body by moving the entitlement criteria to the query attribute in the innerHit nested object and specifying "access" for the value of the type attribute because this is the criteria we are using to search through the nested @access array:

{
    "indices": [
        "identities"
    ],
    "query": {
        "query": "attributes.uid:douglas.flores",
        "innerHit": {
            "type": "access",
            "query": "type:ENTITLEMENT AND source.name:Finance"
        }
    }
}

Now, we see that only the entitlements that the douglas.flores identity has on the Finance source are returned in the JSON response body:

innerHit search 4.png

Gael-Nite · ‎Sep 16, 2022

Nice, this is very useful. Thanks

wi_fil · ‎Nov 29, 2023

Thank you, @christina_gagnon !

Hi, Is it possible to use queryResultFilter to limit the amount of lines in the response? I would like to retrieve only the IDs of the ROLES that a certain user has.

I tried, but it did not work:

{

"indices": [

"identities"

],

"query": {

"query": "id:123456789",

"innerHit": {

"type": "access",

"query": "type:ROLE"

},

"queryResultFilter": {

"includes": [

"access.id",

"access.type"

]

}

christina_gagnon · ‎Nov 29, 2023

@wi_fil

My understanding is that it is not possible to use queryResultFilter to limit the fields in the response.

perezr7 · ‎Sep 23, 2024

Thank you @christina_gagnon! Is there any way to increase the number of records in the result, or use paging in an innerHit query? I have cases where a user could have 500~ of entitlements in the same source, but this innetHit search query only shows 100.

Thanks!