Subject: [Acme] Allowing clients to understand the account creation functionality supported by a server

From: Zach Shepherd <[email-masked]>
Date: Wed, 22 Mar 2017 05:13:16 +0000

The following feedback is based on 8010a31 (current HEAD of master).

Section 7.3, Account Creation, states "The server SHOULD validate that the contact URLs in the “contact” field are valid and supported by the server. If the client provides the server with an invalid or unsupported contact URL, then the server MUST return an error of type “invalidContact”, with a description describing the error and what types of contact URL the server considers acceptable."

It is undesirable that a client can only determine the supported schemes for contact URLs by attempting to submit an unsupported URL. This makes it difficult to implement a general-purpose client which can work with a variety of servers which might each support a different set of contact schemes.

I would propose including information about the supported contact schemes in a machine readable format as a part of some GET request.

Section 7.3, Account Creation, also states "A client creates a new account with the server by sending a POST request to the server’s new-account URI. The body of the request is a stub account object containing the “contact” field and optionally the “terms-of-service-agreed” field. ... The server MUST ignore any values provided in the “orders” fields in account bodies sent by the client, as well as any other fields that it does not recognize. If new fields are specified in the future, the specification of those fields MUST describe whether they can be provided by the client."

Similarly, it would be beneficial for a client to be able to determine the set of fields that a server does recognize so that it does not prompt the user for information which the server will not make use of.

I would propose including information about the fields which may be specified as a part of account creation in a machine readable format as a part of some GET request.

Together, these proposals could be addressed by responding to GET requests on the server's new-account URI with an object describing the client-specifiable account creation fields and applicable restrictions on each, such as the supported schemes for contacts URLs.

Regards,
Zach Shepherd

---

From: Daniel McCarney <[email-masked]>
Date: Wed, 22 Mar 2017 13:43:07 -0400

Hi Zach,

> It is undesirable that a client can only determine the supported schemes
for contact URLs by attempting to submit an unsupported URL. This makes it
difficult to implement a general-purpose client which can work with a
variety of servers which might each support a different set of contact
schemes.

I feel your pain, but I'm hesitant to see more metadata/complexity put into
the /directory (I think the "meta" field of the directory resource would be
the best place if anywhere). My gut says it will be unlikely many servers
will allow contact URLs outside of "mailto:" and "tel:" and it seems
reasonably easy to handle the unsupported contact type error. For the
account fields we'd be adding complexity to simplify UI and I'm not
convinced yet its justified.

Another note: If consensus is that we need a machine-readable way for
clients to know ahead of time what contact methods & account fields a
server supports we should also give the same consideration to identifier
types for Section 7.4.1's Pre-Authorization mechanism. A client may want to
know what types of identifiers a server would pre-authorize.

On Wed, Mar 22, 2017 at 1:13 AM, Zach Shepherd <[email-masked]> wrote:

> Section 7.3, Account Creation, states "The server SHOULD validate that the
> contact URLs in the “contact” field are valid and supported by the server.
> If the client provides the server with an invalid or unsupported contact
> URL, then the server MUST return an error of type “invalidContact”, with a
> description describing the error and what types of contact URL the server
> considers acceptable."
>
> It is undesirable that a client can only determine the supported schemes
> for contact URLs by attempting to submit an unsupported URL. This makes it
> difficult to implement a general-purpose client which can work with a
> variety of servers which might each support a different set of contact
> schemes.
>
> I would propose including information about the supported contact schemes
> in a machine readable format as a part of some GET request.
>
>
> Section 7.3, Account Creation, also states "A client creates a new account
> with the server by sending a POST request to the server’s new-account URI.
> The body of the request is a stub account object containing the “contact”
> field and optionally the “terms-of-service-agreed” field. ... The server
> MUST ignore any values provided in the “orders” fields in account bodies
> sent by the client, as well as any other fields that it does not recognize.
> If new fields are specified in the future, the specification of those
> fields MUST describe whether they can be provided by the client."
>
> Similarly, it would be beneficial for a client to be able to determine the
> set of fields that a server does recognize so that it does not prompt the
> user for information which the server will not make use of.
>
> I would propose including information about the fields which may be
> specified as a part of account creation in a machine readable format as a
> part of some GET request.
>
>
> Together, these proposals could be addressed by responding to GET requests
> on the server's new-account URI with an object describing the
> client-specifiable account creation fields and applicable restrictions on
> each, such as the supported schemes for contacts URLs.
>
> Regards,
> Zach Shepherd
>
>
> _______________________________________________
> Acme mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/acme
>
>

---

From: Zach Shepherd <[email-masked]>
Date: Thu, 23 Mar 2017 18:06:04 +0000

Let's consider a simple world where all ACME servers support mailto and some ACME servers support tel.

To create an account, the user provides the necessary information to their AMCE client: one or more email addresses and zero or more phone numbers. The ACME client then attempts to supply all of this information to in an account creation request. Some of the time, this will result in an error because the ACME server does not support tel.

