Application Identities (App IDs)
A Catalyst Application Identity, referred to as App ID, is a projection or "digital twin" that represents an externally-hosted application workload. An App ID is required for each microservice or application that will interact with the Catalyst APIs. Each App ID is used to establish API connectivity, set access control policies, enable resiliency and more.
Overview
In order to use the Catalyst APIs from your application code or the Catalyst client interfaces, creating an App ID is the first step. Each App ID is created with a unique API token which is used by the calling application to authenticate inbound API requests to Catalyst. You can create an App ID and generate an API Token using the diagrid appid create command. It is recommended to name your App ID after the application workload it corresponds to externally.
While the API token can be used to authenticate incoming calls to the Catalyst APIs, you may have some applications which need to receive outbound calls from the Catalyst APIs. In order to handle this scenario, you can configure your App ID to route requests to an external endpoint. This is described in the Establish Outbound Connectivity section of this document.
Outside of establishing secure connectivity between your application and the Catalyst service, App IDs are also used to:
- Scope access to underlying infrastructure resources via Connections
- Enforce access control policies to restrict which applications can invoke a given App ID via the Request/Reply API
- Set resiliency policies which are used when performing invocations via the Request/Reply API
Getting Started
The quickest way to call the Catalyst APIs is to invoke them directly once you have an App ID available and retrieve the generated API token. You can use the API explorer in the Catalyst console or the diagrid call commands provided in the Diagrid CLI for an easy testing experience.
The Diagrid CLI also provides the diagrid listen command which forwards outbound calls from an App ID to the CLI on your local machine to test the receipt of outbound API requests, without the need to deploy any application code.
To learn more about getting started without application code, visit Test Catalyst APIs without application code or complete any of the available quickstarts.
Connect Applications to Diagrid Catalyst
This section describes how to establish inbound and/or outbound connectivity between your application and Diagrid Catalyst.
Establish Inbound Connectivity
As mentioned above, each App ID has its own API Token which must be used when making inbound requests to the Catalyst APIs. For security purposes, the API token can be regenerated at any time, immediately invalidating the previous API token. Inbound connectivity to the Catalyst APIs is required to perform the following API actions:
- Workflow API: Trigger Workflow operations (start, stop, etc.)
- Request/Reply API: Initiate a direct service-to-service call
- Pub/Sub API: Publish a message
- State API: Manage application state
- Bindings API: Invoke an output binding
If your application is only performing inbound API calls, configuring an application connection is not necessary. If your application also needs to receive outbound calls from Catalyst, use the instructions in the establishing outbound connectivity section.
For instructions on how to configure your code to connect to Catalyst and perform secure API calls, see Connect Dapr SDKs to Catalyst.
Establish Outbound Connectivity
In some cases, a given application may need to receive outbound requests from Catalyst. Connectivity from Catalyst to your application code is required to enable the following scenarios:
- Request/Reply API: Respond to a direct service-to-service call
- Pub/Sub API: Subscribe to messages
- Bindings API: Trigger your app via input binding
To establish a connection from the Catalyst platform to your external application, you can configure an Application Connection. An App Connection is made up of the following:
| Setting | Description |
|---|---|
| App Endpoint | The public endpoint your external app is listening on to receive messages or invocations. |
| App Protocol | The protocol used by Catalyst to communicate with your external app (HTTP or gRPC). Default: HTTP |
| App Token | A generated token used for securing communication from Catalyst to your external application. For security purposes, the app token can be regenerated at any time, immediately invalidating the previous application token. Bring-your-own token is also supported. |
When the above settings are supplied, your App Connection will provide a status indicator as to if your external endpoint is "available" or "unavailable". Today, availability merely indicates if the endpoint provided responded to a layer 3 request.
Today, your application must be publicly accessible for successful connection establishment from Catalyst. This is a temporary limitation, with virtual network integration planned for a future release.
Configure Resiliency
When creating or updating an App ID, you have the option to enable a set of default resiliency policies. These resiliency policies apply specifically to Request/Response API calls made from your application targeting another application. In the event of call failures and transient errors, the configured policies would be enforced, without the need for you to write any resiliency code in your application itself.
There are three default resiliency policies available, and you can choose which you want to enable.
Timeout: Early-terminate long-running operations that exceed 10s.
Retry: Retry failed operations
Setting Description policy Constant back-off and retry interval duration 5s between retries maxRetries 5 retries maximum Circuit Breaker: Shut off traffic to the impacted application when certain criteria is met to avoid flooding
Setting Description trip After 5 consecutive failures, the CB will trip and become open timeout 20s after the CB is tripped, it will switch to half-open interval 5s, meaning the CB clears its internal counts after 5s maxRequests 1 request will be allowed to pass through when the CB is half-open and recovering from failure