Getting started

This article describes the first steps to be taken when developing an app with Talent App Store.

Creating and installing your app

The first step is to create an app associated to your developer account and install your app in your tenant.

Creating an app

Create an account at https://developer.talentappstore.com, then create a developer.
Now define your app, and the tenant APIs (API calls between apps) that it produces and consumes.
If your app has SSO-protected web pages, also specify your app's principal type (user or candidate).
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.
For custom integrations and special use cases, you can also define your own tenant APIs, and use them in your apps.

Installing an app

The purpose of this exercise is to help you understand what the customer journey would look like.

Create an account at marketplace.talentappstore.com, then create a tenant.
Install identity apps as required (extra ways for users or candidates to sign in).
Ask the developer for an install token for their app, then enter the token to install the app.

Big Picture

Diagram describing the difference between Tenant and Core APIs

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.

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

Parameter

Description

Prefix

Back end server (tazzy tab on your app)
e.g. https://yourapp.com:8080

Authentication

Check that the incoming tazzy-secret request header matches 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

Tenant APIs

Remember to declare all tenant APIs your app produces and consumes

SoT == TRUE

/t/{tenant}/devs/{developer}<api>

e.g. GET /jobs --> https://yourapp.com:8080/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

Tenant APIs

on behalf

As above, but your app also receives the tazzy-saml request header.

Consuming APIs

Parameter

Description

Prefix

https://<yourapp>tazzy.io

Authentication

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

/core<api>

e.g. GET /tenants/{tenant} --> https://yourapp.tazzy.io/core/tenants/{tenant}

Tenant APIs

Remember to declare all tenant APIs your app produces and consumes

SoT == TRUE

/t/{tenant}/devs/{developer}<api>

e.g. GET /jobs --> https://yourapp.tazzy.io/t/acme/devs/tas/jobs

yourapp --> your apps shortcode.
{tenant} --> customers tenant shortcode.
{developer} --> the shortcode for the developer that has created the API you wish to use.
<api> --> the API you wish to use e.g. /jobs.

Tenant APIs

SoT == FALSE

/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, 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.

SSO - Single Sign On

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):

Give your app a principal type (user or candidate)
Put your pages at an endpoint like /t/{tenant}/, e.g. /t/{tenant}/index.html
Now your page is available at https://yourapp.communityapps.talentappstore.com/t/{tenant}/...

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:

Provide a sign out link that leads to /t/{tenant}/saml/logout.
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.

Level

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:

Parse the Authorization header, which will look like "Bearer <header>.<payload>.<signature>", where the content after Bearer is a jwt
From this, extract the payload (between dots)
There is no real need to check the signature, since this traffic came in from tazzy and can be trusted
Convert the body from base 64, then parse it - it will be in this form.
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

-- CODE language-json --
{
"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"
]
}