# Get FileVault Recovery Key

Retrieve FileVault recovery keys for macOS devices managed by JAMF Pro

Retrieves FileVault recovery keys for the requestor's macOS devices enrolled in JAMF Pro. The recovery key allows users to unlock their encrypted drives when they forget their password.

To watch one request from start to finish (a sign-in to verify, then the key by direct message) and how to set it up, see the video [Example: recover a FileVault key](https://www.tryrisotto.com/docs/guides/examples/filevault-key-video).

## Overview

This tool enables self-service retrieval of FileVault recovery keys through Risotto. Users can retrieve keys for their own devices when locked out. The tool:

- Automatically searches for devices assigned to the ticket requestor
- Verifies the device is macOS (FileVault only works on Mac)
- Retrieves the escrowed recovery key from JAMF Pro
- Logs all access for security audit trails
- **Security**: Users can only retrieve keys for devices assigned to them

## Prerequisites

Before using this tool, you need the same JAMF Pro API configuration as the [Get Device Information](https://www.tryrisotto.com/docs/integrations/tools/jamf/get_device_information) tool:

1. **JAMF Pro Server URL** (e.g. `https://yourcompany.jamfcloud.com`)
2. **API Client ID** and **Client Secret** (OAuth credentials)
3. An **API Role** with the privileges listed below

Additionally, the API Role must include the **View Disk Encryption Recovery Key** privilege to access FileVault keys.

## Setup

### Step 1: Update the API Role Privileges

If you already configured the [Get Device Information](https://www.tryrisotto.com/docs/integrations/tools/jamf/get_device_information) tool, update its API Role to add the FileVault privilege:

1. Log into your JAMF Pro server as an administrator
2. Navigate to **Settings** (gear icon) > **System** > **API Roles and Clients**
3. Click the **API Roles** tab and open the role used by Risotto (e.g. `Risotto Computer Inventory Reader`)
4. Ensure the following privileges are selected:
   - **Read Computers**
   - **View Disk Encryption Recovery Key**
5. Click **Save**

> **Warning:** The **View Disk Encryption Recovery Key** privilege is required to access
> FileVault recovery keys. Without it, the tool will return an authorization
> error from JAMF Pro.

> **Note:** After modifying which privileges are assigned to an API Role, you may need to
> generate a new client secret on the associated API Client for the changes to
> take effect.

### Step 2: Connect JAMF Pro in Risotto

Skip this step if JAMF Pro is already connected for your organization.

1. In the Risotto dashboard, navigate to **Settings > Integrations > Jamf**
2. On the **JAMF Pro** card, click **Connect**
3. Enter your JAMF Pro credentials:
   - **Server URL**: Your JAMF Pro server URL (without trailing slash), for example `https://yourcompany.jamfcloud.com`
   - **Client ID**: Your JAMF Pro API Client ID
   - **Client Secret**: Your JAMF Pro API Client Secret
4. Click **Save**

### Step 3: Enable the Tool in Risotto

1. Select **Tools** in the sidebar
2. In the **Tool groups** list, select **Jamf**
3. Find **JAMF Pro Get FileVault Recovery Key** and click **Enable**
4. Optionally, open the tool and click **Edit** to change its settings:
   - **Requires Approval**: Require human approval before the tool runs (recommended)
   - **Restrict to Requestor Only**: Only operate on devices assigned to the ticket requestor. On by default.
   - **Send via DM Only**: Send the key to the requestor in a Slack DM, not in the ticket thread. If Risotto cannot send the DM, it does not post the key in the thread. The tool fails, and the agent escalates the ticket.
5. Click **Save**

> **Tip:** Enabling approval workflows ensures that FileVault key access is reviewed by a
> human before being shared, adding an extra layer of security.

## How It Works

### Automatic Requestor Identification

The tool automatically identifies the requestor from the ticket context and searches for devices assigned to that user in JAMF Pro (matching on the user's email). This ensures users can only retrieve keys for their own devices.

### Multiple Devices

If you have multiple Macs enrolled in JAMF Pro:

- **Without serial number**: Tool lists all your devices with their serial numbers and asks you to specify which one
- **With serial number**: Tool retrieves the key for your specific device matching that serial

## Configuration Options

| Parameter       | Type | Required | Description                                                     |
| --------------- | ---- | -------- | --------------------------------------------------------------- |
| `serial_number` | TEXT | No       | Device serial number (only needed if you have multiple devices) |

The tool automatically uses the requestor's email from the ticket context to find their devices.

## Response Format

### Successful Retrieval

```
**FileVault Recovery Key for MacBook-Pro-2023**

**Device:** MacBook-Pro-2023
**Serial:** C02XY1ZHJG5H
**User:** john.smith@company.com

🔑 **Recovery Key:**
`XXXX-XXXX-XXXX-XXXX-XXXX-XXXX`

⚠️ **Important:** This key allows full disk decryption. Handle with care and do not share unnecessarily.
```

### Multiple Devices Found

```
You have 2 devices enrolled:
C02XY1ZHJG5H, C02AB2CDJG5K

Please specify serial_number to get the FileVault key for a specific device.
```

### No Key Available

```
No FileVault recovery key found for MacBook-Pro-2023.

Possible reasons:
- Device is not encrypted with FileVault
- Recovery key was not escrowed to JAMF Pro
- Device needs to regenerate its recovery key
```

## Usage Examples

### Example 1: Single device - automatic retrieval

**User Request:**

> "I'm locked out of my MacBook and can't remember my password"

**What Happens:**

1. Tool automatically finds device assigned to requestor
2. Verifies device is macOS
3. Retrieves FileVault recovery key from JAMF Pro
4. Returns key with device details and security warning

### Example 2: Multiple devices - disambiguation needed

**User Request:**

> "I need my FileVault key"

**First Response:**

```
You have 2 devices enrolled:
C02XY1ZHJG5H, C02AB2CDJG5K

Please specify serial_number to get the FileVault key for a specific device.
```

**User Clarifies:**

> "I need the key for C02XY1ZHJG5H"

**What Happens:**

1. Tool searches requestor's devices
2. Uses serial number to identify the correct device
3. Returns key for that specific device

## Security Considerations

### Access Control

- **Self-Service Only**: Users can only retrieve keys for devices assigned to them in JAMF Pro
- **Approval Workflows**: Enable human approval for additional security layer (recommended)
- **Audit Logging**: All key access is logged with device and requester details
- **Ticket Context**: Tool only works within support ticket context

### Best Practices

1. **Enable Approval**: Configure the tool to require human approval for additional security
2. **Monitor Usage**: Review logs regularly to track key retrieval
3. **Secure Handling**: Keys allow full disk decryption - handle with care
4. **Password Reset**: Users should reset their password after using the recovery key

### API Credential Security

- Store API credentials securely (Risotto encrypts them at rest)
- Use a dedicated API Client for Risotto rather than sharing one across integrations
- Grant only the privileges required (least privilege)
- Rotate the client secret periodically (every 90 days recommended)

## Troubleshooting

### No devices found assigned to your email

**Causes:**

- Device is not assigned to you in JAMF Pro
- Device is not enrolled in JAMF Pro
- Email mismatch between the ticket and JAMF Pro user record

**Solution:**

1. Verify your device is enrolled in JAMF Pro
2. Ensure the device's assigned user email matches your ticketing email
3. Contact IT to verify device assignment

### No FileVault recovery key found

**Causes:**

- Device is not encrypted with FileVault
- Recovery key was not escrowed to JAMF Pro
- API Role lacks the **View Disk Encryption Recovery Key** privilege

**Solution:**

1. Verify FileVault is enabled on your device
2. Confirm a Disk Encryption configuration profile is scoped to the device with **Escrow Personal Recovery Key** enabled
3. Contact IT to verify the API Role has the required privilege

### Cannot retrieve FileVault key for this device

**Cause:** Device platform is not macOS

**Solution:**

- FileVault is only available on Mac devices
- For Windows devices, contact IT for BitLocker recovery

### Authentication failed

**Cause:** Invalid or expired API credentials, or the API Client is disabled

**Solution:**

- Verify the Client ID and Secret in Risotto match what's shown in JAMF Pro
- Check that the API Client is enabled in **Settings** > **System** > **API Roles and Clients**
- If the client secret was rotated in JAMF Pro, update the credentials in Risotto

## API Details

### Required Privileges

- **Read Computers** — Search and retrieve device information
- **View Disk Encryption Recovery Key** — Access FileVault recovery keys

Source: https://www.tryrisotto.com/docs/integrations/tools/jamf/get_filevault_key
