Obtaining a Cantook Cloud Identifier

The association between the bookstore’s customer and his Cantook Cloud account is done by the bookstore acquiring a Cantook Cloud Identifier (a string unique to each participating customer).

The following three scenarios are possible:

1. The bookstore site manages its own account system, but it will delegate its authentication to Cantook Cloud, in which case it will obtain the Cantook Cloud Identifier at the time of the user’s login.

2. The bookstore already manages its own accounts and its own authentication system, in which case it must obtain a Cantook Cloud Identifier for each customer wishing to access Cantook Cloud. The bookstore must store this identifier in its Database alongside its existing customer’s information.

3. The bookstore has no concept of user accounts (the users do not create accounts to buy books). In that case, the bookstore must redirect the user to Cantook Cloud for authentication and include the Hub purchase information in a particular field,

Note

All cases use the same authentication flow but the bookstore site uses them differently.

Implicit Flow with Form Post

Authentication in Cantook Cloud is based on the standard Implicit Flow With Form Post with Cantook Cloud acting as the identity provider. This section describes the flow within the context of the previously described scenarios.

First scenario: bookstore delegates authentication to Cantook Cloud

1. The user visits the bookstore site. Before buying any book, he/she must click on a button “login / register”.

2. When the user clicks The bookstore site redirects the user to a login page on Cantook Cloud, passing the following parameters in the URL (as a query string):

   • client_id: An identifier for the bookstore (provided by De Marque)
   • response_mode: “form_post”
   • response_type: “id_token”
   • redirect_uri: The URL (on the bookstore site) to which the user should be redirected after authentication. This URL must be added to a pre-authorized list communicated beforehand to De Marque. This URL must point to an end-point capable of handling the POST request described in step 3.
   • state (OPTIONAL): The content of this parameter will be returned in full and without modification at the end of the login process. It is therefore used by the integrator to retain relevant information present at the time control was passed to Cantook Cloud (for example, the integrator can include a URL to redirect the user so that they return to the specific state they were in when they left the site).

3. The user authenticates herself.

4. Once authenticated, the user is redirected to the bookstore site (specifically, to the redirect_uri) with a POST request containing the following two fields (application/x-www-form-urlencoded):

   • id_token, which holds the OpenID Connect ID Token. This token contains the Cantook Cloud Identifier of the customer, in its sub field.
   • state, which contains the string that had been passed by the bookstore site to the Cantook Cloud authorization page, if any.

5. The bookstore creates the account of the user, if the account does not yet exist, using the Cantook Cloud Identifier as its identifier.

Second scenario: bookstore has its own authentication system

1. The user visits the bookstore site. The user is already logged in the bookstore. The user is shown a message inviting him to join Cantook Cloud

2. When the user clicks The bookstore site redirects the user to a login page on Cantook Cloud, passing the following parameters in the URL (as a query string):

   • client_id: An identifier for the bookstore (provided by De Marque)
   • response_mode: “form_post”
   • response_type: “id_token”
   • redirect_uri: The URL (on the bookstore site) to which the user should be redirected after authentication. This URL must be added to a pre-authorized list communicated beforehand to De Marque. This URL must point to an end-point capable of handling the POST request described in step 3.
   • state (OPTIONAL): The content of this parameter will be returned in full and without modification at the end of the login process. It is therefore used by the integrator to retain relevant information present at the time control was passed to Cantook Cloud (for example, the integrator can include a URL to redirect the user so that they return to the specific state they were in when they left the site). The bookstore can also pass its own identifier of the account so that it can recover it in the next step.

3. The user authenticates himself

4. Once authenticated, the user is redirected to the bookstore site (specifically, to the redirect_uri) with a POST request containing the following two fields (application/x-www-form-urlencoded):

   • id_token, which holds the OpenID Connect ID Token. This token contains the Cantook Cloud Identifier of the customer, in its sub field.
   • state, which contains the string that had been passed by the bookstore site to the Cantook Cloud authorization page, if any.

5. The bookstore associates the Cantook Cloud Identifier to the user’s account in its DB.

Third scenario: bookstore has no accounts

We provide this flow as a template for a bookstore with no concept of user accounts, the details might vary. When the bookstore has no concept of user account, it must asks the user to complete a login flow in cantook cloud everytime he wants to add his purchases to Cantook Cloud. The bookstore site can use the state parameter to store the information it will needs to push the books to cantook cloud (for instance, the order identifier) once the user is redirected back.

1. The user visits the bookstore site and buys some books. He is presented a button to add the books he bought to cantook cloud.

2. The user clicks on the button.

3. When the user clicks The bookstore site redirects the user to a login page on Cantook Cloud, passing the following parameters in the URL (as a query string):

   • client_id: An identifier for the bookstore (provided by De Marque)
   • response_mode: “form_post”
   • response_type: “id_token”
   • redirect_uri: The URL (on the bookstore site) to which the user should be redirected after authentication. This URL must be added to a pre-authorized list communicated beforehand to De Marque. This URL must point to an end-point capable of handling the POST request described in step 3.
   • state: the bookstore passes (for example) the purchase order identifier

4. Once authenticated, the user is redirected to the bookstore site (specifically, to the redirect_uri) with a POST request containing the following two fields ( application/x-www-form-urlencoded ):

   • id_token, which holds the OpenID Connect ID Token. This token contains the Cantook Cloud Identifier of the customer, in its sub field.
   • state, which contains the purchase order identifier.

5. The bookstore can now retrieve the purchase information from Cantook Hub, and use it alongside the Cloud Cantook Identifier to push the content to Cantook Cloud, as explained in the Adding purchases to Cantook Cloud section.

ID Token

The ID Token is a JWT token that must be validated by the bookstore using the JWKS provided by De Marque (see Configurations). The issuer and audience fields MUST be verified to ensure the token can be safely used:

• issuer must be the value set by Cantook Cloud
• audience must be equal to the client_id that was provided to you.

Note

In the ID Token, the sub field contains the Cantook Cloud identifier of the user, which the bookstore site must retain and associate with the local user for interactions with the Cantook Cloud API.

Configurations

A staging environment is provided for testing purposes. The different values needed to implement the authentication flow for both staging and production environments are the following:

Configuration	Staging	Production
Authentication end point	https://cantook-cloud-auth-staging.pages.dev/login	https://id.cantook.com/login
JWKS	https://storage.googleapis.com/jwks/jwks-cantookcloud-development.json	https://storage.googleapis.com/jwks/jwks-cantookcloud.json
Token’s issuer	https://cloud-dev.cantook.com	https://cloud.cantook.com
Token’s audience	Bookstore’s client_id	Bookstore’s client_id

Note

The bookseller must provide a list of URLs on their website that will be pre-authorized as legitimate redirect URIs, for both Production and Staging environments.