OpenID connect
and security
| Name | Description |
| AuthorizationEndpoint | URI to get the authorization code |
| RedirectURL | URI on which the authorization code is restricted |
| AccessTokenEndpoint | URI get the access token |
| ClientID | A unique ID that identifies each participant to OpenID Connect |
| ClientSecret | A secret related to ClientID |
| Scope | Specifies what access privileges are being requested |
The authentication process that is used here is the Authorization Code Flow.
At first, the mobile application gets an authorization code. Then the backend uses this authorization code to get an access token. Hereafter is a scheme representing this process.
Note : The authorization code is only valid during a short time (i.e. 10 minutes). So the application must send it to the backend as soon as possible. The backend must use it immediately after reception to get the access token and should not persist it..
This phase is made by the mobile application. It requires an input from the customer: its credentials for the Hager system. The AuthorizationEndpoint, the RedirectURL, the ClientID and the Scope are used to reach a widget (hosted by Hager) that needs to be displayed to the customer (i.e. through a WebView). Therefore those information need to be embedded into the mobile application.
When the customer validates his credentials in the widget, it induces an URL redirection (HTTP code 302) that must be intercepted by the application. This URL is the RedirectURL and contains the authorization code as an URL parameter named code.
It returns a JSON object which contains the following parameters:
Then the authorization code must be sent to the backend, using the partner’s communication channel. So that the backend will be able to get the tokens.
Tokens
This phase is made by the backend.
The AccessTokenEndpoint, the RedirectUrl, the ClientID and the ClientSecret are required. When using the AccessTokenEndpoint, it is possible to send the authorization code in order to get :
• An access token
• An access token
• An ID token
• An expiration date for the access token
Note : The refresh token expires after a long period (i.e. 30 days), because it is only exchanged between the partner’s backend and the Hager Authentication server.
Implementation
On the mobile application side, the only steps are:
• Get the authorization code
• Send the authorization code to the backend
Even if there exist several libraries that implement the Authorization Code Flow of OpenID Connect, the authorization code can simply be gotten by opening a WebView and loading a dedicated URL. The WebView will display a web form in which the user has to enter his credentials and validate. Once validated (and if the credentials are correct), the WebView must intercept an URL redirection that contains a parameter named code. The value of this parameter is the authorization code.
The URL of the web form is constituted as follow :
<AuthorizationEndpoint>?
redirect_uri=<RedirectURL>&client_id=<ClientID>&response_type=code&state=astring&scope=<Scope>
Note : The parts in bold between <> must be replaced by their values (without <>) and url encoded. The value of the query parameter named state just needs to be a url encoded string, whatever its value. This mechanism can at least be implemented in IOS and Android using respectively didReceiveServerRedirectForProvisionalNavigation and shouldOverrideUrlLoading (see chapter 0)
The backend is responsible to store the tokens and to refresh the access token when it expires, using the refresh token.
Backend
When the backend receives an authorization code (i.e. associated to a customer), it must persist it and use it to get an access token and a refresh token (at once).
There again are several libraries that allow to do that, but it can be done manually with a POST HTTP request to the AccessTokenEndpoint, using the ClientID and the ClientSecret as, respectively, the login and password of a Basic Authentication, and with the following parameters:
| Parameter | Value |
| grant_type | authorization_code |
| code | The authorization code sent by the mobile application |
| redirect_uri | The value of RedictURL |
It returns a JSON object which contains the following parameters:
| Parameter | Description |
| access_token | [String] the value of the access token |
|
expires_in |
[int] validity period (in second) of the access token |
| id_token | [String] the value of the identity token |
| refresh_token | [String] the value of refresh token |
| token_type | [String] the type of token |
The access token must be set as the Bearer Authentication value for every use of the Hager Open API.
If the access token has to be used outside of its validity period, a new access token must be requested using the refresh token. To do so, send a POST HTTP request to the AccessTokenEndpoint, using the ClientID and the ClientSecret as, respectively, the login and password of a Basic Authentication, with the following parameters:
| Parameter | Value |
| grant_type | refresh_token |
| refresh_token | The value of the current refresh token |
It returns the same JSON object than the former request, with a new access token and a new refresh token. The new tokens must then replace the former ones.
Note : Take care to refresh the tokens before the end of the refresh token validity period (i.e. 30 days), or a new authorization code will be needed.
