Client credentials applications

Client credentials applications are externally hosted OAuth or OSDK applications that use client credentials for authentication. These applications are ideal for pro-code solutions that require maximum user scale and allow customer-defined authentication and authorization logic outside of Foundry.

Client credentials applications are ideal for the following use cases:

• Server-to-server integrations that do not require interactive user login.
• Automated systems that need to access Foundry data programmatically.
• Backend services that process data or trigger workflows.
• API integrations with external platforms.
• Public-facing applications that need to serve many users without individual authentication.

Architecture

Client credentials applications authenticate using a client ID and client secret. They then receive an access token tied to a service user and use that token to make API calls to Foundry through the service user's permissions.

External application → OAuth Client Credentials → Service user → Foundry APIs

Prerequisites

Before setting up a client credentials application, ensure that you have the following:

• Third-party application management permissions on your organization in Control Panel.
• An external hosting environment for your application.

Setup

Step 1: Create an OAuth client application

OAuth clients are now created in Developer Console. Refer to the comprehensive OAuth client guide for more information.

1. Navigate to Developer Console > OAuth clients.
2. Select Create OAuth client.
3. Choose the Backend service application type.
4. Configure the application settings and note the generated credentials.

Step 2: Understand service user implications

For client credentials applications, Foundry creates a service user that acts on behalf of your application. This offers the following benefits:

• No user login required: Since your application displays information that is not scoped to individual users, the service user handles all operations.
• Service user permissions: By default, the service account does not have access to any resources. A Foundry administrator must assign the desired roles and permissions to the service user account for the client to perform actions in Foundry.
• Authorization responsibility: You must implement authorization logic in your application since users cannot log in individually. Your application receives a single token for all operations.
• Permission management: Grant the service user access to specific projects, object types, and datasets required by your application.

Step 3: Configure service user permissions

After creating the OAuth client, configure the following permissions for the service user:

• Project access: Grant the service user access to projects containing required resources.
• Ontology type access: Grant access to the necessary ontology types. Ensure that the service user can submit actions.
• Dataset access: Grant access to required datasets.
• Role assignments: Assign appropriate roles that provide necessary API operations.

Step 4: OSDK application implementation

For TypeScript applications, use the OSDK to generate a custom SDK library for your application. Refer to the bootstrapping server-side TypeScript applications guide for more information.

The OSDK bootstrapping process consists of the following steps:

1. Create an OSDK package: Use Developer Console to generate an OSDK package.
2. Add Ontology resources to the SDK: Add the entities that your application needs to access to the OSDK resources.
3. Install the OSDK: Install the generated OSDK package in your application.
4. Configure authentication: Use the OSDK authentication client with your OAuth client credentials to access Foundry.
5. Query data: Query ontology data with the service user's permissions using the OSDK client.

The OSDK client provides type safety, automatic serialization, and simplified API interactions compared to raw REST API calls.

Step 5: Verify application access

1. Verify authentication: Ensure that your application can successfully obtain access tokens.
2. Test API calls: Confirm that your application can access the required Foundry resources.

Troubleshooting

Authentication issues

• Invalid client credentials: Verify that the client ID and secret are correct. Regenerate if necessary to confirm the secret is correct.
• Scope errors: Ensure requested scopes are granted to the OSDK client application.
• Network connectivity: Check firewall and network policies to ensure your requests are making it to Foundry.

Permission errors

• 403 Forbidden: Review application permissions in Developer Console. A 403 error means a user does not have permission to see the application.
• Resource not found: If the user does not have access to resources that you expect them to see, verify that the application service user has access to those resources and they have been added to the application's ontology resources.

You now have a working client credentials application with the power of the Ontology at your fingertips. Your external application can securely access Foundry data and functionality through the service user's permissions, enabling you to build scalable consumer-facing applications with robust backend integration.