Application Identities (App IDs)
A Catalyst Application Identity, referred to as an 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 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 Catalyst, you may have some applications which need to receive outbound requests from Catalyst. 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 App 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 Components
- Enforce access control policies to restrict which applications can invoke a given App ID via the Service Invocation API
- Set resiliency policies which are used when performing invocations via the Service Invocation 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 requests from an App ID to the CLI on your local machine to for testing purposes.
To learn more about getting started without application code, visit Test Catalyst APIs without application code.
Connect to Catalyst
This section describes how to establish connectivity between your application and Diagrid Catalyst.
Send Catalyst API Requests
As mentioned above, each App ID an associated API Token which must be used when making requests to the Catalyst APIs. For security purposes, the API token can be regenerated at any time, immediately invalidating the previous API token. An API token is required to perform the following API actions:
- Workflow API: Trigger Workflow operations (start, stop, etc.)
- Service Invocation 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
For instructions on how to configure your code to connect to Catalyst and perform secure API requests, see Connect Dapr SDKs to Catalyst.
If your application is only performing API requests, configuring an App Conenction is not necessary. If your application also needs to receive requests from Catalyst, use the instructions in the following section.
Establish App Connection
In some cases, an application may need to receive outbound requests from Catalyst. Connectivity from Catalyst to your application code is required to enable the following scenarios:
- Service Invocation API: Receive a direct service-to-service call
- Pub/Sub API: Subscribe to messages
- Bindings API: Trigger your app via input binding
Adding an Application Connection allows your App ID to act as a proxy, ensuring all requests destined for the App ID are sent to the proper application endpoint. An App Connection is made up of the following:
| Setting | Description |
|---|---|
| App Endpoint | The 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 indicate the availability status of the provided endpoint. Today, availability merely indicates if the endpoint provided is responsive to a layer 3 request.
Today, your application must be publicly accessible or connected via the Diagrid CLI to establish connectivity from Catalyst. This is a temporary limitation, with virtual network integration planned for a future release.