Token Introspect: Link External Identity Tokens to Graph Nodes

Token Introspect bridges external identity providers (IdP) with the IndyKite Knowledge Graph:

What it does:

1. Validates JWT tokens from external providers (Auth0, Okta, etc.)

2. Extracts claims (sub, email, custom claims) from the token

3. Creates/updates a Token node in the IKG with extracted claims

4. Links the Token node to an existing Person node via _SAME_AS relationship

Result: External authentication becomes usable for graph-based authorization decisions.

Use case

Scenario: Your application uses Auth0 for user authentication but needs IndyKite for authorization.

Flow:

1. User authenticates with Auth0, receives JWT access token

2. Application calls IndyKite API with the Auth0 token

3. Token Introspect validates the token and extracts claims

4. A Token node is created in the IKG with properties from token claims

5. Token node is linked to Person(Alice) via _SAME_AS relationship

Graph result:

Person(Alice) -[_SAME_AS]-> Token(auth0|12345)

↳ sub: "auth0|12345"

↳ email: "alice@example.com"

↳ auth_level: "mfa"

Now KBAC policies can use token claims (like auth_level) in authorization decisions.

Requirements

Prerequisites:

- ServiceAccount credentials: For creating Token Introspect configuration

- AppAgent credentials: For data ingestion and triggering introspection (X-IK-ClientKey)

- External IdP token: A valid JWT from Auth0, Okta, or another supported provider

Required API access:

- POST /capture/v1/nodes/ (capture Person node)

- POST /configs/v1/token-introspects (create configuration via Terraform or Hub)

- POST /access/v1/WhatAuthorized (triggers introspection)

Steps

Step 1: Ingest Person Node

- Authentication: AppAgent credential (X-IK-ClientKey header)

- Action: POST Person node that will be linked to the external identity

- Result: Person node exists in IKG

Step 2: Obtain External IdP Token

- Action: User authenticates with Auth0 (or other IdP)

- Result: JWT access token with claims (sub, email, custom claims)

- Note: This step happens in your application, not via IndyKite API

Step 3: Create Token Introspect Configuration

- Method: Terraform or IndyKite Hub

- Configuration includes:

- issuer: The IdP's issuer URL (e.g., "https://your-tenant.auth0.com/")

- client_id: The OAuth client ID

- sub_claim: Which claim to use as external_id (default: "sub")

- perform_upsert: true (to create/update Token node automatically)

- Result: Token Introspect configuration active

Step 4: Trigger Token Introspection

- Authentication: AppAgent credential (X-IK-ClientKey) + User's IdP token (Bearer)

- Action: POST to WhatAuthorized endpoint (or any KBAC endpoint)

- The system validates the token, extracts claims, and creates/updates Token node

- Token node is linked to matching Person via _SAME_AS relationship

- Result: Token claims now available for authorization decisions

Step 5: Use in Authorization

- Now KBAC policies can reference token claims (e.g., auth_level, email)

- Entity Matching can be used if automatic linking needs refinement

{
  "nodes": [
    {
      "external_id": "alice",
      "is_identity": true,
      "type": "Person",
      "properties": [
        {
          "type": "email",
          "value": "alice@email.com"
        },
        {
          "type": "given_name",
          "value": "Alice"
        },
        {
          "type": "last_name",
          "value": "Smith"
        }
      ]
    }
  ]
}

{
  "profiles": [],
  "email": "alice@email.com",
  "iss": "issuer_url",
  "sub": "sub_value",
  "aud": [
    "client_id",
    "https://issuer/userinfo"
  ],
  "iat": 1749319876,
  "exp": 1749406276,
  "scope": "openid profile email",
  "azp": "client_id"
}

terraform {
  required_providers {
    indykite = {
      source  = "indykite/indykite"
      version = 1.26. // or latest version
    }
  }
}

# indykite provider integrates IndyKite platform with Terraform scripting.
# Provider for now does not support any parameters and all is set within service account credential file.
provider "indykite" {}


resource "indykite_token_introspect" "token_config" {
  name         = "terraform-token-introspect"
  display_name = "Terraform token introspect"
  description  = "Token introspect for DigitalTwin access token"
  location     = "ProjectGID"
  jwt_matcher {
    issuer   = "https://example.com"
    audience = "client-id"
  }
  offline_validation {}
   ikg_node_type = "Token"
   claims_mapping = {
        "email" = "email"
    }
   perform_upsert = true
}

{
  "subject": {
    "access_token": "{{accessToken}}"
  },
  "resourceTypes": [
    {
      "type": "Person",
      "actions": [
        "EXISTS"
      ]
    }
  ]
}

{
  "decisionTime": "2025-06-07T18:46:25.236068434Z",
  "decisions": {
    "Person": {
      "actions": {
        "EXISTS": {
          "resources": []
        }
      }
    }
  }
}