![\"Clear](\"https://mootooling.blob.core.windows.net/third-party-sso-docs/ClearCookies.PNG\")
\nThis collection demonstrates the auth flows in MOO that are relevant to third parties who are integrating their application with MOO.
\nMOO implements the OAuth2 standard for authorization.
\nTo access protected MOO resources the third party application needs a valid access token. There are two distinct types of access token in MOO:
\nuser specific access tokens
\nclient specific access token
\nUser specific access tokens can only (initially) be acquired through user interaction in the browser. The third party app can use the authorization code flow and redirect the user's browser to the MOO Secure token service (STS) to request an authorization code. This code can then be exchanged for an access token (and a refresh token).
\nThe refresh token enables the app to request new user specific access tokens without requiring further user interaction.
\nUser specific access tokens are limited to requesting resources that the logged in user has access to and that the third party client has access to.
\nThe first five requests in this collection illustrate the use of user specific access tokens.
\nClient specific access tokens can be acquired directly by the third party application, and do not require a logged in user.
\nClient specific access tokens are limited to requesting resources that the third party client has access to and that support direct client access.
\nThe last two requests in this collection illustrate the use of client specific access tokens.
\nFor both client and user tokens the application must specify a comma seperated list of scopes in the call to the Authorize or Token endpoints. These scopes indicate the api access that are requested for the token. Clients can only specify scopes that they have explicitly been given access to by MOO. It is also considered best practice to only request the scopes that are required for that given token / context.
\nIf you want to test the calls using postman directly you need to do the following:
\nInstall postman
\nOpen this collection in postman
\nImportant: Turn off redirect following in postman: File - Settings - Automatically follow redirects
\nFill in the collection variables (current value):
\nClientId
\nClientSecret
\nRedirectUri
\nStsCookie (requires logging in to the MOO portal)
\nExecute the requests in the correct sequence
\n![\"Edit](\"https://mootooling.blob.core.windows.net/third-party-sso-docs/CollectionVariables.PNG\")
","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"475129","collectionId":"2b987c2e-8a5d-4f4b-bca6-adcfb51aa8f5","publishedId":"S1a7W5f2","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2019-07-01T09:04:25.000Z"},"item":[{"name":"Get code for user code flow","event":[{"listen":"test","script":{"id":"0cdf93f9-3a70-4c44-a684-b4b2efaa7004","exec":["var location = postman.getResponseHeader(\"Location\");\r","var code = location.match(/code=[^&]*/)[0].substr(5);\r","pm.globals.set(\"Code\", code);\r",""],"type":"text/javascript"}}],"id":"fadb6309-4768-4541-82b2-5edf9c08731f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"cookie","value":"","type":"text"}],"url":"https://sts.moo.nl/WebSTS/Oauth/Authorize?response_type=code&client_id=&redirect_uri=&scope=user.signin,resapi.user.self.read&state=SomeImpossibleToGuessAntiCsrfValue","description":"Redirect the user's browser to the STS Authorize endpoint to start the SSO auth flow with MOO. If the user is not yet logged in, then she is prompted to login first. If the user is already logged in then the STS automatically redirects the browser back to the calling app, using the redirect uri provided. This redirect uri needs to match the uri configured in MOO to prevent authorization codes leaking to unauthorized parties.
\nTo protect your application from CSRF logins it is considered best practice to use the state parameter in the call to the authorization endpoint (see Cross Site Request Forgery and OAuth2). The state parameter should contain some session or time limited data that is not possible to guess by an attacker who attempts to redirect an unwitting user to the authorize endpoint. This state should then be validated by the app before trading the code for an access token and logging the user in. For the test in postman this dummy value is acceptable.
\nDon't worry if the response looks like an error. A user does not normally see this html, because the browser redirects to the redirect_uri immediately.
\nstatus code: 302\nLocation header: https://moo.thirdpartyapp.nl/Account/ExternalLogOnCallback?code=5b6950cdd21e4725946d6bcc8fc777b86c50b3392d764d4ebfd1f151aae5fbb7&state=SomeImpossibleToGuessAntiCsrfValue\nFor this to work in postman you need to fool the STS into thinking that a logged in user is present. For this you need to set the value of the STS cookie variable to the correct value. The value you need is the key-value pair of the Websts cookie in the domain .moo.nl. It looks like this: \"Websts={base64 string}\". An easy way to get the value of this cookie is to use the browser devtools (i.e. in chrome). Go to the MOO portal and login with the MOO credentials you have been provided with. In dev tools go to the network tab and ensure that the log is preserved between redirects. Then go the the application tab and clear all the cookies in the v2.moo.nl domain and hit refresh.
\n\nBecause the portal user is no longer authenticated the browser is redirected to the sts Authorize endpoint. This call includes the Websts cookie, and it can be retrieved from the request headers.
\n![\"Authorize](\"https://mootooling.blob.core.windows.net/third-party-sso-docs/AuthorizeCall.PNG\")
\nThe code that the STS returns to the user's browser should be used by the web application to request an access token. The token call requires the client secret and should therefore be performed by the backend. This flow ensures that the client secret does not have to be passed to the browser. A code can be used only once to request a token, an attempt to reuse a code returns an error.
\nMOO supports a single user having different roles in different organisations within a single tenant.
\nAccess tokens are always organisation specific, and the access they provide is generally limited to the organisation context of any given resource call.
\nWhen the generic OAuth/Token endpoint is used, the organisation of the token is determined by the user's paying (= primary) organisation.
\nIf the application requires a token for a user in a different member organisation, then a call can be made to the organisation specific token endpoint: OAuth/{OrganisationKey}/Token.
\n{\n \"access_token\": \"eyJ0eXAiO...\",\n \"token_type\": \"bearer\",\n \"expires_in\": 1199,\n \"refresh_token\": \"eyJ0eX...\"\n}\nThe tokens use the jwt format and can easily be decoded, for example using jwt.io. The token signature does not have to be verified by the calling application.
\n","urlObject":{"protocol":"https","path":["WebSTS","OAuth","Token"],"host":["sts","moo","nl"],"query":[],"variable":[]}},"response":[],"_postman_id":"1bdf9165-69d5-434d-a02c-5a605a24ce3c"},{"name":"Get UserInfo","id":"01a4e9ee-1250-4b8c-9941-fca8709dd490","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{AccessToken}}"}]},"isInherited":false},"method":"GET","header":[],"url":"https://resource.moo.nl/resource/api/v1/userinfo","description":"Use the user token to request user information from the resource api. The actual fields returned depend on the fields that the client has access to, as configured in MOO.
\n{\n \"LoginName\": \"T.Hawk@test01.moo.nl\",\n \"FirstName\": \"Tony\",\n \"MiddleName\": null,\n \"LastName\": \"Hawk\",\n \"OrganisationKey\": \"65ad2c83-53cc-4e61-842f-04ae904c8417\",\n \"TenantKey\": \"55380524-4c8b-4483-81e6-f771c2afc340\",\n \"Key\": \"4e225c26-e984-4987-84ec-6929a98283c3\"\n}\nUserinfo endpoint with support for more fields via query options. The actual fields returned also depend on the fields the client has access to, as configured in MOO.
\n{\n \"Key\": \"4e225c26-e984-4987-84ec-6929a98283c3\",\n \"PayingOrganisation\": {\n \"Key\": \"fd414907-d02d-48f8-a14b-49b0357b45ac\"\n },\n \"FirstName\": \"Tony\",\n \"MiddleName\": null,\n \"LastName\": \"Hawk\"\n}\nAccess tokens have a limited lifetime. Their lifetime length is included in the access_token itself and also directly in the response from the token endpoint. When the access token has expired it is possible to get a new one from the STS without user interaction. This is done using the refresh token, that was included in the original token response. The refresh token has a much longer (or unlimited) lifetime.
\nRefresh tokens can be used only once, but the refresh token response also includes a new refresh token with which the refresh process can be initiated again.
\n{\n \"access_token\": \"eyJ0eXAiO...\",\n \"token_type\": \"bearer\",\n \"expires_in\": 1199,\n \"refresh_token\": \"eyJ0eX...\"\n}\nGet a app specific (in contrast to a user specific) access token using the OAuth client flow. Client tokens are useful for background processing.
\nThird party apps in MOO are restricted to organisation specific access.
\nIn contrast to the token post in the authorization code flow, the token post in de client flow must include the organisation key of an organisation that has granted access to the third party app.
\nIf you are executing this request in postman, then the OrganisationKey is extracted from the reponse to the \"Get more userinfo\" call. If you want to test this call without executing the user code flow, then you need to set the OrganisationKey variable by hand to an organisation key that your application has been granted access to.
\n{\n \"access_token\": \"eyJ0eXAiO...\",\n \"token_type\": \"bearer\",\n \"expires_in\": 1199\n}\nThe token uses the jwt format and can easily be decoded, for example using jwt.io. The token signature does not have to be verified by the calling application.
\n","urlObject":{"protocol":"https","path":["WebSTS","OAuth","","Token"],"host":["sts","moo","nl"],"query":[],"variable":[]}},"response":[],"_postman_id":"1f2aad9b-90c0-43be-a452-92bbe5d84dd3"},{"name":"Get organisation users","id":"5a09c468-7d31-46c7-b2d5-4485fe969208","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"{{ClientAccessToken}}"}]},"isInherited":false},"method":"GET","header":[],"url":"https://resource.moo.nl/resource/api/v1/organisations//users?select=firstname,lastname,usertype","description":"Use the client token to get all the users in an organisation. The actual fields returned depend on the fields the client has access to, as configured in MOO.
\n[\n {\n \"Key\": \"580223b4-5a38-4433-9eaa-9a68d117c9cd\",\n \"FirstName\": \"Admin\",\n \"LastName\": null,\n \"UserType\": \"OrganisationAdmin\"\n },\n ...\n]\n