July 18, 2017
Joel Farrell, Prasad Chodavarapu. Valerie Smothers, Luke Woodham
1 Security Guidelines
Joel noted that Prasad made changes as discussed. He strengthened the recommendations. Joel had been concerned about the security protocols. Although SAML adopted by certain groups, they were enthusiastic about trying to take a firm stand on open id and OAuth.
Prasad reviewed the changes. He added on pg 12 two types of clients: confidential and public. All server side clients are confidential. Newer frameworks are considered public clients; they are running in the browser, and the security mdoel changes. OAuth cannot trust the browser. Section 4.1 has some edits and new diagrams. He did the same for 4.2. Valerie asked if universal hub used that model. Prasad replied that Universal Hub did not use OAuth. The Hub is doing some work between the enterprises. In the OAth model, new applications are registered more easily. he also added a diagram in 4.3. the AAMC's list of medical schools might be a public API. 4.3.4 now includes the term user delegation. This is when the user authorizes an app to access information or resources. Due to privacy policies, it's often easier to use this model. Office 365 is an example of an Enterprise resource access provided through Web API. Some applications are incorporating SAML for authentication, then using OAuth in a hybrid model. He's added that to section 5. Basically it plugs SAML into OAuth. Joel asked if that was supported by third party apps. Prasad noted OAuth is just a framework. He has seen it in one vendor. SAML cannot support User Delegation. Joel noted this was a way to bridge the gap. We can tell people how to do migration form SAML, but if they are aware of a way to bridge, they would like to do that. In common is SAML based. The medical school IT organizations are wed to those approaches. Joel noted a few small edits. He recommended after looking at those suggestions we publish the document. Valerie will update the references for consistency and aim to publish in September.
2 JSON usage
The USCF team has asked if we should have a standard for how we return data in the APIs. We left things a little open there in the API document indicating a close relationship with existing standards. They brought up JSON API and JSON LD. They were more interested in JSON API. JSON LD is for representing linked data. Joel did not think JSON LD was a good fit. JSON API seems more applicable. jsonapi.org is where the spec is. If you want to decide how data should be formatted back and forth, there are collections of objects that are part of the payload, this dictates how that should look, how you format output. It is very restful approach. There is a lot of information about metadata, navigating through collections of resources.
Prasad noted that they use Swagger. It uses JSON schema to represent what it will look like. It's automatically built from annotation. You can see the data directly in json or xml. We've indicated that you can use accept header to specify json or xml.
Joel noted that Swagger uses open API. how prescriptive is it on how the API is structured? JSON API talks about required and optional objects. Also an error object. Does Swagger go into that? Prasad replied yes. Swagger could turn it into json schema. Easier if system generated. Joel recommended if UCSF could give an example of how they would see an API that used JSON API that shows how it would look. He could see how it could be helpful. Other scenarios, it seems like too much. It's about arrays of objects you can move through. How much of what is defined in JSON API are they needing? He asked the gorup to read up on JSON API and Open API under Swagger. They could join a call in August if everyone available. Valerie will touch base with Joel about scheduling.
Joel asked about Kirke's request:
At the annual meeting there was a conversation at the TSC about how AAMC and MedBiq could possibly work together on the topic of federated identity management standards or patterns for our shared community. If there is an upcoming TSC call, perhaps this is something that could be put on the agenda (“potential for AAMC-MedBiq collaboration with respect to FIM”) and we could include some of our technical SMEs to be part of the call. This isn’t time-sensitive, but we had a discussion about it today so I said I’d check with you.
Joel agreed the AAMC's support could help that scenario. The Curriculum Inventory working group, when would they need to know? they would need to know when defining responses. Valerie will send Joel the link to the Curriculum Inventory APis. Joel agred we should concentrate on this next time.