Connector Auth Model


There has been some discussion in Interledger Slack about how Ilp-over-Http nodes should authenticate to each other, and how we should think about the identity relationship between two parties in ILP.

I wrote a brief article to summarize my thoughts on the topic here: Connector Auth Security

Essentially, I see two auth models that we could leverage between ILP nodes, and my article describes a way we could start with the simpler version (account-based auth) and later, potentially, upgrade to a peer-based (multiple-account-per-credential) model in the future. In other words, two different models that can co-exist with each other depending on what an implementation chooses to support.

I’m curious what people think about these two models, and am curious to hear opinions around how people conceive of the identity relationship between two Connectors.

Last but not least, this topic directly relates to this PR in the ILP-over-http spec.


Thanks for the write up @sappenin

I disagree with a few of the assertions you’ve made.

In particular you say that one of the purposes of an account is to:

provide a conduit for exchanging ILP packets in order to facilitate a variety of messaging, financial, and other (potentially multi-hop) operations related to Interledger

This suggests to me that we have different ideas of what an account is. In the context of ILP I consider an account to be simply a record of the financial position of a peer with another peer. i.e. It’s a financial concept like a bank account, or account in a chart of accounts for a business.

I believe that what you are describing is more like a user account/login like you would have with an email provider or an online service.

I prefer the former interpretation because unlike many services that track “user accounts” an ILP connector DOES track a financial account for its users/peers. If we use the term “account” to define the whole relationship between the two peers then how do we differentiate that from the financial account specifically?

Let’s agree on the domain model (I think we do but let’s be clear):

  1. the two entities that are establishing a relationship are “peers”
  2. a peer will maintain an accounting system (a set of “accounts”) and one or more of these “accounts” will relate to the financial relationship with the peer
  3. these accounts may differ by currency or function. E.g. A peer may track a liability account which tracks the amount owed to the other peer and a separate asset account which tracks the amount owed to it by the other peer. Or the peer may just maintain a single consolidated account which is a net of both owed and owing but track multiple of these because it settles with the peer in multiple currencies.

On the basis of that model I think it’s entirely inappropriate to perform authentication between peers using an account identifier as the subject of the authentication.

The entity being authenticated is the peer so the subject should be the peer identifier.

It’s possible that a connector may offer an alternative authentication scheme where the subject is an account. This would likely be a claims-based authentication scheme (i.e. the subject is the account and the token is a signed claim that proves the holder can transact against the account) but I would recommend against that being an interoperability requirement, it’s a complex authentication scheme that requires the auth layer to access the accounting/business layer to perform the authentication.

With regards to

My recommendation is that we stick with ilp-peer-id as the header we expect for disambiguating packets from different peers at the same endpoint.


@adrianhopebailie Thanks for your post - very helpful.

I think you’re right - maybe for clarity let’s qualify our usages (at least for this dialog, anyway) and say that a peer maintains “financial accounts”, each of which tracks some sort of financial position with a peer (e.g., a single net-balance, or some other balance-tracking mechanism).

Yes, this is correct, although I think our two definitions can co-exist.

I say this because overall I’m trying to arrive at is just an authentication mechanism (i.e., an identity and a credential to prove that identity) and my overall point (read below) is that there are many valid possibilities for a Connector to uniquely identify (i.e., authenticate) incoming connections.

This is not always true, and needn’t be always true.

For example, let’s imagine there are two companies, BigCo and SmallCo, and they want to “peer” with each other using ILP-over-HTTP.

For example’s sake, let’s say that BigCo has a database that stores a peerId for each of its peers, and so it has an entry in a database for SmallCo that is “sco”. Likewise, SmallCo has a database that stores peerId and SmallCo’s database has an entry for BigCo that is “bco”.

Now, let’s also imagine that BigCo is a sophisticated Connector operator, so they issue credentials that allow peers to operate across multiple financial accounts (for the sake of argument, we could imagine a token-authorization scheme that peers can utilize to get limited-access tokens to operate on one more more financial-accounts, depending on authorities granted in the token). We can also imagine that, in addition to offering complex permissions per-credential, BigCo also allows its peers to each hold multiple credentials so that some of its peer’s employees can use the BigCo connector with limited access, whereas other credentials might provide broader access (e.g., an “admin” account and a “payor” account).

Now, let’s also imagine that SmallCo is not quite so sophisticated, and when SmallCo issues a credential to BigCo, the credential is just a very simple shared-secret that only works with a single financial account at SmallCo.

While I agree that your domain-model accurately describes BigCo and SmallCo as “peers”, the auth-credentials they utilize are orthogonal to this concept. BigCo is providing one or more identities to SmallCo that transcend the concept of a financial account or a peer. Conversely, SmallCo is providing an identity that is strongly tied to one, and only one, financial account (ignoring the peer identifier entirely).

In this example, saying that the “subject” of the authentication credential is “the peer id” is just incorrect. In neither example at BigCo nor SmallCo are credentials identified with “sco” or “bco”. Instead, the “subject” of the authentication credential is something else, and it’s not always the same even between two peers due to the nature of ILP-over-HTTP.

All that so say: I’m not saying you’re peerId-as-Auth-Identifier is “wrong” in and of itself (quite the opposite, it could be a valid auth-scheme if two peers desired it). Instead, I’m saying that it would be a mistake to mandate this auth scheme on every bilateral peer relationship. It doesn’t need to be normalized.

I think as a non-normative suggestion, this is fine if it fits the auth-model between two peers.

However, as a normative part of the spec, this breaks down if the two peers don’t identify themselves using their peer identifiers (assuming these identifiers even exist between two peers).

All that to say, I think we should either close or else introduce a new section that details (non-normatively) how peers might use extra headers to help with authentication.

As one final example, the Java ILP-over-HTTP implementation supports a JWT authentication mode where the entire token can trivially be used in a performant manner without any additional headers. This is proof enough that this header is only sometimes required.


Okay, I think we’re on the same page! When I said:

I was thinking exactly along the lines you are. Auth is orthogonal to the domain specifics (peers, accounts etc).

My concern was that if we were going to make normative changes to the spec that require support for a header carrying the subject of an auth then we should keep that list of possible headers (credential labels) as small as possible and the only one that makes sense as a normative requirement is peer.

I’m very happy to not make this normative with the caveat that I think we SHOULD define at least one auth mechanism that is a minimum requirement for all connectors. (I think these can even be defined in the Open API spec).

My goal is a mechanism for auto-mated peering between connectors without a need for manual intervention (e.g. to configure credential)

1 Like