Toggle document index

Creating and installing your app

Creating an app Installing an app
  1. Create an account at https://developer.talentappstore.com, then create a developer.
  2. Now define your app, and the tenant APIs (API calls between apps) that it produces and consumes.
  3. If your app has SSO-protected web pages, also specify your app's principal type (user or candidate).
  4. Write your code, start up your server and make it available on the internet, then point to it via your app's back end server.
  5. For custom integrations and special use cases, you can also define your own tenant APIs, and use them in your apps.
  1. Create an account at https://www.talentappstore.com, then create a tenant.
  2. Install identity apps as required (extra ways for users or candidates to sign in).
  3. Ask the developer for an install token for their app, then enter the token to install the app.

Big picture



Coding your app - producing and consuming APIs

TAS supports two types of API - core and tenant. Mostly, writing an app involves using tenant APIs, with core APIs handled by the tazzy network proxy working on your app's behalf.

Tenant APIs are the familiar, business-oriented APIs seen in HR platforms. For example, a career site app might call GET /jobs to get a list of open jobs (maybe from the Applicant Tracking System). Tenant APIs have some additional concepts:

  • Source of truth
    • true - the API is only produced by a single app, e.g. GET /jobs
    • false - many apps can produce the API (i.e. event model), e.g. POST /applications/views/at/onboard/now
  • On behalf - a signed in user's identity is required to consume the API, e.g. POST /candidates/me

Core APIs are housekeeping APIs that make tenant APIs possible. For example the TAS core will make a core API call into your app whenever a tenant installs it.

Important: Your app must always check that the incoming tazzy-secret request header on all incoming traffic matches your app's secret key. A failed match may indicate someone is trying to hack your app.

Producing APIs Consuming APIs
Prefix Back end server (tazzy tab on your app)
e.g. https://yourapp.com:8080
https://<yourapp>tazzy.io
Authentication Check that the incoming tazzy-secret request header matches your app's secret key Attach tazzy-secret request header with your app's secret key
Core APIs
You don't need to declare the core APIs your app produces and consumes
/tas/core<api>

e.g. POST /tenants --> https://yourapp.com:8080/tas/core/tenants
/core<api>

e.g. GET /tenants/{tenant} --> https://yourapp.tazzy.io/core/tenants/{tenant}
Tenant APIs
(SoT == true)
Remember to declare all tenant APIs your app produces and consumes
/t/{tenant}/devs/{developer}<api>

e.g. GET /jobs --> https://yourapp.com:8080/t/acme/devs/tas/jobs
/t/{tenant}/devs/{developer}<api>

e.g. GET /jobs --> https://yourapp.tazzy.io/t/acme/devs/tas/jobs
Tenant APIs
(SoT == false)
/t/{tenant}/devs/{developer}<api>

e.g. GET /appStatus --> https://yourapp.com:8080/t/acme/devs/tas/appStatus
/t/{tenant}/apps/{app}/devs/{developer}<api>

e.g. GET /appStatus --> https://yourapp.tazzy.io/t/acme/apps/someapp/devs/tas/appStatus
Tenant APIs
(on behalf)
As above, but your app also receives the tazzy-saml request header. As above, and:
  • From within an SSO-protected web page: Set the outgoing tazzy-saml request header from the same incoming header.
  • While producing an on-behalf API: Set the outgoing Authorization request header from the same incoming header.

Coding your app - SSO

To protect web resources (e.g. pages) in your app with the customer's SSO (i.e. so that only authorized users or candidates can see them):

  1. Give your app a principal type (user or candidate)
  2. Put your pages at an endpoint like /t/{tenant}/, e.g. /t/{tenant}/index.html
  3. Now your page is available at https://yourapp.communityapps.talentappstore.com/t/{tenant}/...
  4. Remember to lock down access to the page from your own domain (if publicly visible), or visitors will be able to bypass SSO!

Add sign out support:

  1. Provide a sign out link that leads to /t/{tenant}/saml/logout.
  2. Add a "signed out" page at /t/{tenant}/tas/logout (signing out will redirect user to here).

Choose a suitable protection level for each page in your app.

Visible to tazzy-saml request header Example
Secured Signed in visitors only Always present url: /t/acme/index.html
Whitelisted Anyone Present if the user has recently visited a secured page. Useful for e.g. career site pages that are visible to anyone, but show extra information to signed in candidates. url: /t/acme/index.html
whitelist: /index.html
Anonymous Anyone Not present. url: /index.html
url: /static/code.js
url: /tenants/acme/index.html

Whitelisting syntax

Enter your whitelisting rules against your app in the developer site, using the following rules:

  • ? matches one character
  • matches zero or more characters
  • ** matches zero or more directories in a path

Examples:

  • /index.html - matches /t/{tenant}/index.html only
  • /public/* - matches all resources in the /t/{tenant}/public directory
  • /public/*.jsp - matches all .jsp files in the /t/{tenant}/public directory
  • /public/**/*.jsp - matches all .jsp files in the /t/{tenant}/public directory or any subdirectory thereof
  • /public/t?st.jsp - matches /t/{tenant}/public/test.jsp but also /t/{tenant}/public/tast.jsp or /t/{tenant}/public/txst.jsp
  • / - matches the home page, e.g. /t/{tenant}
  • /**/* - matches everything under /t/{tenant} (negates SSO entirely, so not useful)

Accessing details of signed in user

When inside an SSO-protected web page, the tazzy-saml header is present (see above).

When producing an on-behalf API:

  1. Parse the Authorization header, which will look like "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOnsic2FtbEtleSI6IjEyMzQifSwiY29ucyI6eyJjYSI6ImNvbnN1bWluZ2FwcCJ9fQ.Trb1qXNcn1ytWxXLpHFufK2DxdNRWyBDYMb2mQHCrwc", where the content after Bearer is a jwt
  2. From this extract the body (between dots - in the example above, eyJzdWIiOnsic2FtbEtleSI6IjEyMzQifSwiY29ucyI6eyJjYSI6ImNvbnN1bWluZ2FwcCJ9fQ)
  3. There is no real need to check the signature, since this traffic came in from tazzy and can be trusted.
  4. Convert the body from base 64, then parse it - it will be in this form.
  5. Finally, access the .sub.samlKey property of that object. This is the tazzy-saml value that you need.

GET /core/tenants/assertions/byKey/tazzy-saml/json

Response:
{
    "nameID": "frank@ibm.com",
    "entityID": "some other SAML info",
    "tas.personal.givenName": "Fred",
    "tas.personal.familyName": "Bloggs",
    "tas.personal.email": "fredbloggs@gmail.com",
    "tas.roles": [
        "internal"
    ]
}