Elaborate on service configuration #443

msporny · 2025-01-29T16:56:28Z

This PR attempts to address issue #267 by documenting how service instance configuration works.

Fixes #267.

jrhender

Thanks for the PR. I'd been wondering how to proceed on #419 and maybe this PR helps move that issue forward as well.

jrhender · 2025-01-29T17:30:50Z

index.html

-Instance configuration can include, but is not limited to, credential format, key options, credential status mechanisms, and/or credential templates.
-Administrators are expected to configure service instances such that `options` included in client requests cannot result in incorrect action or problematic responses by the service.
+The APIs defined in this specification presume that they are attached to a
+specific instance of some kind with an associated configuration that has been


To me, the "of some kind" text is superfluous

Suggested change

specific instance of some kind with an associated configuration that has been

specific instance with an associated configuration that has been

jrhender · 2025-01-29T17:36:55Z

index.html

+For example, the `/credentials/issue` endpoint is expected to be at the end of a
+longer URL such as `/instances/12345/credentials/issue`. In this case, it is the


Does it need to be at the end of longer URL? It seems reasonable to me that one could direct to specific instances in other ways. For example, one could use subdomains to address an instance or an internal service discovery mechanism.

+1, I made a suggestion in my review.

jrhender · 2025-01-29T17:40:45Z

index.html

+      <p class="note"
+         title="Use cases can use multiple instances for complex flows">
+A coordinator instance can have access to multiple service instances in order to
+support different use cases. Runtime discovery of service instance configuration
+is not supported by the VC API as services are expected to be known by the
+coordinator at the time of coordinator deployment.


IMO, the current title is too narrow. In my mind, a single coordinator could support multiple use cases and so might need multiple service instances, even the each use case flow is "simple". So having the title suggest that the main use for multiple instances is "complex" flows is too narrow.

Suggested change

<p class="note"

title="Use cases can use multiple instances for complex flows">

A coordinator instance can have access to multiple service instances in order to

support different use cases. Runtime discovery of service instance configuration

is not supported by the VC API as services are expected to be known by the

coordinator at the time of coordinator deployment.

<p class="note"

title="A coordinator can use multiple service instances">

A coordinator instance can have access to multiple service instances in order to

support different use cases or a use case with complex flows. Runtime discovery of service instance configuration

is not supported by the VC API as services are expected to be known by the

coordinator at the time of coordinator deployment.

We might also want to say that "Using multiple service instances, such as different workflows, can also be used to improve a deployment's security profile by limiting the privileges that a coordinator needs to operate. One way this can be done is by restricting the inputs a coordinator can provide when creating an exchange to just a few variables in a workflow-specific template." Or something along these lines.

dlongley

Approving with some suggestions.

dlongley · 2025-01-29T21:50:50Z

index.html

      </p>
      <p>
-A coordinator instance can have access to multiple service instances in order to support different use cases.
-Runtime discovery of service instance configuration is not supported by the VC API as services are expected to be known by the coordinator at the time of coordinator deployment.
+For example, the `/credentials/issue` endpoint is expected to be at the end of a


Suggested change

For example, the `/credentials/issue` endpoint is expected to be at the end of a

For example, the `/credentials/issue` endpoint can be provided at the end of a

dlongley · 2025-01-29T21:52:10Z

index.html

+to configure an instance, or be aware of the setup that the administrator did on
+the instance. Administration endpoints for configuring instances could be
+provided by implementations but are not necessary to expose as HTTP APIs;
+configuration can also be done through configuration files or graphical
+interfaces.


Clients do need to know what is expected to happen when the admin hands them the URL, but otherwise, yes:

Suggested change

to configure an instance, or be aware of the setup that the administrator did on

the instance. Administration endpoints for configuring instances could be

provided by implementations but are not necessary to expose as HTTP APIs;

configuration can also be done through configuration files or graphical

interfaces.

to configure an instance, or be aware of the setup that the administrator did on

the instance other than the requisite details to make appropriate use of it.

Administration endpoints for configuring instances could be

provided by implementations but are not necessary to expose as HTTP APIs;

configuration can also be done through configuration files or graphical

interfaces.

dlongley · 2025-01-29T21:55:21Z

index.html

+      <p class="note"
+         title="Use cases can use multiple instances for complex flows">
+A coordinator instance can have access to multiple service instances in order to
+support different use cases. Runtime discovery of service instance configuration
+is not supported by the VC API as services are expected to be known by the
+coordinator at the time of coordinator deployment.


We might also want to say that "Using multiple service instances, such as different workflows, can also be used to improve a deployment's security profile by limiting the privileges that a coordinator needs to operate. One way this can be done is by restricting the inputs a coordinator can provide when creating an exchange to just a few variables in a workflow-specific template." Or something along these lines.

TallTed · 2025-01-29T21:50:45Z

index.html

-Administrators are expected to configure service instances such that `options` included in client requests cannot result in incorrect action or problematic responses by the service.
+The APIs defined in this specification presume that they are attached to a
+specific instance of some kind with an associated configuration that has been
+put in place by a systems administrator. When a client calls an endpoint on a


Suggested change

put in place by a systems administrator. When a client calls an endpoint on a

put in place by a system administrator. When a client calls an endpoint on a

TallTed · 2025-01-29T21:54:14Z

index.html

+Software clients that call a particular instance might not have the capability
+to configure an instance, or be aware of the setup that the administrator did on
+the instance. Administration endpoints for configuring instances could be
+provided by implementations but are not necessary to expose as HTTP APIs;


Suggested change

provided by implementations but are not necessary to expose as HTTP APIs;

provided by implementations but are not necessarily exposed as HTTP APIs;

msporny added 2 commits January 29, 2025 11:51

Remove trailing whitespace.

9ec6a00

Elaborate on instance configuration.

e9a242a

msporny requested review from BigBlueHat, dlongley, jandrieu, jrhender, eric-schuh and PatStLouis January 29, 2025 16:56

msporny requested review from mavarley and mkhraisha as code owners January 29, 2025 16:56

jrhender reviewed Jan 29, 2025

View reviewed changes

dlongley approved these changes Jan 29, 2025

View reviewed changes

TallTed suggested changes Jan 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Elaborate on service configuration #443

Elaborate on service configuration #443

msporny commented Jan 29, 2025 •

edited by pr-preview bot

Loading

jrhender left a comment

jrhender Jan 29, 2025

jrhender Jan 29, 2025

dlongley Jan 29, 2025

jrhender Jan 29, 2025

dlongley Jan 29, 2025

dlongley left a comment

dlongley Jan 29, 2025

dlongley Jan 29, 2025

dlongley Jan 29, 2025

TallTed Jan 29, 2025

TallTed Jan 29, 2025

	specific instance of some kind with an associated configuration that has been
	specific instance with an associated configuration that has been

		For example, the `/credentials/issue` endpoint is expected to be at the end of a
		longer URL such as `/instances/12345/credentials/issue`. In this case, it is the

	put in place by a systems administrator. When a client calls an endpoint on a
	put in place by a system administrator. When a client calls an endpoint on a

	provided by implementations but are not necessary to expose as HTTP APIs;
	provided by implementations but are not necessarily exposed as HTTP APIs;

Elaborate on service configuration #443

Are you sure you want to change the base?

Elaborate on service configuration #443

Conversation

msporny commented Jan 29, 2025 • edited by pr-preview bot Loading

jrhender left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dlongley left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

msporny commented Jan 29, 2025 •

edited by pr-preview bot

Loading