How can I call Foundry APIs from Foundry itself?

[ckucera]

For example, if I want to leverage ontology APIs, grab build history, or update users programmatically?

[ckucera]

Background / Problem:

• You need to run some automated logic that hits Foundry Services.

• Right now you are storing your personal token as a secret on a REST API source OR you’ve written an external transform and are storing your personal token as a secret of that external transform.

---

As an example, you want a Webhook that can Preregister a user to Multipass. And you want this to be executed automatically (via Automate). Note that for your example the set of scopes and permissions may be different! Edit them accordingly.

Step 0: You determine that a Confidential Client 3PA is in fact the way to go.

• You realize that you want this to be run by an automation, and not by a privileged user’s action. Therefore, other alternatives such as setting up a 3PA Authorization Code Flow which checks the user’s own permissions to complete the preregistration task, or simply using the multipass UI directly to perform the task, are out.

• Now, you want to avoid creating a Service Account and generating a long-lived token, and you also want to avoid generating a long-lived token from a privileged human user. These would be suboptimal setups from a security and maintainability perspective.

• Therefore you conclude that an OAuth Confidential Client flow is the right solution.

Step 1: [Research/Prework] Understand the permissions required to Preregister a User in Multipass and how to obtain them.

1. You investigate and you learn that preregistering a user to multipass requires elevated privileges. Specifically, it requires that your 3PA’s service user must have the multipass:preregister-user gatekeeper operation, on the Organization into which it will preregister users.

2. You learn that one way this operation is typically granted is through the Manage Users and Groups workflow granted to users assigned as Users and groups administrators in Control Panel → Organization Permissions.

Step 2: Create a 3rd Party Application in Developer Console

• 

• 

• 

• Make sure to select “No, I won’t use an Ontology SDK”. This will create a non-OSDK 3PA. If you don’t, it will be an OSDK 3PA and will not support custom scopes such as multipass:preregister-user.

• You will be provided with a CLIENT SECRET and a CLIENT ID. We’ll need these soon.

Step 3: Create a REST API Magritte Source

• The domain for the rest api should be your Foundry enrollment’s frontdoor. e.g. https://stack.palantirfoundry.com

• Probably, choose Direct Connection.

• Probably, add an Egress Policy to it, that refers back to the front door of your stack, over port 443 (e.g. https://stack.palantirfoundry.com)

• Choose Authentication: None

• Add a Secret to it containing your CLIENT SECRET from Step 2.

• Add a Secret to it containing your CLIENT ID from Step 2.

Step 4: Create a webhook from that REST API Source

Configure the webhook to perform the Client Credentials Handshake.

1. Follow the instructions here: https://www.palantir.com/docs/foundry/data-connection/webhooks-reference/#build-a-webhook-that-performs-the-client-credentials-handshake

2. The first call manually request an OAuth token. You will need to edit it to specify the scopes you are requesting for your token, via the OAuth Scope string (Screenshot below left)

   1. In this case, that would be multipass:preregister-user

3. The second call will have to be customized depending on which foundry endpoint you are trying to hit. In this case, the preregister users endpoint. You’ll also add an email Input Parameter to the webhook, and pass it to the API call, because that endpoint expects the user to provide an email address. (Screenshot below right)

Step 3. Rest API Source Setup

Step 4. Webhook configuration

Step 4. Webhook configuration

Step 5: Test your webhook and it fails with a Permission Error

• You test your webhook https://www.palantir.com/docs/foundry/data-connection/webhooks-setup/#test-the-webhook but the webhook fails with a permission error.

• This makes sense for two reasons:

  • Your 3PA Client’s Service User is not a Users and Groups Administrator. It’s not allowed to preregister users.

  • And, when you set up the 3PA itself in Control Panel, you didn’t specify any Scope Restrictions. Therefore, by default, the scopes were restricted down to an empty list of scopes. Your 3PA Clients’ tokens have a scope that starts off as whatever permissions the Service User has, and then is filtered down to the list of scopes specified.

Step 6: Fix the Permissions and the Scope

• You assign your Service User as a Users and Groups Administrator in Control Panel (if you are allowed to do so)

• You go to your 3PA’s Configuration in Dev Console and try to edit the scope

Step 7: Test your webhook again and it succeeds

• You test your webhook again, and celebrate!

Step 8: Create the Action & the Automation

• You’re off to the races. You create an Action backed by your Webhook and you define an Automation in Automate to run your Action automatically in response to your desired triggers.