Creating and installing your app

Creating an app	Installing 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.	Note: The purpose of this exercise is to help you understand what the customer journey would look like. Create an account at https://www.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.

Creating an app

Installing 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.

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

Create an account at https://www.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

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

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.

	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:

Parse the Authorization header, which will look like "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOnsic2FtbEtleSI6IjEyMzQifSwiY29ucyI6eyJjYSI6ImNvbnN1bWluZ2FwcCJ9fQ.Trb1qXNcn1ytWxXLpHFufK2DxdNRWyBDYMb2mQHCrwc", where the content after Bearer is a jwt
From this extract the body (between dots - in the example above, eyJzdWIiOnsic2FtbEtleSI6IjEyMzQifSwiY29ucyI6eyJjYSI6ImNvbnN1bWluZ2FwcCJ9fQ)
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

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"
    ]
}