Integration types

When integrating with the Salto KS APIs, you will receive a client ID and, depending on the application type you are building, a client secret, which is configured for the specific OpenID Connect flow you will use. These flows are sometimes referred to as grant types. They are not specific to the Salto KS platform, but rather an implementation of the public OpenID Connect protocol, which is also used by other systems on the internet. Libraries and frameworks that implement OpenID Connect protocol can also be used by partners integrating with the Salto KS platform.

The OpenID Foundation website has a list of different OpenID Connect implementations.

Using a client library is recommended as it handles different flows automatically and it will be updated when the OpenID Connect protocol changes for any flow. This can happen if a security vulnerability is discovered, and the protocol standards need to be modified.

Clients integrating with the Salto KS Connect API can be configured under two types of integration: Interactive and Non-Interactive.

Interactive: browser and mobile applications

The interactive integration applies to clients that are building browser-based applications, such as Single Page Applications (SPAs), as well as mobile applications. These applications have a User Interface (UI) component, through which clients interact with. In this case, clients are making use of an authorization_code flow. The authenticity of the client making the request is ensured with the client ID and the predetermined URLs that are registered in the system. Those return URLs are attached to your specific client ID and this is where the results of the requests are delivered. Only the owner of the systems on these URLs can receive the tokens.

The authorization_code flow consists of two components: a front-channel step (for example, a login page) and a back-channel step. The operation performed in the front-channel generates an authorization code, which is then exchanged in the back channel with the requested token.

Interactive clients can be either public or confidential. For both cases, the authorization_code flow is used together with a Proof Key for Code Exchange (PKCE), which is a security requirement to keep the flow secure. The difference is that for confidential clients, a client secret is also required when providing the credentials, and the client secret must be known in order for the authorization code to be turned into an access token.

The authorization_code flow happens between the client application and the Salto KS Identity Provider, and it can be broken down into the following steps:

Authorization code flow

With the access token, the client application can make a call to the KS Connect API. Furthermore, if the GET request in step 1 contains the scope offline_access, then the Identity Provider will return not only an access token, but also a refresh token in step 5.

https://identity-server-url/connect/authorize
?response_type=code
&scope=user_api.full_access+offline_access
&client_id={{client_id}}
&redirect_uri={{redirect_uri}}

Non-interactive: server-to-server

The non-interactive integration applies to clients that are not building a user interface. In other words, it works as a server-to-server interaction. The KS Connect API always works with the concept of a user. For this reason, server-to-server interactions need a predefined user. For instance, a system user that needs to be previously added to all the sites the client wants to manage. This system user needs to be added under a site_owner role.

Non-interactive clients make use of a password_flow. Once the environment is set up, clients must create a POST request to the Salto KS Identity Provider to request the token, as well as provide a client ID and a client secret. Then, in the body of the request, the client must fill in the following values:

curl --location --request POST "{{identity_server_url}}/connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9pZF9zZWNydGV0" \
--data-urlencode "grant_type=password" \
--data-urlencode "username=(insert KS email here)" \
--data-urlencode "password=(insert KS password here)" \
--data-urlencode "scope=user_api.full_access"

The response body will contain the access token with which clients can make API requests.

Refresh tokens

Refresh tokens have a much longer lifetime, so they can be used to obtain another access token with a POST call to the token endpoint. This flow works for both interactive and non-interactive clients.

curl --location --request POST "{{identity_server_url}}/connect/token" \
--header "Content-Type: application/x-www-form-urlencoded" \
--header "Authorization: Bearer {{access_token}}" \
--data-urlencode "client_id=client" \
--data-urlencode "client_secret=secret" \
--data-urlencode "grant_type=refresh_token" \
--data-urlencode "refresh_token=hdh922"

When integrating with Salto KS, every client application needs to go through an authentication process before making a call to the APIs. This is done so that the KS Identity Provider, which works as a security gateway, is able to verify the identity of the application that is trying to connect.