Create stand-alone 'how to participate' section in README.md (somewhere up-front)

[ausdigital]

Create stand-alone 'how to participate' section in README.md (somewhere up-front)

[asmith1024]

swaggerhub API specifications are broken, but not sure where to tracj that. They're linked from these documents, so the post is here. Need to add audit service specifications, and core APIs need some work. Authorisation, URI path design, end-to-end crypto & signing (without WS-Security bloatware), payload-agnostic. The swaggerhub repo is read only - where should suggestions go?

[markmuir87]

Sorry for the very late reply, had a family emergency so was out of the country for a bit. Just to clarify, are you saying swaggerhub specs are fundamentally broken, or our particular instance of them are?

Steve might have a view on this but I figured the higher level suggestions would either be github issues or pull requests, and nitty gritty changes to the spec and prototype implementation would occur on swaggerhub (or wherever we decide to mock/prototype the APIs).

Totally with you on avoiding the awfulness that is WS-*. OAuth/OpenID Connect seems like a nice fit to me. In the past, I wrote a client/relying party implementation of one of the OIDC auth flows, just reading straight from the spec. I actually spent more time hunting around for a pre-canned OIDC library than I did just doing doing it myself.

This looks like a very nice shortcut in that direction: https://github.com/ory-am/hydra#what-is-hydra . It's also Apache 2.0 licensed. An attribute-based credential system like OAuth seems like a nice fit for authorising third-parties to act on businesses' behalf, businesses authorising employees to make purchases within certain limits etc. They'd simply be separate OAuth scopes that reflect the underlying relationship/delegations between the parties.

The other necessary component of all this (e.g. invoice signing, non-repudiation, proof-of-existence, document authentication etc.) I'm less sure on. In theory we could abuse the OAuth spec into fulfilling some of these functions, but that doesn't sound ideal. I've been thinking of something along the lines of a public/private key system where the government basically acts as public key repository (which are publicly bound to ABNs), publishes authorisations made by businesses and also publishes buinsess technical capabilities/endpoints. In other words, a centralised registry function (key server and directory). It's the one area where I think it makes sense for government to centrally control this part of the system. Probably worth a bit of careful thinking and discussion.

This is how AUSkey should have been used, incidentally. It's still possible I suppose, given it's just an x509 cert jammed into some weird proprietary container (or something). But perhaps a good idea to see if there are better alternatives around, given it's been a decade or so since AUSkey was first released.

But yeah, on the participation stuff, Steve is the guy to talk to as he initially set up this infrastructure, so will need to be the one doling out the access/authorisation. I'm only really here because I'm interested in this stuff; not really here in any 'official' Treasury capacity (we have another rep on the committee I think).

[asmith1024]

Our instances are broken, not the whole site. Swagger itself is pretty good, even if the UI generator is a glorified cross-site scripting vulnerability factory. Swaggerhub neatly side-steps that problem. Not sure we need to bother with documents with our solution just yet - we have another working group for that. Getting the security and the RESTful semantics right is enough to be getting on with for now.

[onthebreeze]

On the initial topic of this ticket
https://github.com/ausdigital/framework-docs#how-to-participate