Cylindo allows third-party clients to authenticate their users on Cylindo’s behalf, using a standard OpenID Connect authentication flow. Cylindo then acts as an OIDC Provider and expose a number of user resources to the client.

As of now, the only supported authentication flow is the Authorization code flow with PKCE (Proof Key for Code Exchange). This flow is intended for third-party public clients (such as an SPA).

Authorization code flow with PKCE

Flow schema

Integration example

An integration example with a react SPA can be found here (its code can be found there). All the actual authentication flow code is located in this file, in the methods authorize and exchangeCode.

The integration example uses the openid-client library.

Endpoints documentation

The OIDC issuer is https://app.cylindo.com/api/rest/services/oidc. All OIDC endpoints are subroutes of this URL.

GET /authorize endpoint

This endpoint serves the authorization step of the authentication (see OAuth’s documentation). This endpoint is intended to be navigated to directly from a browser, by a redirection from the authorized client.

Query parameters

Responses

Redirected location

As long as the redirect_uri query parameter is valid, the /authorize endpoint will redirect to it.

If the authorization is successful, the redirected location will contain the following query parameters:

If the authorization failed, the redirected location will contain the following query parameters:

Example cURL

 curl -H 'referer: https://client-app.com' \
   'https://app.cylindo.com/api/rest/services/oidc/authorize?redirect_uri=https%3A%2F%2Fclient-app.com%2Fredirect&scope=openid+email&state=EatlqjKZ&nonce=n3UdyX2s&code_challenge=xLO0yqyWUBp_EZxnw23V0JNFM3TkfRvB9WF-7ZwUJCY&code_challenge_method=S256&client_id=I2r6wGHFOlvptyUOLhD8cR57&response_type=code'

POST /token endpoint

This endpoint serves the authentication step of the flow (see OAuth’s documentation). This endpoint is intended to be requested directly from the public client itself (in this case, an SPA).

The POST /token request must have its parameter URI-encoded in its body, and its Content-Type must be application/x-www-form-urlencoded.

Body parameters

Responses

Example cURL

 curl 'https://app.cylindo.com/api/rest/services/oidc/token' \
   -H 'content-type: application/x-www-form-urlencoded;charset=UTF-8' \
   -H 'origin: https://client-app.com' \
   --data-raw 'redirect_uri=https%3A%2F%2Fclient-app.com%2Fredirect&code=eyJh...F7Pw&code_verifier=XDY-0Oxq1V0S2IqwbZwPNiiQt2xEMO7BvBCjZbvkT38&grant_type=authorization_code&client_id=I2r6wGHFOlvptyUOLhD8cR57'

Available scopes

Token object

JSON Errors

Error codes

Cylindo public key

The RS256 public key can be found in a JWK format here. We recommend fetching it through jose's createRemoteJWKSet method, since it comes with cache handling.