# Auth0 Identity Analysis

Tools for analyzing Auth0 identity data by cross-referencing it with Neo4j graph database and MySQL vend_contact records.

## Overview

This project creates combined user reports by merging Auth0 user data with identity and tenant access information stored in Neo4j, organization membership data from Auth0, and `vend_contact` reconciliation data from MySQL. The goal is to identify user profiles, understand tenant access relationships, track organization memberships, surface vend_contact mismatches, and analyze activity patterns across the platform.

### How Combined Data is Created

1. **Export Users from Auth0** - User data is exported from Auth0 via the Management API, including standard fields (email, name, created_at) plus custom fields like `last_login` and `orchardIdentityId` from user metadata.

2. **Export Organization Memberships** - Auth0 organization membership data is fetched for all organizations, capturing which users belong to which organizations.

3. **Query Neo4j for Identity Data** - Each Auth0 user's identity ID is used to query Neo4j in batches. The graph database contains Identity nodes linked to Profile nodes, which in turn have access relationships to various tenant types (Vendor, Subaccount, LabelParticipant, Collaborator).

4. **Aggregate Relationships** - For each identity, the system collects all associated profiles and their tenant access relationships. Active and deleted access records are tracked separately to understand current vs historical access.

5. **Reconcile vend_contact** - For each Auth0 user, LabelProfile `profileId`s are pulled from Neo4j and joined against the MySQL `vend_contact` table to flag mismatches between Auth0's stored `vend_contact_id` and the actual vend_contact records.

6. **Combine All Data** - The final step merges Auth0 user info, organization memberships, Neo4j identity data, and vend_contact reconciliation into a comprehensive dataset with profile counts, active/deleted access counts, days since last login, organization memberships, vend_contact mismatch flags, and human-readable tenant access summaries.

## Setup

```bash
# Install package with dev dependencies
make install-dev
```

Create a `.env` file with credentials:
```
NEO4J_URL=neo4j+ssc://hostname:7687
NEO4J_USERNAME=username
NEO4J_PASSWORD=password

MYSQL_HOST=hostname
MYSQL_USERNAME=username
MYSQL_PASSWORD=password
MYSQL_DATABASE=database
MYSQL_PORT=3306  # optional, defaults to 3306
```

## Pipeline Summary

The export pipeline runs as a sequence of independent steps. Each step writes to `data/input/` (or `data/output/` for the final combined file), and later steps pick up the latest matching file from previous steps automatically (or interactively).

```
1. export_auth0_users         → data/input/job_<ID>.json
2. export_auth0_orgs          → data/input/orgs_<timestamp>.json
3. export_auth0_org_members   → data/input/org_members_<timestamp>.json
4. export_neo4j_identities    → data/input/neo4j_identities_<timestamp>.json
5. export_vend_contacts       → data/input/vend_contact_report_<timestamp>.json
6. combine_users              → data/output/combined_users_<timestamp>.json.gz
```

Steps 1–5 are independent and can be re-run individually. Step 6 merges everything.

## Usage

### Export Auth0 Users

First, install the Auth0 CLI: https://github.com/auth0/auth0-cli#installation

```bash
make export_auth0_users
```

This authenticates with Auth0 (browser-based if needed), creates an export job, and downloads the result to `data/input/job_<ID>.json`.

### Export Auth0 Organizations and Members

```bash
# Export organization list
make export_auth0_orgs

# Export organization members (interactive file picker)
make export_auth0_org_members

# Test mode: single org, limited users
make export_auth0_org_members_test
```

### Enrich with Neo4j Data

```bash
make export_neo4j_identities INPUT=data/input/job_<ID>.json
```

**Options:**
- `BATCH_SIZE=500` - Users per batch (default: 1000)
- `MAX_BATCHES=5` - Limit batches for test runs
- `OUTPUT=custom.csv` - Custom output path

### Reconcile vend_contact (Auth0 + Neo4j LabelProfiles + MySQL)

```bash
# Interactive file picker
make export_vend_contacts

# With explicit input
make export_vend_contacts INPUT=data/input/job_<ID>.json
```

For each Auth0 user, this pulls LabelProfile `profileId`s from Neo4j and looks up matching rows in MySQL `vend_contact`. A mismatch is flagged when Auth0's `vend_contact_id` is missing from the result set, or when the row marked `auth0_primary='Y'` has a different id. Output: `data/input/vend_contact_report_<timestamp>.json`.

**Options:**
- `BATCH_SIZE=500` - Users per batch (default: 1000)
- `MAX_BATCHES=5` - Limit batches for test runs
- `OUTPUT=custom.json` - Custom output path

### Combine All Data

```bash
# Auto-selects latest files from each source
make combine_users

# Interactive file selection
make combine_users INTERACTIVE=1
```

Results are saved to `data/output/combined_users_YYYYMMDD_HHMMSS.json.gz`.

## Development

```bash
make help        # View all commands
make format      # Format code with ruff
make lint        # Lint code
make type-check  # Type check with mypy
make check       # Run all checks
```