-
Notifications
You must be signed in to change notification settings - Fork 96
Integration: Server to Server
"Server to Server" (S2S) integration provides the ability for 3rd party applications to invoke actions on an OAE tenant in such a manner that they are not strictly scoped to the access of a particular user and are not necessarily performed on behalf of some particular user, but rather on behalf of an application.
The goals of a server-to-server integration strategy are the following:
- Allow a Global Administrator the ability to provide a set of known Trusted Applications for the system
- Allow a Tenant Administrator to enable access for Trusted Applications and also define their own ad-hoc applications to perform actions and access data from OAE
- Provide the ability for 3rd party systems to securely authenticate themselves with OAE to perform those actions
- Provide a framework in which the actions and data 3rd party applications are able to gain access to are controllable by administrators
S2S integration will be implemented using OAuth v2. 2LO is used to enable S2S integration with external services without requiring prior user consent, but rather can be given by the consent of an Administrator.
- Administrator creates an entity ("Application") with the administration panel with a secret key
- The Administrator selects the default user on whose behalf to perform an action
- The Administrator selects the subset of actions it will allow the Application to perform. For example: a. "Post to users activity feeds" b. "Impersonate a User" (From here, possible granular user actions are delegated to the 3LO functionality as though the application was granted access by the user in a 3-Legged-OAuth workflow)
- The secret key is provided by the Administrator to the Application with which it can authenticate requests
- At any time, the Administrator can remove the Application / change the key to revoke access for that key
In contrast, the more traditional OAuth workflow (3-Legged-OAuth / "3LO") implies performing actions on behalf of a user, and accessing data from the view-point of the user who provided consent. This workflow typically involves redirecting the user to the application, having them authenticate themself, and providing a list of actions to which the 3rd party service wishes to have access (e.g., "View your library", "Access to your user profile", "View the list of people you follow").
The technical approach of implementing 2LO for OAE should keep into consideration the parallels for 3LO. That is to say that while the 3LO workflow may be out-scoped to another unit of work, the authentication and authorization of granular scoped permissions should be implemented in such a way that the 3LO workflow can be built on top of the authorization scoping of the 2LO work.
Providing the ability for service providers (Global Administrator) to define trusted applications allows tenant administrators to enable access to external applications in such a way that the trust key is managed by a single source. It is possible that as a future requirement, the selection of actions that are possible to be granted are different when added as a "Trusted Application" by the global administrator, versus if they are added as an ad-hoc "Application" integration by a Tenant Administrator.
To create a Trusted Application, a Global Administrator will access the global administration panel, fill out a form that includes the application name. The Tenant Administrator will be able to "Generate" a trust key for the application, then provide that trust key to the 3rd party service to use for authentication. The Global Administrator will then be able to select the actions they wish for the Trusted Application to be able to perform.
The Tenant Administrator will be able to see the name of the Trusted Application in their administration panel, and they will be able to see the actions that the Trusted Application have been granted. However, they will not see the trust key that was configured by the Global Administrator. The Tenant Administrator will be able to enable or disable the Trusted Application integration for their tenant.
Once a 3rd party service receives a trusted key from an OAE Administrator, it may be used as the "Bearer Token" when authenticating a request to OAE as specified in the OAuth v2 specification. That is, when issuing a request as the Application to OAE, the following Authorization header should be provided:
Authorization: Bearer <base64_encoded_token>
By default, a request in OAE that has been authenticated to an application will be treated as anonymous, or the designated user that was specified -- this may be a Global Administrator, or a Tenant Administrator of a designated tenant, however their actions will still be scoped by that selected for the Application by the Administrator. If the impersonation option is enabled for the Trusted Application, it should be possible for the 3rd party Application to provide an additional header that identifies a user that they wish to impersonate:
X-OAE-Impersonate: <base64_encoded_internal_userid>
When using server-to-server integration, it becomes an issue for an external application to be able to know a user's OAE internal ID. In 3LO this is not an issue as the authentication workflow produces a unique bearer token that is mapped directly to the integrating user.
There will need to be a separate OAuth-enabled application endpoint that allows user ID lookup based on certain known attributes of a user. Depending on the sensitivity of information that can be exposed VIA reverse lookup using such an endpoint in combination with impersonation, it is important to explore the implications of user data that can potentially be exposed to 3rd party systems. These implications should be explored in context of privacy policies that are outlined in identity providers that may be used to achieve reliable user mappings.
- Is it considered fair use that, if an external "Trusted Application" knows some shibboleth metadata attribute of a user, they should be able to look up the internal identifier in OAE? What about ad-hoc "Application"s defined by Tenant Administrators?
- What about other user information such as email address, some external synchronized profile information, etc...