Formal
Connect Formal to Ploy to see every user in your Formal organization, people and machine users alike, and which Formal groups each one belongs to. Ploy can also create people in Formal, block and unblock users, delete users, and add or remove people from groups.
This integration is in beta
The Formal integration is in beta. It was built from Formal's documented API and has not yet been run against a live Formal organization, so some behaviour may differ from what is described here until it has.
The first step of setup is a consent checkbox. Ticking it lets Ploy send redacted error data to its own monitoring when a call to Formal fails. Redacted means secrets, tokens and personal details are removed before anything is stored. Ploy uses it only to fix problems with the integration. You need to tick it to continue.
What Ploy reads
Every user in your Formal organization. People show with their email address, name and database username. Machine users, such as service accounts and CI jobs, show as service accounts.
Temporary users whose expiry date has passed are shown as having lost their Formal access.
Every Formal group, and who belongs to it. Groups synced from your directory say so in their description.
Formal does not report which users are blocked, so a blocked user still shows as having access in Ploy.
Policies, resources, connectors, sessions and logs are not scanned yet.
What Ploy can change
Create a person in Formal from their email address, first name and last name. Formal does not send them a password, so they sign in through your single sign-on or directory sync.
Block a user, or unblock them. Blocking keeps the user and their groups in Formal.
Delete a user. Deleting someone who is already gone counts as done.
Add or remove a person from a group, from the group's page in Ploy. Adding someone who is already in the group, or removing someone who is not, counts as done.
Before you start
You need a Formal API key. In the Formal console, open API keys and create a key, then copy it. Formal API keys have no separate permissions: any key can read and change users and groups, so create it from an account you trust with that.
Connect Formal
In Ploy, open Integrations and choose Formal.
Tick the beta consent checkbox.
Paste your Formal API key.
Select Test to check the key. Ploy lists your Formal users with it to confirm it works.
Save the connection. The first scan starts straight away.
To connect another Formal organization, add another Formal connection with that organization's key.
Troubleshooting
Formal rejected that API key: check that the key was copied in full and has not been deleted.
Formal refused to list users: use a key created by an admin of your Formal organization.