Org Web Adapter

Editing pages/15five_partnership_sso_design_document.org

:PROPERTIES:
:ID:       17f69fbb-eb6c-4da4-827a-70acc84484f5
:END:
#+title: 15Five Partnership SSO Design Document

- tags :: [[id:62688cd1-edb1-46b7-a244-fe065ef486c5][Design Document]] [[id:b08ac197-337b-4392-84d5-98eaead61400][15Five]] [[id:d2fc1f50-b020-4f19-a882-2434f80ca378][Partnership Squad]]

* Purpose
An integral part of our go-to-market strategy with partnerships is being able to easily define the needs for an effective partnership with other software providers. The purpose of this document is to outline at a general level the engineering preferences for implementing what is frequently called Single Sign-On or SSO between the 15Five application and our partner applications.
* Design
** Within 15Five
*** Enabling the application
Customer enables an "app" in the marketplace, this takes them to a configuration page where they enter the API of the partner application.
*** Initial provisioning
Once the app is enabled, an initial provisioning occurs which creates accounts for 15Five users in the new service. This provisioning is idepotent so that if there are already users in the partner app with the same email as a 15Five user, a new account will not be created.
*** Nightly cron job
After the initial provisioning, the application is considered "active" and a periodical cron job will be scheduled with will add any new users found in 15Five. It's not clear yet whether this script should handle deactivating accounts in the partner app if they are no longer found in 15Five.
** Within Partner App
*** New user invites or activation
Depending on the partner's API, new users could either be automatically activated, or an invitation sent. If the partner does not send emails, provisoning script should handle sending email notification to users of new integration. We could also always send a 15Five email to each user informing them of their new account.
*** Login flow
User login will depend on how the customer has configured 15Five and the partner application. Rather than provide an identity provider ourselves, 15Five will depend on the customer having configured their account with the partner application to best suit their needs. If they use a common IdP like Okta or Azure, they can enable both 15Five and the partner app to use the same IdP, allowing newly invited users

While there may in the future be more strategic integrations where 15Five may want to actually be the IdP, the fastest way to market is to expect partner applications to be configured to use the same IdP as the customer's 15Five account.

In cases where customers do not have an IdP configured, users logging into the partner app will simply fallback to creating a password for this service to go along with the email address they use in 15Five.
* Open questions
1. How do we surface the need to pre-configure partner apps with an IdP (Okta, Azure, etc)?
2. Should we worry about deactivating users in the partner app when a user is deactivated in 15Five?
3. Sometimes integrations will be both push and pull. How should those integrations look?