2. OpenID connect flow

Step by step detailed integration instruction and code examples you can find in the Integration section.

OpenID authorization flow

Cyberus Key implements the OpenID protocol and supports OpenID’s Code Flow, which means Cyberus Key authenticates both a front and back channel.

• The Front channel, in the context of the OpenID specification, is a user application (usually a web page).
• The back channel is a server (API) related to it.
• Identity Provider (IdP) is a server which authenticates (authorizes).

The official OpenId documentation can be found here: https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth

Basically, OpenID consists of two obligatory requests:

1. Authentication Request – it authenticates (and can also authorize) a user on a front channel, returning a special Authorization Code.
2. Token Request – done by a client’s back channel; it uses an Authorization Code and client’s secret ID to authenticate the client and in the end, notifies the back channel about the login (by an HTTP redirection)

So the idea is to authenticate/authorize both the front and back channel:

The above diagram shows a typical OpenID flow (e.g. for Facebook). A user clicks the login button and then, if he/she is not already logged in, is prompted to provide credentials. If the credentials are correct, then the Authentication Request is finished with an HTTP redirection (which includes the Authorization Code) to the Client Server’s callback URL.
The only requirement of the Client Server is to call the Token Request with HTTP Basic Authentication in order to validate the client. The Client Server can do more before the Token Request, e.g. can handle a state parameter to mitigate CSRF/XSRF threats (described later).

The key components

To implement Cyberus Key, in the standard scenario, you need:

1. A client account.
   You create an account in a dashboard (during the registration process) to get a client ID (public) and secret key. The last one should be protected and be known only to your backend.
2. The back channel with a defined callback that is fired when Authentication Request ends, either with success or failure.
3. The front channel with the widget embedded or your own implementation that prepares and executes an Authentication Request.
4. Optionally, handle claims like state, nonce, at_hash.

Integration steps

1. Get client keys and other needed data
2. Integrate users with Cyberus Key users
3. Create a redirection
4. Embed  the Widget
5. Callback on the back channel

A detailed description of each step and code examples can be found in the integration section.