Merge branch 'master' into feature_multiidp

docs/assets/auth.uml.txt

@@ -0,0 +1,68 @@
+@startuml
+title Current login workflow
+
+participant App
+participant WebView
+participant MAG
+participant IDP
+participant STS
+
+App-[#green]>WebView: Open webview
+activate WebView
+
+group OAuth/IUA flow
+  WebView-[#red]>MAG: **Step 1**\n**[ITI-71]** GET /authorize\nextended access request
+  note right
+    The IUA callback url and client secret must
+    be registered in the MAG
+  end note
+end
+
+group SAML 2 artifact binding
+  MAG-->WebView: Redirect to the IDP
+  WebView->IDP: **[AuthnRequest]** POST with SAMLRequest
+  note right
+    The MAG generates and signes the
+    AuthnRequest with its private key
+  end note
+
+  IDP-->WebView: Show login form
+  App-[#green]>IDP: Sends login info
+
+  note over IDP: The SAML callback URL, entity ID, public key and\nclient TLS certificate must be registered with the IDP
+  IDP-->WebView: Redirect to /SSO (SAML callback URL)\nWith the SAML Artifact
+
+  WebView->MAG: Get SAML Artifact
+  activate MAG
+
+  MAG->IDP: **[ArtifactResolve]** POST
+  note right
+    The MAG uses its client TLS certificate
+  end note
+  IDP-->MAG: Returns the IDP Assertion
+
+  MAG-->WebView: Redirect to /authorize
+  deactivate MAG
+end
+
+WebView->MAG: GET /authorize
+activate MAG
+MAG->STS: **[ITI-40]** Get X-User Assertion
+STS-->MAG: Returns the XUA
+
+
+group OAuth/IUA flow
+  MAG--[#red]>WebView: **Step 2**\nRedirect to IUA callback URL\nWith the code
+  deactivate MAG
+  App<--WebView: Close webview
+  note right
+    The app can monitor the webview URL, or use
+    deep-linking to detect this specific redirect,
+    extract the code and close the webview
+  end note
+  deactivate WebView
+
+  App-[#red]>MAG: **Step 3**\n**[ITI-71]** POST /token\nwith the code
+  MAG-->App: access_token is the XUA
+end
+@enduml

docs/integration-primary-system.md

@@ -13,8 +13,13 @@ For HTTP GET requests, there is usually an equivalent HTTP POST request that sho
 
 ## Authentication
 
+![Sequence diagram for authentication](assets/auth.png)
+
+The sequence diagram shows the currently implemented authentication flow.
+
 You should integrate one of the supported IDPs in your application.
-The SAML flow is the only one currently supported.
+The OAuth/IUA flow is supported for clients, the SAML flow is the only one implemented between the 
+MobileAccessGateway and the IDP.
 
 Once you get the IDP SAML assertion, you can trade it for the community SAML assertion, which binds your IDP
 identification to a specific patient and a purpose of use.

docs/snippets/http_iti65.txt

@@ -198,7 +198,8 @@ Content-Type: application/fhir+json;charset=UTF-8
               "contentType": "application/pdf",
               "creation": "2011-11-29T11:00:00+01:00",
               "language": "de-CH",
-              "url": "urn:uuid:59f3a738-11c1-4a0e-a89b-c4552d0fe9a7"
+              "url": "urn:uuid:59f3a738-11c1-4a0e-a89b-c4552d0fe9a7",
+              "title": "Document example title"
             },
             "format": {
               "code": "urn:che:epr:EPR_Unstructured_Document",