OpenID Connect concepts

Before explaining how to obtain an access token for calling the KS Connect API, here are some OpenID Connect concepts that will be mentioned later.

Application types

The OAuth 2.0 specification (Section 2.1) defines two client types, based on their ability to maintain the confidentiality of their client credentials:

Confidential: Clients capable of maintaining the confidentiality of their credentials or capable of secure client authentication using other means.
Public: Clients that do not maintain the confidentiality of their credentials.

Furthermore, the following applications can be recognized:

Web Applications with a Server component: A web application is a confidential client running on a web server. The client credentials, as well as any access token issued to the client, are stored on the web server and are not exposed to or accessible by the resource owner. Example: Web applications that generate HTML on the server.
User-agent based applications: A user-agent-based application is a public client in which the client code is downloaded from a web server and executes within a web browser. Protocol data and credentials are accessible (and often visible) to the resource owner. Example: SPA or Single Page Applications. Web applications that generate HTML in the client's browser and call a different API to send and receive the data.
Native applications: A native application is a public client installed and executed on the device used by the resource owner. It is assumed that any client authentication credentials included in the application can be extracted. On the other hand, dynamically issued credentials such as access tokens or refresh tokens can receive an acceptable level of protection. At a minimum, these credentials are protected from hostile servers with which the application may interact. Example: Mobile applications.

This classification is important because different client applications might implement their authentication processes in a slightly different way. They will also have different features offered by the identity provider based on their security level.

Tokens

It can sometimes be confusing to distinguish between different token types. They have different lifetimes and have different purposes. However, not all of them are available for all scenarios.

ID tokens carry identity information encoded in the token itself, which must be a JWT (JSON Web Token).
Access tokens are used to gain access to resources by using them as bearer tokens. A bearer token means that the bearer can access authorized resources without further identification. Because of this, it is important that bearer tokens are protected. If someone gets hold of your access token, they will be able to impersonate you. The lifetime of access tokens is one hour. While not mandatory by the standard, in our case this token is also a JWT.
Refresh tokens exist solely to get more access tokens. It is not convenient to ask an end-user to enter their credentials every time the access tokens expire. On the other hand, from a security perspective, it should be possible to prevent access to someone without waiting weeks before their token expires. Refresh tokens are valid for multiple weeks, and they can be revoked.

Endpoints

The protocol used to communicate with the Identity Provider is HTTP communication.

The Identity Server URL is identity.eu.my-clay.com/. It is important to distinguish Token and Authorize endpoints, because depending on the type of the client application, it could be that you will need to use only one of them.

Authorize endpoint: The Authorize endpoint can be used to request tokens or authorization codes via your browser. This process typically involves an authentication process of the end-user and is of optional consent.

bash

curl -X GET "https://identity.eu.my-clay.com/connect/authorize\
?client_id={{client}}\
&scope={{space separated scopes}}\
&response_type=id_token token\
&redirect_uri={{redirect_uri}}\
&state={{state}}\
&nonce={{nonce}}"

Token endpoint: The Token endpoint can be used to programmatically request tokens.

bash

curl --location --globoff '{{identityServerUrl}}/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic {authorization_token}' \
--data-urlencode 'grant_type={grant_type}' \
--data-urlencode 'scope={scopes}'

Contents