Skip to content

Security#

Before you can use the API of Laces Hub, you must have an activated user account (see Getting started) and register your client application as an approved application.

Approving your application#

By registering your client application as "approved", you imply that you trust this application to connect to the API on your behalf. Using the steps below you can assign the same, or stricter, permissions to your application.

First you should login to Laces Hub at hub.laces.tech.

Click on your user profile icon, in the top right corner, and select the "Approved Applications" menu option.

Within the approved applications overview page, click on the "Approve Application" button.

Provide the necessary details for your new application:

  • Application name: a descriptive name to identify your application later
  • Authentication type: either BASIC or LACES_TOKEN (see below)
  • Application password (only BASIC): the password which will be used by the application, see Basic authentication.
  • Application public key (only LACES_TOKEN): the public key of a public/private key pair, which will be used for generating authentication tokens (see Token authentication). This field must only contain the base64 encoded key and no other text. See Create RSA Key-pair for details on how to create a public (and private) key.
  • Generate key pair: By checking this option, the platform will create a unique key pair for you. Make sure you copy the private key for later, as it will not be stored and therefore cannot be retrieved later!
  • Repository permissions: select the permissions you want for your newly approved application on each group or repository. These permissions are by default all set to 'none', to avoid that users accidentally provide too many permissions to an application.

Permissions#

While registering your application, you can grant the application permissions on any group or repository for which you have permissions. Based on your personal permissions, you can either select the same permission, more strict permission, or no permission at all. The permissions tree shows all groups and repositories which you can access. If you grant certain permissions to a group, all the subgroups and repositories below will automatically receive the same permissions. It is possible to add higher permissions to a specific subgroup or repository. However, groups and repositories can never have less permissions than their parent group.

You can grant the following roles to your application:

  • None: no access
  • Viewer: read-only permission
  • Publisher: read and write permissions
  • Manager: full administrative permissions

After filling in all the necessary details and clicking on "Approve", the application will be approved and you will be presented with an "Application ID". You can copy this ID using the "Copy to clipboard" button, as you will need this later when authenticating to the Platform from within your application.

After registration, the application will appear in your list of Approved Applications. From that point on the application can perform authorized requests to the platform on your behalf, based on the provided permissions.

After this step you are set up to start accessing services of the Laces Platform from your approved application.

This mechanism also supports the case in which you might want to revoke permissions for a single application, without the need to change your password. To stop an application from accessing the platform, login to the Platform, navigate to your Approved Applications, and press the "Revoke" button on the right of the application entry.

Authentication#

The two authentication methods, using Basic- and Token Authentication, both require you to create an approved application. Once created, you should have an application ID and either as password or private-public key-pair.

Basic authentication#

The easiest way to connect to the Platform is using Basic Access Authentication. This form of authentication uses a standard HTTP Header Authorization for which the value should be constructed in the following manner:

  1. The username and password are combined with a single colon (:)
  2. The resulting string is encoded using a variant of Base64
  3. The authorization method Basic and a space are then prepended to the encoded string

In case of a username "application-id" and password "supersecret", we would need to use the following header and value:

Authorization: Basic YXBwbGljYXRpb24taWQ6c3VwZXJzZWNyZXQ=

Since the base64 encoding of application-id:supersecret is YXBwbGljYXRpb24taWQ6c3VwZXJzZWNyZXQ=.

Note: Although we use the username application-id in the example above, your application's username is equal to its application ID (e.g. abcdef12-3456-7890-abcd-ef12345667890) which can be found on its details page and copied using the "Copy" button.

Warning: Since the username and password, although encoded in Base64, are transmitted in plain text, anybody who intercepts the request can recover these credentials. Therefor it is important to always use a secure (HTTPS) connection when using this form of authentication.

Some HTTP (REST) clients support this form of authentication out of the box and will take away all complexity of constructing and providing this header in your requests. In case of Postman you simple open the "Authorization" tab of a request and select "Basic Auth" from the Type dropdown. Then you simply fill in your username and password.

Token authentication (advanced)#

In this case each requests to the REST API is authenticated using public-key cryptography. For this, a public/private key pair should be generated: the public key should be registered at the platform and the private key should be used to generate an authentication token (and should be kept secret!).

The way in which this type of cryptography works, is that anybody can check the validity of the provided token using the "known" public key, but only the holder of the private key is able to generate a valid token.

While registering you application, you can either provide a valid public key, for which you hold the private key. Or you can generate a pair directly on the page, of which only the public key is stored (and you should copy and store the private key yourself). Want to know how how to create a key pair by yourself? Check out Creating RSA Key-pair.

When copying and pasting the keys, make sure to remove any lines starting with "-----BEGIN" or "-----END", including any newline characters.

Every applications must sign their requests with an valid token, which is calculated using RSA cryptography. The requesting application uses its private key to create a signature, which is then added as the authentication token. Upon receiving this token, the platform will then validate the token using the known public key.

The authentication token should be provided within the Authorization header of the request, and its value should start with the text "semmtech-app-token":

semmtech-app-token appId="{applicationId}", signature="{signature}"

Following this token, two key-values are provided. Here, the {applicationId} must match the ID provided during registration of your application in the Laces Platform (see above). The {signature} is the signature generated from the relative request URL for the current request, using an asymmetric encryption algorithm (SHA-1 with RSA).

Generating a signature is done as follows: first, the SHA-1 hashing algorithm is used to produce a digest from the relative URL that you want to query; then, the hash is encrypted using the RSA encryption algorithm using the public/private key pair that was generated earlier and registered on the platform for the application. The result of the encryption should be base-64 encoded to yield the signature.

Below is an HTTP example of calling the service located on the Laces Platform hosted at 

http://hub.laces.tech

The call is done from within the application, which has as its application ID "3bb7f45d-1adf-437a-affa-ae783e779a18". To retrieve a list of top-level groups, accessible to the application, we call the API with:

GET /api/v1/groups HTTP/1.1
Host: hub.laces.tech
Authorization: semmtech-app-token appId="195331be-05d8-4f1c-b69e-1a437c5c3d91", signature="WLIoyDcU+Jh.....4rX+QokXt0fyw4qdtjdJldmLFSU3uryI2GQ3xj0="