# The Redirect Flow
Redirect Flow SPA
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:
- Your app redirects users to the Zaikio Hub to request their identity
- Users approve access in the Zaikio Hub and are redirected back to your App
- Your App exchanges the grant token received through the redirect into an access token
- Your app uses the Zaikio Hub API to query user information
- Integrate the Launchpad on your website
# 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
| ||The client ID for your App as generated by the Zaikio Hub.|
| ||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|
| ||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.|
| ||If provided, this email address will be suggested as the users login.|
| ||If omitted or set to |
| ||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:
|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.|
Depending on the HTTP
Accept header send with your request, the response will either be plain text, JSON or XML and is described below:
# 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>
<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).
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.
2. Generate the code_challenge
In addition to the
code_challenge is created. The
code_challenge can be based on two different methods:
code_challenge_method "plain" the
code_challenge is exactly the same as the
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!
3. Adjust the authorization grant request
Add the parameters
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
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.