TAS core outgoing (TAS -> app) API documentation version v1
http://talentappstore.com/v1
/tenants
Called by TAS to inform your app that a new tenant has arrived (i.e. has clicked install on the app). The app can assume the tenant has status of "halted".
Your app can perform internal housekeeping, e.g. inserting the new tenant into its customers table. Ideally your app should wait for the start event (incoming call to your /tenants/{tenant}/starts endpoint) before consuming any tenant APIs.
See reboots under /tenants for more details.
A tenant is a customer within the multi-tenanted environment of Talent App Store. Currently all core API calls that your app makes to TAS are within the context of a single tenant.
Called by TAS to inform your app that an existing tenant has been deleted (i.e. has clicked uninstall on your app). Your app can assume the tenant has status "halted".
Your app has now been permanently disconnected by the tenant, and should make no more tenant API calls or core API calls on behalf of the tenant, and should perform or schedule its own cleanup, e.g. deleting tenant data. If this cleanup is long-running, you should handle a case where the tenant immediately reinstalls your app, and ensure the cleanup from the earlier install(s) can continue.
See reboots under /tenants for more details.
Called by TAS to request your app (for a specific tenant) to immediately stop any chains of tenant API calls that it "owns", i.e. has started.
For example if your app includes a daemon, it should shut down the daemon or at least stop it from consuming tenant APIs, and if it includes a UI, it should log out the user and not allow the UI to make any tenant API calls.
Your app should complete the stopping process and return 200 within a few seconds.
After this, your app should continue producing tenant APIs, and, in response to incoming tenant APIs, consuming tenant APIs on other apps - it just should not initiate new tenant API activity.
See reboots under /tenants for more details.
Called by TAS to request your app to (for a specific tenant)
- stop producing or consuming tenant APIs
- stop consuming core APIs
- stop accepting logins
Your app should immediately (before responding) stop making tenant API calls, then respond with 200.
After this, until your app receives the init call, it should consume no tenant APIs, and only these core APIs:
- GET /tenants/{tenant}/status
See reboots under /tenants for more details.
Called by TAS to notify your app that it is being started up as part of a reboot, and that it can now start making core API calls.
Your app should perform normal init processing (as below), and then return 200 as soon as possible.
- apps that consume APIs should discard any cached OAuth tokens where the consumer sgen does not match the tenant's new sgen
- apps that produce APIs should discard any cached OAuth tokens (i.e. cached to avoid re-checking) where the producer sgen does not match the tenant's new sgen
After returning 200, your app should start producing tenant API calls immediately. However it should not consume any tenant APIs, except in response to an incoming tenant API call (i.e. your app may take part in, but should not initiate, chains of tenant API calls).
See reboots under /tenants for more details.
Called by TAS to notify your app that it is being started up as part of a reboot, and that it can now start making tenant API calls.
Your app should return 200 as soon as possible.
After returning 200, your app can start consuming tenant API calls as normal.
See reboots under /tenants for more details.
Only called on apps tagged with storeFront.
Called by TAS to ask for the main page of your storeFront app. TAS calls this on your app whenever the tenant clicks to uninstall a storeFront app, while using that same app.
When this happens, the browser needs to be redirected to one of the remaining (or new) storeFronts main pages. If there are multiple storeFronts remaining, TAS will pick one at random.
The main page is normally the first page a user sees after logging in, typically displaying the apps hero list.
the principal type that this login is for
Called by TAS to tell your assertionDecorator app about someone logging in. The request body contains the original SAML assertion. Your response contains an array of roles that should be added to the SAML assertion before it reaches the app, or a 403 error to prevent login altogether (TAS will wait until all assertionDecorators have responded with 200 before it passes the login through to the web app).
For example, if the response to the API is 200, with body of:
["internal", "grade2"]
..then the SAML assertion will have the following attributes added:
- tas.roles.internal
- tas.roles.grade2
The other way a role can be set in the SAML assertion is directly by the IdP - so assertion decoration is a way for an app to achieve the same effect.
TAS will only call this API on apps that have been marked in the developer site as being assertionDecorators for the given principal type.
The SAML assertion provided in the request is the original one - i.e. prior to any roles added to the assertion as a result of another session decorator returning 200.
A typical assertion decorator might be a legacy ATS system. Example: an alumni member arrives to log into the alumni portal, and authenticates via Facebook, thus proving their email address. During the login, the ATS's assertion decorator endpoint is called. The ATS looks up the person in its database, and injects the role of "alumni". Login continues, and the SAML assertion, now containing the alumni role, reaches the alumni portal. The portal (which has no users table of its own), can now examine the incoming SAML assertion to decide whether to allow access. It might also auto-provision a row in its own database at the same time.
Assertion decoration might seem like a place to do auto-provisioning, but it's not ideal. Firstly, every assertion decoration app gets called no matter which app the user is logging into. But there might be no reason for, say, the learning system to create a row for someone just because they logged into the performance management system. Second, if there multiple assertion decorators, then some other subsequent one might return 403 to cause the entire login to fail. Now the user is unable to log in, but a record has been created for them. Instead, auto-provisioning for an app should normally be done inside that app itself upon successful login.
See Injecting role attributes for more details.
Some tenants may have legacy apps installed (e.g. an ATS) that have their own tables holding user login details (email, password) and hence can act as a "password manager". The TAS core SSO system can then delegate account activities (like validating their password) to the app.
the principal type
TAS core calls this to ask the tenant's installed password manager whether the principal's email exists.
TAS core calls this to ask the tenant's installed password manager to verify the principal's email/password combination (e.g. is this a valid login). All fields in the request except for email and password will be ignored.
The response will not include the password.
TAS core calls this to ask the tenant's installed password manager to create a new account with the given email and password.
Any fields other than the email and password should be ignored.
TAS core calls this to ask the tenant's installed password manager to replace the principal's existing password with the provided value.
All fields in the request except for the email and password will be ignored.
TAS core calls this to ask the tenant's installed password manager whether it allows account creation, and if so, whether there are any t&c's that the user must agree to first.