When the ACME client receives this error, it could:
1. Display it to the user and ask the user to adjust their input accordingly. (A poor user experience.)
2. Attempt to parse to the error message to confirm that the problem was the tel. (Hacky.)
3. Assume that the problem was the tel and retry without that. (Very hacky.)

A new ACME server could come along that requires at least one tel or that doesn't support mailto. As a result, ACME clients may chose to attempt #2 and/or #3 before falling back to #1.

This means that ACME clients have one of six different behaviors (#1, #2, #3, #2 falling back to #1, #3 falling back to #1, #2 falling back to #3 falling back to #1), some of which add a non-trivial amount of complexity to attempt to parse error messages (yuck.) and some of which end up pushing the complexity onto the end-user in end anyways. (Or worse, ACME clients wind up with hard-coded assumptions based on a specific ACME server implementation and become less portable.)

Providing information about the supported contact schemes in a machine readable format (e.g., in response to a GET requests on the server's new-account URI) does add work for ACME server implementors, but not so much that it's worth complicating the end-user experience.

Regards,
Zach

________________________________
From: Daniel McCarney <[email-masked]>
Sent: Wednesday, March 22, 2017 10:43 AM
To: Zach Shepherd
Cc: [email-masked]
Subject: Re: [Acme] Allowing clients to understand the account creation functionality supported by a server

Hi Zach,

> It is undesirable that a client can only determine the supported schemes for contact URLs by attempting to submit an unsupported URL. This makes it difficult to implement a general-purpose client w…

I feel your pain, but I'm hesitant to see more metadata/complexity put into the /directory (I think the "meta" field of the directory resource would be the best place if anywhere). My gut says it will be unlikely many servers will allow contact URLs outside of "mailto:" and "tel:" and it seems reasonably easy to handle the unsupported contact type error. For the account fields we'd be adding complexity to simplify UI and I'm not convinced yet its justified.

Another note: If consensus is that we need a machine-readable way for clients to know ahead of time what contact methods & account fields a server supports we should also give the same consideration to identifier types for Section 7.4.1's Pre-Authorization mechanism. A client may want to know what types of identifiers a server would pre-authorize.

On Wed, Mar 22, 2017 at 1:13 AM, Zach Shepherd <[email-masked]<mailto:[email-masked]>> wrote:

Regards,
Zach Shepherd

_______________________________________________
Acme mailing list
[email-masked]<mailto:[email-masked]>
https://www.ietf.org/mailman/listinfo/acme<https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_acme&d=DwMFaQ&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=mLXl-Tt4EwYbR1MBiFQQ0WZ5XFbdy4TsA2LeBwzJ7eE&s=Iwaw66ccf6rwdCNvFQfF5apZ1WRKaNmkYwyfq954enk&e=>

---

From: Daniel McCarney <[email-masked]>
Date: Tue, 28 Mar 2017 18:04:18 -0400

I still think this is the wrong layer to solve this problem. If the crux of
the matter is that `urn:ietf:params:acme:error:invalidContact` isn't
sufficient to distinguish between invalid vs unsupported without parsing we
could add a `urn:ietf:params:acme:error:unsupportedContact` error type and
remove the need for parsing the message of the invalidContact error. This
seems cleaner to me.

I believe there will always be cases where a general purpose ACME client
will attempt to use a feature unsupported by a given server and will have
to react accordingly. Rather than try to preempt all of these cases by
supplying metadata on all of the available options I'd favour refining the
errors the server returns and promoting flexibility in handling them client
side.

On Thu, Mar 23, 2017 at 2:06 PM, Zach Shepherd <[email-masked]> wrote:

> To create an account, the user provides the necessary information to their
> AMCE client: one or more email addresses and zero or more phone numbers.
> The ACME client then attempts to supply all of this information to in an
> account creation request. Some of the time, this will result in an error
> because the ACME server does not support tel.
>
> A new ACME server could come along that requires at least one tel or that
> doesn't support mailto. As a result, ACME clients may chose to attempt #2
> and/or #3 before falling back to #1.
>
> This means that ACME clients have one of six different behaviors (#1, #2,
> #3, #2 falling back to #1, #3 falling back to #1, #2 falling back to #3
> falling back to #1), some of which add a non-trivial amount of complexity
> to attempt to parse error messages (yuck.) and some of which end up pushing
> the complexity onto the end-user in end anyways. (Or worse, ACME clients
> wind up with hard-coded assumptions based on a specific ACME server
> implementation and become less portable.)
>
> Providing information about the supported contact schemes in a machine
> readable format (e.g., in response to a GET requests on the server's
> new-account URI) does add work for ACME server implementors, but not so
> much that it's worth complicating the end-user experience.
>
> Regards,
> Zach
>
> ------------------------------
> *From:* Daniel McCarney <[email-masked]>
> *Sent:* Wednesday, March 22, 2017 10:43 AM
> *To:* Zach Shepherd
> *Cc:* [email-masked]
> *Subject:* Re: [Acme] Allowing clients to understand the account creation
> functionality supported by a server
>
> Hi Zach,
>
> I feel your pain, but I'm hesitant to see more metadata/complexity put
> into the /directory (I think the "meta" field of the directory resource
> would be the best place if anywhere). My gut says it will be unlikely many
> servers will allow contact URLs outside of "mailto:" and "tel:" and it
> seems reasonably easy to handle the unsupported contact type error. For the
>> Section 7.3, Account Creation, states "The server SHOULD validate that
>> the contact URLs in the “contact” field are valid and supported by the
>> server. If the client provides the server with an invalid or unsupported
>> contact URL, then the server MUST return an error of type “invalidContact”,
>> with a description describing the error and what types of contact URL the
>> server considers acceptable."
>>
>> Section 7.3, Account Creation, also states "A client creates a new
>> account with the server by sending a POST request to the server’s
>> new-account URI. The body of the request is a stub account object
>> containing the “contact” field and optionally the “terms-of-service-agreed”
>> field. ... The server MUST ignore any values provided in the “orders”
>> fields in account bodies sent by the client, as well as any other fields
>> that it does not recognize. If new fields are specified in the future, the
>> specification of those fields MUST describe whether they can be provided by
>> the client."
>>
>> Similarly, it would be beneficial for a client to be able to determine
>> the set of fields that a server does recognize so that it does not prompt
>> the user for information which the server will not make use of.
>>
>> Together, these proposals could be addressed by responding to GET
>> requests on the server's new-account URI with an object describing the
>> <https://urldefense.proofpoint.com/v2/url?u=https-3A__www.ietf.org_mailman_listinfo_acme&d=DwMFaQ&c=uilaK90D4TOVoH58JNXRgQ&r=Z9jmRNJFc0_mrYgZ7k4FWDuC1AsqA1UJKUYIM6ZnnNk&m=mLXl-Tt4EwYbR1MBiFQQ0WZ5XFbdy4TsA2LeBwzJ7eE&s=Iwaw66ccf6rwdCNvFQfF5apZ1WRKaNmkYwyfq954enk&e=>
>>
>>
>

---

From: Richard Barnes <[email-masked]>
Date: Tue, 28 Mar 2017 18:14:48 -0400

Dumping some of this info in `directory.meta` doesn't really seem that
tragic to me.  It's not that much information, and could avoid some errors.

I would note, however, that we could also do this in an extension, rather
than in the main spec.

On Tue, Mar 28, 2017 at 6:04 PM, Daniel McCarney <[email-masked]>
wrote:

> I still think this is the wrong layer to solve this problem. If the crux
> of the matter is that `urn:ietf:params:acme:error:invalidContact` isn't
> could add a `urn:ietf:params:acme:error:unsupportedContact` error type
> and remove the need for parsing the message of the invalidContact error.
> This seems cleaner to me.
>
>> To create an account, the user provides the necessary information to
>> their AMCE client: one or more email addresses and zero or more phone
>> numbers. The ACME client then attempts to supply all of this information to
>> in an account creation request. Some of the time, this will result in an
>> error because the ACME server does not support tel.
>>
>> *Subject:* Re: [Acme] Allowing clients to understand the account
>> creation functionality supported by a server
>>
>> Hi Zach,
>>
>> > It is undesirable that a client can only determine the supported
>> schemes for contact URLs by attempting to submit an unsupported URL. This
>> makes it difficult to implement a general-purpose client which can work
>> with a variety of servers which might each support a different set of
>> contact schemes.
>>
>>> I would propose including information about the supported contact
>>> schemes in a machine readable format as a part of some GET request.
>>>
>>>

---

From: Daniel McCarney <[email-masked]>
Date: Wed, 29 Mar 2017 12:49:56 -0400

Do you feel strongly enough about it to make it a MUST? If it isn't a MUST
it seems like we'd be back in the situation that Zach wants to avoid.

On Tue, Mar 28, 2017 at 6:14 PM, Richard Barnes <[email-masked]> wrote:

>>> A new ACME server could come along that requires at least one tel or
>>> that doesn't support mailto. As a result, ACME clients may chose to attempt
>>> #2 and/or #3 before falling back to #1.
>>>
>>> This means that ACME clients have one of six different behaviors (#1,
>>> #2, #3, #2 falling back to #1, #3 falling back to #1, #2 falling back to #3

---

From: Josh Soref <[email-masked]>
Date: Thu, 30 Mar 2017 19:42:23 -0400

>From my perspective, the UX from not having this feature is pretty awful.
And for clients to try to make the UX not awful, they'd have to add quite a
bit of complexity.

I'd much rather a must with a bit of extra information in the meta
directory.