[WG-OTTO] Fwd: Re: [refeds] Initial API design
mike at gluu.org
Wed Feb 22 15:48:08 CST 2017
I previously wasn't aware of this effort.
We need to take a closer look at their design to see if we're missing
-------- Original Message --------
Subject: Re: [refeds] Initial API design
Date: 2017-02-22 09:00
From: Rhys Smith <Rhys.Smith at jisc.ac.uk>
To: "refeds at lists.refeds.org" <refeds at lists.refeds.org>
Reply-To: refeds at lists.refeds.org
By the way, one thing I didn’t mention: the API's authorisation model
currently works like this:
API users are given a credentials (c.f. the Authentication section of
the docs), each credential either specifies a particular member that
that credential is allowed to make modification for, or is an admin
credential that can make any modifications.
For our web front-end, the front-end uses an admin credential and deals
with authorisation itself (the portal its behind understands all of the
Jisc membership, so the API basically delegates authorisation).
But to give direct access to the API for certain members, you just set
up a new non-admin credential and they are constrained to only be able
to make changes to the member/entities related to that credential.
Dr Rhys Smith
Chief Technical Architect, Trust & Identity
T: +44 (0) 1235 822145
M: +44 (0) 7968 087821
Lumen House, Library Avenue, Harwell Oxford, Didcot, OX11 0SG
Jisc is a registered charity (number 1149740) and a company limited by
guarantee which is registered in England under Company No. 5747339, VAT
No. GB 197 0632 86. Jisc’s registered office is: One Castlepark, Tower
Hill, Bristol, BS2 0JA. T 0203 697 5800.
> On 22 Feb 2017, at 15:53, Rhys Smith <Rhys.Smith at jisc.ac.uk> wrote:
> Hi all,
> I’ve been promising for a while to publish the draft API that we’ve
> been building for federation entity management, as a part of some work
> the UK federation is currently in the middle of. And Mads made me
> promise to finally get around to it…
> TL;DR - draft API docs are available on https://api.dev.ja.net/api.html
> - if you go to the bottom of the page and click on the get/put/etc
> it’ll popup with detailed request/response info. It is still draft, so
> if there are any bits missing, just ask :-).
> In a bit more detail...
> The basic overview is that there are three APIs:
> * Member management
> * Entity management
> * Approval management.
> The basic APIs are of course pretty simple, and it’d be good if this
> can be as reusable as possible. Our particular implementation of them
> is then of course more complex, and makes certain assumptions about how
> you (well, we) operate - i.e. Git backend, etc. But the API as is
> should generalise to whether you store backend stuff in XML in a
> repository; in a database; whatever.
> (Note, the reason there’s an approvals API is so that anything using it
> can essentially be stateless (other than maybe caching things for
> To detail our implementation of the API a bit to demonstrate its usage…
> Our implementation is level 3 RESTful, and works at an XML level. That
> is, you GET/PUT/POST/DELETE, and give and receive XML that represents
> membership, entities, or approvals. Behind the API is a version of the
> Shibboleth MDA with extensions to enable this stuff, and everything is
> basically MDA flows behind the scenes.
> 1) The member management bit allows federation membership to be managed
> - creating new members, updating existing, removing existing.
> Membership includes the organisation name and any “approved” items for
> that member. I.e. approved domains for use in entityIds and scopes,
> approved entity categories for specific entities of the member (for
> those that require approval), etc.
> 2) The entity management bit allows entities to be managed. You can add
> a new entity by POSTing, you can get an existing one by GETTING, you
> can update an existing one by PUTTING, and you can delete an existing
> one by DELETEing. When adding/updating, certain items in the XML are
> always set by the backend, no matter what the API user POSTs/PUTs (e.g.
> MDRPI tags are under the control of the federation, not the entity) -
> so if the API user put their own MDRPI tag in, it gets replaced with
> ours. This is done for a few of the bits and pieces in the XML.
> 3) The approvals management bit allows items requiring approval to be
> managed. - Items can be added to the queue and removed, as you’d
> To give an example of the usage of these three things, imagine a
> scenario where an existing member is using the front-end portal that
> makes use of the API, and they want to add a new entity that is using
> an entityId containing a domain name that we haven’t yet approved their
> usage of. This is what would happen:
> Step 1) User submits entity MD in the UI that makes use of the API.
> Step 2) API checks the incoming request, does the usual/obvious checks
> (like whether it’s actually schema valid, etc), decides it’s “good”
> metadata, but notices the the domain isn’t approved, so it rejects the
> request with an error message specifying that it has failed because the
> domain requires approval.
> Step 3) The UI tells the user the request has been rejected, asks the
> user if they wish to submit the request for approval. User says yes.
> Step 4) The UI then puts the new entity request onto the approvals
> Step 5) Admin finds out there’s something that requires approval, goes
> to the UI, pulls the list of things on the approval queue, and looks at
> the details. They see the entity is attempting to use an unapproved
> domain. Admin out-of-band does all the checking of domain ownership,
> etc, possibly interacting with the customer via email. Once admin is
> satisfied the member does have the right to use that domain, they hit
> the “approve” button.
> Step 6) UI gets the current member details from the members API, alters
> the XML to include the newly authorised domain, and puts it back to the
> member API.
> Step 7) UI then re-submits the entity MD to the entity API, which this
> time around passes all the checks, and the entity gets added to the set
> of entities in the backend.
> As I said above, more detailed API docs are available on
> N.B. One thing we’ve not spent much time on so far is authentication to
> the API. We’ve currently got a very simple model, detailed in the docs.
> This could of course switch to something more interesting like OAUTH or
> whatnot. Of course, that’s not really the interesting part of all of
> this, just a detail to work out.
> And this is all, of course, a separate set of work from the front-end
> that makes use of the API. We’re in the middle of implementing that as
> well, and will do all the things you’d expect (nice simple PEER-like MD
> management UI that lets you update MD without touching the XML if you
> don’t want to).
> Anyway, this is all still in development though the API has settled
> down a lot over the last few months. Happy to talk to people interested
> in this stuff either over email, or in person at REFEDS, TNC, etc.
> Dr Rhys Smith
> Chief Technical Architect, Trust & Identity
> T: +44 (0) 1235 822145
> M: +44 (0) 7968 087821
> Skype: rhys-smith
> GPG: 0x4638C985
> Lumen House, Library Avenue, Harwell Oxford, Didcot, OX11 0SG
> Jisc is a registered charity (number 1149740) and a company limited by
> guarantee which is registered in England under Company No. 5747339, VAT
> No. GB 197 0632 86. Jisc’s registered office is: One Castlepark, Tower
> Hill, Bristol, BS2 0JA. T 0203 697 5800.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 3859 bytes
Desc: not available
More information about the WG-OTTO