The Redirect Flow

Javascript / Webpack

Redirect Flow SPA

crispymtn/zai-demo-app-javascript redirect-flow-demonstrator.zaikio.com

crispymtn/zaikio-oauth_client

This gem is a mountable Rails engine that provides single sign on, Zaikio access and further Zaikio platform connectivity

Zaikio supports the web application flow based on the standard authorization code grant type (opens new window). In order to use this flow you need to create an App (which can be either public or private) in the Zaikio Hub.

After your App has been created you can use this flow to identify users that visit your App.

In order to do so, four steps are necessary:

1. Your app redirects users to the Zaikio Hub to request their identity
2. Users approve access in the Zaikio Hub and are redirected back to your App
3. Your App exchanges the grant token received through the redirect into an access token
4. Your app uses the Zaikio Hub API to query user information

Requesting a user's identity

To start the web application OAuth flow, you need to redirect users that don't have a valid session for your App to GET https://hub.zaikio.com/oauth/authorize.

Name	Description
client_id required	The client ID for your App as generated by the Zaikio Hub.
redirect_uri	The URL where users should be redirected by the Zaikio Hub after authorisation is obtained. This URL needs to exactly match one of the URLs configured during App setup in the directory, it cannot contain any additional parameters. If omitted the user will be redirected to the first URL you specified during App setup
state	You should set this parameter to a secure random string only known to your App, as a means of protection against forgery attacks (opens new window). This parameter can also contain any other arbitrary data. It will be reflected back to your App with the redirect after authorisation is obtained.
login	If provided, this email address will be suggested as the users login.
signup	If omitted or set to true, the Zaikio Hub will allow the user to create a new account during the authorisation process. If set to false, a signup is not possible.
scope	A comma-seperated list of the scopes you want authorisation for. Please read the scope guides.

Users are redirected back to your App by Zaikio

After a user has successfully logged into Zaikio and approved access for your App, Zaikio will redirect the user back to your App, based on the redirect_uri specified in step 1 or in your App configuration. The redirect call will contain the code parameter which you need to exchange for an access token in step 3. It will also contain the state parameter from the previous step. You should use the state parameter to ensure that the request originated from your App. If the state doesn't match the process must be aborted.

Exchange the grant code for an access token

The final OAuth step exchanges the grant code that you received with the redirect from step 2 into a valid API token for the Zaikio Hub. In order to perform the exchange you need to send a request to POST https://hub.zaikio.com/oauth/access_token. The following parameters must accompany the request:

Name	Required	Description
client_id	Required	The client ID for your App as generated by the Zaikio Hub.
client_secret	Required	The client secret for your App as generated by the Zaikio Hub.
code	Required	The code parameter from step 2.

Depending on the HTTP Accept header send with your request, the response will either be plain text, JSON or XML and is described below:

{
  "access_token": "749ceefd1f7909a1773501e0bc57d5b2",
  "refresh_token": "be4ae927cf49466293049c993ad911b2",
  "token_type": "bearer",
  "scope": "zaikio.person.read",
  "audiences": ["directory"],
  "expires_in": "2019-12-03T08:57:35.958Z",
  "bearer": {
    "id": "29b276b7-c0fa-4514-a5b1-c0fb4ee40fa7",
    "type": "Person"
  }
}

<?xml version="1.0" encoding="UTF-8"?>
<OAuth>
   <access_token>749ceefd1f7909a1773501e0bc57d5b2</access_token>
   <refresh_token>be4ae927cf49466293049c993ad911b2</refresh_token>
   <token_type>bearer</token_type>
   <scope>zaikio.person.read</scope>
   <audiences>directory</audiences>
   <expires_in>2019-12-03T08:57:35.958Z</expires_in>
   <bearer>
     <id>29b276b7-c0fa-4514-a5b1-c0fb4ee40fa7</id>
     <type>Person</type>
   </bearer>
</OAuth>

access_token=749ceefd1f7909a1773501e0bc57d5b2&token_type=bearer

Retrieve user information via the Zaikio Hub API

In order to retrieve information about the current user (like email address, name and organisation memberships) you need to query the Zaikio Hub V1 REST API at GET https://hub.zaikio.com/api/v1/person. Please note that contrary to the token exchange response, the API only responds with JSON. To authenticate against the API the Authorization header must be set to

Bearer <your API token>

where <your API token> must be replaced with the token you obtained in step 3.

An example call to this endpoint might look like this:

curl --request GET \
     --url https://hub.zaikio.com/api/v1/person \
     --header 'Authorization: Bearer 749ceefd1f7909a1773501e0bc57d5b2'

PKCE required for non-oauth-confidential

OAuth 2.0 public clients are susceptible to the authorization code interception attack.

To prevent these attacks we support PKCE (Proof Key for Code Exchange) as described in RFC7636 (opens new window).

WARNING

For applications that are not "oauth_confidential" (like mobile apps and SPAs) the usage of PKCE is obligated!

How include PKCE in the OAuth flow:

1. Generate the code_verifier Before starting the authorization code grant, a random string called code_verifier is generated using the characters: [A-Z], [a-z], [0-9], "-", ".", "_" and "~", with a minimum length of 43 characters and a maximum length of 128 characters. See RFC7636 4.1 (opens new window) for details.

function base64URLEncode(str) {
  return str
    .toString("base64")
    .replace(/\+/g, "-")
    .replace(/\//g, "_")
    .replace(/=/g, "");
}
const verifier = base64URLEncode(crypto.randomBytes(32));

2. Generate the code_challenge In addition to the code_verifier a code_challenge is created. The code_challenge can be based on two different methods: a) With code_challenge_method "plain" the code_challenge is exactly the same as the code_verifier. b) With code_challenge_method "S256" the code_challenge is the SHA256 Hash value of the code_verifier - url safe base64 encoded (without trailing "=" see RFC 7636 Appendix A (opens new window)).

We strongly recommend to only use S256 as method!

function sha256(buffer) {
  return crypto
    .createHash("sha256")
    .update(buffer)
    .digest();
}

const challenge = base64URLEncode(sha256(verifier));

3. Adjust the authorization grant request Add the parameters code_challenge and code_challenge_method to the authorization grant request, depending on which was used in the previous steps. The endpoint will return an error in case the code_challenge_method is not present or is a not valid one. After a successful authorization the user will be redirected to your redirect_uri as usual and will contain the code parameter.

4. Adjust the access token request When exchanging the code for an access token, add the parameter code_verifier to the request. If the provided code_verifier matches the previously used code_challenge (with the used method) the endpoint will return access tokens as usual. If you originally used PKCE on the authorization grant you MUST submit a valid code_verifier for the access token exchange. Otherwise the endpoint will return an error.