JumpCloud Account Recovery
Draft
JumpCloud Account Recovery
Draft
Press a step to see its codeFind the JumpCloud user, lines 87 to 105Unlock the account, lines 107 to 128Reset MFA, lines 119 to 127Note it on the ticket, lines 130 to 141

Find the JumpCloud user

Suspended and not-yet-activated accounts go to a person instead.

search.status_code !== 200

Fail

JumpCloud returned ${search.status_code} — check the API key.

user === undefined

Fail

No JumpCloud user has the email ${email} — ask which they use.

user.suspended

Fail

${email} is suspended in JumpCloud — hand this to an admin.

!user.activated

Fail

${email} hasn't activated JumpCloud yet — hand this to an admin.

Unlock the account

Nothing happens here when the account isn't locked.

user.account_locked

unlock.status_code !== 200

Fail

Unlock failed (${unlock.status_code}) — use the Admin Portal.

params.problem === "lost_mfa_device"

Reset MFA

They enroll a new authenticator at their next User Portal sign-in.

reset.status_code !== 200

Fail

MFA reset failed (${reset.status_code}) — use the Admin Portal.

Note it on the ticket

ticket !== null

Return

return

true
false
true
false
true
false
true
false
true
true
false
false
true
true
false
false
true
false
1// Get someone back into JumpCloud: unlock a locked account, clear the way
2// for a password reset, or reset MFA after a lost phone. Then note what
3// happened on the ticket.
4//
5// Before publishing: set the JUMPCLOUD_API_KEY config value to an API key
6// from a JumpCloud admin who can manage users. A multi-tenant (MSP) key also
7// needs an x-org-id header naming the org: add it to the requests below as a
8// plain header. It isn't a config value because every config value must be
9// set, and single-org keys don't send one.
10//
11// JumpCloud's API has no call that sends a password reset email, so
12// forgot_password unlocks the account if it's locked and points the person
13// to Reset User Password on the User Portal login page, which emails a link.
14
15export const input = z.object({
16 user_email: z
17 .string()
18 .email()
19 .describe("The email the person signs in to JumpCloud with"),
20 problem: z
21 .enum(["locked_out", "forgot_password", "lost_mfa_device"])
22 .describe("What went wrong: locked out, forgot password, or lost phone"),
23});
24
25// Unlock and MFA reset are POSTs, so the host needs "read_write".
26export const domains = { "console.jumpcloud.com": "read_write" };
27
28const USERS_API = "https://console.jumpcloud.com/api/systemusers";
29
30// Days the person has to set up a new authenticator after an MFA reset.
31const ENROLLMENT_DAYS = 3;
32
33type JumpCloudUser = {
34 _id: string;
35 account_locked: boolean;
36 activated: boolean;
37 suspended: boolean;
38 password_expired: boolean;
39};
40
41function jumpcloudAuth(): HttpAuth {
42 return {
43 type: "api_key_header",
44 header: "x-api-key",
45 value: env.JUMPCLOUD_API_KEY,
46 };
47}
48
49function outcome(
50 email: string,
51 problem: "locked_out" | "forgot_password" | "lost_mfa_device",
52 user: JumpCloudUser,
53 enrollBy: string,
54): string {
55 const unlocked = user.account_locked
56 ? `Unlocked ${email}'s JumpCloud account. `
57 : "";
58 if (problem === "lost_mfa_device") {
59 return (
60 `${unlocked}Reset MFA for ${email}: they set up a new authenticator ` +
61 `at their next User Portal sign-in, and must finish by ${enrollBy}.`
62 );
63 }
64 if (problem === "forgot_password") {
65 return (
66 `${unlocked}Ask ${email} to click Reset User Password on the User ` +
67 `Portal login page; JumpCloud emails them a reset link. (JumpCloud's ` +
68 `API can't send that email for them.)`
69 );
70 }
71 if (!user.account_locked) {
72 return (
73 `${email}'s JumpCloud account isn't locked, so nothing changed. Ask ` +
74 `whether they forgot their password or lost their MFA device.`
75 );
76 }
77 const expired = user.password_expired
78 ? " Their password has also expired, which unlocking doesn't fix: they " +
79 "can set a new one with Reset User Password on the User Portal."
80 : " They can sign in with their current password.";
81 return `${unlocked.trim()}${expired}`;
82}
83
84export default async function run(params: z.infer<typeof input>) {
85 const email = params.user_email;
86
87 // **Find the JumpCloud user**
88 // Suspended and not-yet-activated accounts go to a person instead.
89 const search = await http.get(USERS_API, {
90 query: { filter: `email:$eq:${email}` },
91 auth: jumpcloudAuth(),
92 });
93 if (search.status_code !== 200) {
94 fail(`JumpCloud returned ${search.status_code} — check the API key.`);
95 }
96 const user: JumpCloudUser | undefined = search.body.results[0];
97 if (user === undefined) {
98 fail(`No JumpCloud user has the email ${email} — ask which they use.`);
99 }
100 if (user.suspended) {
101 fail(`${email} is suspended in JumpCloud — hand this to an admin.`);
102 }
103 if (!user.activated) {
104 fail(`${email} hasn't activated JumpCloud yet — hand this to an admin.`);
105 }
106
107 // **Unlock the account**
108 // Nothing happens here when the account isn't locked.
109 if (user.account_locked) {
110 const unlock = await http.post(`${USERS_API}/${user._id}/unlock`, {
111 auth: jumpcloudAuth(),
112 });
113 if (unlock.status_code !== 200) {
114 fail(`Unlock failed (${unlock.status_code}) — use the Admin Portal.`);
115 }
116 }
117 const deadline = new Date(Date.now() + ENROLLMENT_DAYS * 86_400_000);
118 if (params.problem === "lost_mfa_device") {
119 // **Reset MFA**
120 // They enroll a new authenticator at their next User Portal sign-in.
121 const reset = await http.post(`${USERS_API}/${user._id}/resetmfa`, {
122 json: { exclusion: true, exclusionUntil: deadline.toISOString() },
123 auth: jumpcloudAuth(),
124 });
125 if (reset.status_code !== 200) {
126 fail(`MFA reset failed (${reset.status_code}) — use the Admin Portal.`);
127 }
128 }
129
130 // **Note it on the ticket**
131 const summary = outcome(
132 email,
133 params.problem,
134 user,
135 deadline.toISOString().slice(0, 10),
136 );
137 const ticket = await risotto.get_ticket();
138 if (ticket !== null) {
139 await risotto.add_ticket_comment({ comment: summary });
140 }
141 return summary;
142}
87 // **Find the JumpCloud user**
88 // Suspended and not-yet-activated accounts go to a person instead.
89 const search = await http.get(USERS_API, {
90 query: { filter: `email:$eq:${email}` },
91 auth: jumpcloudAuth(),
92 });
93 if (search.status_code !== 200) {
94 fail(`JumpCloud returned ${search.status_code} — check the API key.`);
95 }
96 const user: JumpCloudUser | undefined = search.body.results[0];
97 if (user === undefined) {
98 fail(`No JumpCloud user has the email ${email} — ask which they use.`);
99 }
100 if (user.suspended) {
101 fail(`${email} is suspended in JumpCloud — hand this to an admin.`);
102 }
103 if (!user.activated) {
104 fail(`${email} hasn't activated JumpCloud yet — hand this to an admin.`);
105 }
107 // **Unlock the account**
108 // Nothing happens here when the account isn't locked.
109 if (user.account_locked) {
110 const unlock = await http.post(`${USERS_API}/${user._id}/unlock`, {
111 auth: jumpcloudAuth(),
112 });
113 if (unlock.status_code !== 200) {
114 fail(`Unlock failed (${unlock.status_code}) — use the Admin Portal.`);
115 }
116 }
117 const deadline = new Date(Date.now() + ENROLLMENT_DAYS * 86_400_000);
118 if (params.problem === "lost_mfa_device") {
119 // **Reset MFA**
120 // They enroll a new authenticator at their next User Portal sign-in.
121 const reset = await http.post(`${USERS_API}/${user._id}/resetmfa`, {
122 json: { exclusion: true, exclusionUntil: deadline.toISOString() },
123 auth: jumpcloudAuth(),
124 });
125 if (reset.status_code !== 200) {
126 fail(`MFA reset failed (${reset.status_code}) — use the Admin Portal.`);
127 }
128 }
119 // **Reset MFA**
120 // They enroll a new authenticator at their next User Portal sign-in.
121 const reset = await http.post(`${USERS_API}/${user._id}/resetmfa`, {
122 json: { exclusion: true, exclusionUntil: deadline.toISOString() },
123 auth: jumpcloudAuth(),
124 });
125 if (reset.status_code !== 200) {
126 fail(`MFA reset failed (${reset.status_code}) — use the Admin Portal.`);
127 }
130 // **Note it on the ticket**
131 const summary = outcome(
132 email,
133 params.problem,
134 user,
135 deadline.toISOString().slice(0, 10),
136 );
137 const ticket = await risotto.get_ticket();
138 if (ticket !== null) {
139 await risotto.add_ticket_comment({ comment: summary });
140 }
141 return summary;
Config you will fill in
These become encrypted config fields on the new tool:JUMPCLOUD_API_KEY