add guidance on implementing identity&auth workflow by lucix-aws · Pull Request #2906 · smithy-lang/smithy

lucix-aws · 2025-12-23T20:34:15Z

No description provided.

github-actions · 2025-12-23T20:34:33Z

This pull request does not contain a staged changelog entry. To create one, use the ./.changes/new-change command. For example:

./.changes/new-change --pull-requests "#2906" --type feature --description "add guidance on implementing identity&auth workflow"

Make sure that the description is appropriate for a changelog entry and that the proper feature type is used. See ./.changes/README or run ./.changes/new-change -h for more information.

lucix-aws · 2025-12-23T20:36:36Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+
+```java
+public interface IdentityResolver<TIdentity extends Identity> {
+    TIdentity resolve(Object properties);


The identity resolver / signer property bags are not formally defined here so I've just left them with an Object placeholder. I think the typed property bag construct needs its own section in these guidance docs.

lucix-aws · 2025-12-23T20:37:13Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+// model the Signer as an interface that returns a copied, modified transport
+// message instead.
+public interface Signer<TIdentity extends Identity, TMessage extends Message> {
+    void sign(TIdentity identity, TMessage message, Object properties);


The original doc assumed HTTP, I know formally we want to speak in terms of transport agnosticism so I've parameterized the transport type.

lucix-aws · 2025-12-23T20:37:55Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+```java
+// in this example, the service supports some combination of
+// smithy.api#httpBearerAuth and aws.auth#sigv4
+public MyServiceClientConfig defaultConfig() {


These types of code snippets seem useful to the reader but as we build out these docs we want to make sure we have a standard for stuff like this (i.e. showing how to bootstrap a default config).

lucix-aws · 2025-12-23T20:38:52Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+This may be implemented like the following:
+
+```java
+public void resolveAuthScheme(OperationContext ctx) {


Again, including snippets like this seems helpful but we should be consistent. I elected to just model the examples as using this opaque / undescribed "operation context" input that has the stuff you'd expect on a request.

lucix-aws · 2025-12-23T20:39:52Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+) {}
+```
+
+## Order of Operations


I have issues with this as written tbh. It explains how to use all the parts but it feels incomplete. Perhaps referring to an "order of operations" section once we do that (like the original docs have) will make it make more sense.

lucix-aws · 2025-12-23T20:40:52Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+
+## FAQ
+
+### Wow, this seems like a lot. Do I really need all of these abstractions just to decide how to set an Authorization header?


Probably controversial but this felt absolutely worth stating IMO. I think a lot of client designers will sort of stick to baking in a single transport type (probably HTTP). The language of the question is probably too colloquial ofc.

lucix-aws · 2025-12-23T20:45:20Z

MISSING! An actual example of an AuthSchemeResolver. IMO that is perhaps worth including but I know we are focusing on the runtime here rather than what's code-generated. I think actually showing an example of one for a simple 2-3 operation service that does per-operation multiauth would be of value to the reader, though.

JordonPhillips

General feedback:

When referring to a class in text, it should be enclosed in an inline block with backticks (Foo). I started making comments for each, but there's quite a few.

I'll do another pass later after I've had a chance to think more about the interfaces themselves

JordonPhillips · 2026-01-13T15:13:41Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+the service in order to allow the service to authenticate the Smithy client
+caller's identity.


nit: This validation isn't specific to Smithy clients.

Suggested change

the service in order to allow the service to authenticate the Smithy client

caller's identity.

the service in order to allow the service to authenticate the caller's identity.

JordonPhillips · 2026-01-13T15:14:02Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+
+    /**
+     * Provides an Identity Resolver for this authentication scheme.
+     * This API can return a nullish value indicating that an identity


Suggested change

* This API can return a nullish value indicating that an identity

* This API can return a null value indicating that an identity

JordonPhillips · 2026-01-13T15:14:56Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+private void selectAuthScheme(OperationContext ctx, List<AuthSchemeOption> options) {
+    MyServiceClientConfig config = ctx.clientConfig();
+
+    for (AuthScheme option : options) {


Suggested change

for (AuthScheme option : options) {

for (AuthSchemeOption option : options) {

JordonPhillips · 2026-01-13T15:15:12Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+        //
+        // note that we are only checking whether there IS an identity resolver, not whether
+        // it can actually provide an identity
+        IdentityResolver resolver = scheme.getIdentityResolver(config);


Suggested change

IdentityResolver resolver = scheme.getIdentityResolver(config);

IdentityResolver resolver = found.get().getIdentityResolver(config);

JordonPhillips · 2026-01-13T15:16:55Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+# Identity and Authentication
+
+Operations supported by a Smithy service generally require a mechanism for
+authenticating the client's identity. This section describes how to model the


Suggested change

authenticating the client's identity. This section describes how to model the

authenticating the caller's identity. This section describes how to model the

JordonPhillips · 2026-01-13T15:28:04Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+The Smithy IDL allows clients to model operations which support **multiple**
+authentication schemes. Correspondingly, a Smithy client may be loaded with
+multiple AuthSchemes at runtime. The AuthSchemeResolver is the entity through
+which the appropriate AuthScheme is selected and employed for a given operation
+call.


Suggested change

The Smithy IDL allows clients to model operations which support **multiple**

authentication schemes. Correspondingly, a Smithy client may be loaded with

multiple AuthSchemes at runtime. The AuthSchemeResolver is the entity through

which the appropriate AuthScheme is selected and employed for a given operation

call.

Smithy allows clients to model operations which support **multiple**

authentication schemes. Correspondingly, a Smithy client may be loaded with

multiple `AuthScheme`s at runtime. The `AuthSchemeResolver` is the entity through

which the appropriate `AuthScheme` is selected and employed for a given operation

call.

JordonPhillips · 2026-01-13T15:58:56Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+1. Retrieve the IdentityResolver from the previously-resolved AuthScheme
+   (AuthScheme::identityResolver). Identity resolution
+   (IdentityResolver::resolve) is called with the identity properties sourced from
+   scheme resolution.
+1. Retrieve the Signer from the previously-resolved AuthScheme
+   (AuthScheme::signer). Request signing (Signer::sign) is called with the
+   merged signer properties from scheme and endpoint resolution.


These both mix passive and imperative, a consistent tense should be used

JordonPhillips · 2026-01-13T16:00:00Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+The example set of interfaces provided in this listing represents the most
+rigorous possible solution for implementing Identity & Auth. These interfaces


Suggested change

The example set of interfaces provided in this listing represents the most

rigorous possible solution for implementing Identity & Auth. These interfaces

The example set of interfaces provided in this listing represents a

rigorous solution for implementing Identity & Auth. These interfaces

JordonPhillips · 2026-01-13T16:00:26Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+rigorous possible solution for implementing Identity & Auth. These interfaces
+support multiple authentication schemes, _across_ multiple identity types and
+transport message types. The Smithy client implementor is free to simplify
+along any of those dimensions as fits their service needs.


Suggested change

along any of those dimensions as fits their service needs.

along any of those dimensions as fits their needs.

JordonPhillips · 2026-01-13T16:04:43Z

docs/source-2.0/guides/client-guidance/identity-auth/index.md

+
+### What about operations with no authentication?
+
+"Anonymous" (no authentication) is explicitly modeled via `@smithy.api#noAuth`.


This is what appears when you use the auth knowledge index, but it's a synthetic trait that isn't explicitly modeled. Anonymous auth is specified with an empty auth trait list (@auth([])) or as a consequence of using the optionalAuth trait.

Optional auth should also be discussed here.

add guidance on implementing identity&auth workflow

cc219a9

lucix-aws requested a review from a team as a code owner December 23, 2025 20:34

lucix-aws requested a review from joewyz December 23, 2025 20:34

lucix-aws marked this pull request as draft December 23, 2025 20:35

lucix-aws commented Dec 23, 2025

View reviewed changes

JordonPhillips reviewed Jan 13, 2026

View reviewed changes


		## FAQ

		### Wow, this seems like a lot. Do I really need all of these abstractions just to decide how to set an Authorization header?

		the service in order to allow the service to authenticate the Smithy client
		caller's identity.

	* This API can return a nullish value indicating that an identity
	* This API can return a null value indicating that an identity

	for (AuthScheme option : options) {
	for (AuthSchemeOption option : options) {

	IdentityResolver resolver = scheme.getIdentityResolver(config);
	IdentityResolver resolver = found.get().getIdentityResolver(config);

	authenticating the client's identity. This section describes how to model the
	authenticating the caller's identity. This section describes how to model the

		The example set of interfaces provided in this listing represents the most
		rigorous possible solution for implementing Identity & Auth. These interfaces

	along any of those dimensions as fits their service needs.
	along any of those dimensions as fits their needs.


		### What about operations with no authentication?

		"Anonymous" (no authentication) is explicitly modeled via `@smithy.api#noAuth`.

Conversation

lucix-aws commented Dec 23, 2025

Uh oh!

github-actions bot commented Dec 23, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucix-aws Dec 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lucix-aws commented Dec 23, 2025

Uh oh!

JordonPhillips left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

lucix-aws Dec 23, 2025 •

edited

Loading