Add dest_app_name, dest_app_id, display_username, max_age and prompt

[scweber-cisco]

Adds five optional parameters Duo's authorize endpoint accepts that this SDK could not send, plus the one field Duo returns in response to them. The first three are the Java SDK equivalent of duosecurity/duo_universal_python#42; max_age and prompt are documented by Duo but aren't in the Python SDK yet.

All five are claims in the signed request JWT:

Claim	Meaning
dest_app_name	User-facing name of the application the user is authenticating to. Duo shows it in Duo Mobile and records it in the authentication log.
dest_app_id	Long-lived unique identifier for that application. Not shown to users.
display_username	Username shown in Duo Mobile's "user" field for Push, in place of the Duo username. Does not change which user Duo authenticates.
max_age	How many seconds may have passed since the user last authenticated interactively. A remembered session older than this forces interactive reauthentication.
prompt	login forces interactive reauthentication even when a remembered session exists, equivalent to a max_age of 0.

Duo distinguishes an absent claim from one present with an empty value, so each is omitted from the JWT unless the caller supplies a value. None of the five is validated locally, matching the Python SDK, which validates only username, state and nonce — Duo is the authority on what it accepts.

max_age is a boxed Integer rather than an int so that unset stays distinguishable from 0, which forces interactive reauthentication rather than meaning "no limit".

Response field

Duo echoes dest_app_name back in the ID token as auth_context.application.destination_name, but Application only had key and name, so Utils.getApplication was silently dropping it. The other four aren't documented as being returned anywhere in the token, so they need no response-side counterpart.

API surface

Rather than grow createAuthUrl to eight positional arguments — where destAppName, destAppId and displayUsername are easy to transpose with no compile error — this adds AuthUrlOptions with a builder:

String authUrl = duoClient.createAuthUrl(
        new AuthUrlOptions.Builder(username, state)
                .setNonce(nonce)
                .setDestAppName("Acme VPN")
                .setDestAppId("vpn-prod-1")
                .setDisplayUsername("a.smith@acme.com")
                .setMaxAge(3600)
                .setPrompt(AuthUrlOptions.Prompt.LOGIN)
                .build());

Username and state live inside the options object rather than staying positional. That's what keeps the change source compatible: a three-argument createAuthUrl(username, state, AuthUrlOptions) would have made existing createAuthUrl(username, state, null) calls ambiguous and stopped them compiling. As written, every existing call shape is untouched:

client.createAuthUrl(username, state);         // unchanged
client.createAuthUrl(username, state, nonce);  // unchanged
client.createAuthUrl(username, state, null);   // still compiles

Both existing overloads now delegate to the options path, so the pre-existing nonce and validation tests cover that delegation. The two-argument Application constructor is likewise left alone, matching how Token handles amr and nonce.

prompt is an AuthUrlOptions.Prompt enum, so an unsupported value is a compile error rather than something Duo rejects at runtime.

Utils.createJwtForAuthUrl takes the options object for the same reason — it was already at seven positional parameters. It's package private, so only its two callers in UtilsTest changed.

Tests

Thirteen new tests, each watched fail before the implementation existed:

• one per claim reaching the request JWT; the display_username test also asserts duo_uname is unaffected, since only the displayed name should change
• a max_age of 0 is sent rather than swallowed — the case an if (maxAge > 0) style check would silently break
• unset options leave the claims out of the JWT entirely
• createAuthUrl(null) throws DuoException("Missing options") rather than an NPE
• destination_name maps out of auth_context.application, and is null when Duo omits it
• a new ApplicationTest covering equals and hashCode; the RED here was two applications differing only in destination_name comparing equal

The omission test would have passed on arrival, since the null check was written alongside the first claim. It was mutation-verified instead, and again when max_age and prompt were added to it: emitting the claims unconditionally produced expected: <true> but was: <false>.

80 tests pass, checkstyle is clean on both modules, and mvn install succeeds.

Also tested manually, modifying the demo app to pass the destination application and display parameters and verifying they flow through the auth as expected.

Example app

duo-example now uses the options form, with a commented block showing the five new setters. Its behavior is unchanged — it sets none of the new values.

🤖 Generated with Claude Code

[AaronAtDuo]

Since this is meant to be an example app, let's move the new options out of a comment and actually exercise them.

[scweber-cisco]

I might lean toward leaving this as a commented example, rather than default behavior. All of these fields have specific use cases that are not the most common path.

• Destination app information is only relevant for SSO-like applications that are sending the user to potentially multiple destinations through a common authentication experience
• Display Username is only needed if, for whatever reason, the username in Duo is different from the username that the user expects to see
• Max Age and Prompt are overrides for policy that is defined on the Duo side and may lead to confusion if enabled by default

If you feel strongly about defaulting any of these, happy to adjust.

[AaronAtDuo]

Should the param type be an enum, if we will only ever accept a specific list of values?

[scweber-cisco]

I was leaning toward using the more general String so that if/when Duo support for additional values is added, the SDK would not have to be updated. However, it is likely that an SDK update would be needed anyway to address other behavior changes that come along with different prompt values.

The other consideration is that OIDC defines prompt as a space-delimited list of values, but we can cross that bridge if/when it comes.

[AaronAtDuo]

I see no value in these tests

[scweber-cisco]

There's a real risk when equals/hashCode are manually coded that new parameters are not added to these calculations, but the number of tests here is probably overboard. How about we trim down rather than eliminate entirely?