Verify Requests from Space

Space SDK supports this verification type out of the box. A Space client provides the verifyWithPublicKey() method that handles the entire signature verification process. To verify the signature, the method requires the request body and the content of the X-Space-Public-Key-Signature and X-Space-Timestamp HTTP headers.

For example, this is how you can use this method to verify requests in your application:

Jump to sample code

The typical workflow looks as follows:

1. Before sending a request to your application, Space calculates a request hash.

2. Space generates a request signature: It takes the calculated hash and encrypts it with a private key. The signature is sent along with the request in the X-Space-Public-Key-Signature HTTP header. For example, this is a sample Space request including headers:

   POST /api/myapp HTTP/1.1 X-Forwarded-For : ::ffff:123.123.123.123 X-Forwarded-Proto : https X-PageKite-Port : 443 X-Space-Timestamp : 1632844347462 X-Space-Public-Key-Signature : iOjFEi5EpW+FbU1CJl+oc0QOJbIrv7kaV/VTEMa5i0ot6418N3ObQGz2C0tB8e2N4vHKQ7LWMZZ+OJexeHHoJGvL0XN7nwWb5k7Hn1DOPMMkWgSi6kL5orkyOHqIDPaHgZzX6IGbl3LP/aPms7E1NXaFRIfxuUQGdsDeA7yCjTIv/Rq8AbV9VqVI5TudAhHmaxh6R19wgtzWxaud27rsXV8INAvwXAQLMf5Ld+E1Mzi67qrS79Jxa7U34SJjC9xDe1wYMCZGc+G+6L4zdqVB08C2MCfI1IVYzqiHLyJgCHxhBmvjJ8JivoqadbRKOrbKShvSzHqFD5geEBovO0HqKA== User-Agent : Space (81383) Ktor http-client Accept-Charset : UTF-8 Accept : */* Content-Length : 196 Content-Type : application/json Host: 12345abcdef.ngrok.io Connection : Keep-Alive {"className":"ListCommandsPayload","clientId":"f6df3d26-d9fc-41c5-9fbd-0e7896f2cfb0","userId":"2BgVYn24Jx6u"}

3. The application receives the request. Now, it should verify the request signature.

   First, the application must obtain a public key from Space. To do this, the application must send an HTTP request to the applications/public-keys Space endpoint. For instance, this is how a request might look like:

   GET https://mycompany.jetbrains.space/api/http/applications/clientId:abc1234/public-keys Authorization: Bearer abc1234 Accept: application/json

   Here clientId is the client ID assigned to your application during registration. API Playground can help you with generating a request:

   

4. In the reply, Space sends a JSON Web Key set. Typically, the set contains only one key. When a current public key becomes outdated, there is a period of time when the set contains two keys (the current one and a new one).

   For each key in the set, the application must:

   1. Get the value of the X-Space-Timestamp header and the request body.

   2. Generate a string consisting of the timestamp and the body. Use colon : as a delimiter. For example in Kotlin, it can look like follows:

      val str = "$timestamp:$body"

      In case of the sample request above, the str value would be:

      1632844347462:{"className":"ListCommandsPayload", "clientId":"f6df3d26-d9fc-41c5-9fbd-0e7896f2cfb0","userId":"2BgVYn24Jx6u"}

   3. Calculate string hash using SHA512.

   4. Decrypt the content of the X-Space-Public-Key-Signature header using the RSA algorithm.

   5. Compare the decrypted signature with the calculated hash. If they are equal, the application is allowed to process the request, if not, the application must return the HTTP 401 Unauthorized response code.

      Note that only one key from the set must return the correct hash result.

Important: After a certain period of time, public keys become outdated. So, while the application can cache public keys (to avoid requesting them from Space each time), the cache should be cleared once the cached keys don't produce a correct signature. Space SDK does such caching under the hood.

Sample code

The following Kotlin code snippet demonstrates how to check the signature in the X-Space-Public-Key-Signature header:

There are no helper functions in Space SDK for this method, so, our task is to implement the verification logic described in Verify Requests from Space. To calculate hash, you can use the Apache Commons Codec library. To reference it from a Gradle project, add the following lines to build.gradle:

• To repositories:

  repositories { jcenter() // ... other repos }

• To dependencies:

  dependencies { compile group: 'commons-codec', name: 'commons-codec', version: '1.15' // ... other dependencies }

This is how a simple implementation of this method can look like:

The typical verification workflow looks as follows:

1. During registration of your application, Space can issue it a signing key. To get the key, you should open the Endpoint tab of the application settings and click Generate under Signing key.

2. Save the signing key in your application, for example, as a string constant.

3. Before Space sends a request to your application, it calculates the request hash using the generated signing key and puts it into the X-Space-Signature header. For example, this is a sample Space request including headers:

   POST /api/myapp HTTP/1.1 Host: 12345abcdef.ngrok.io User-Agent: Space (61355) Ktor http-client Content-Length: 163 Accept: */* Accept-Charset: UTF-8 Content-Type: application/json X-Forwarded-For: 123.456.123.456 X-Forwarded-Proto: https X-Space-Signature: 2aa8cba6217a28686de0ca8dcfe2a1d0795e343d744a0c5307308e43777593a5 X-Space-Timestamp: 1607623492912 Accept-Encoding: gzip {"className":"ListCommandsPayload","accessToken":"","verificationToken":"d415ca5965b37f4f0cac59fd33de7b94e396284e897d0fb8a070d0a5e1b7f2d3","userId":"2kawvQ4F6GM6"}

4. Now, it's the application's turn to calculate the request hash. To do this:

   1. Get the value of the X-Space-Timestamp header and the request body.

   2. Generate a string consisting of the timestamp and the body. Use colon : as a delimiter. For example in Kotlin, it can look like follows:

      val str = "$timestamp:$body"

      In case of the sample request above, the str value would be:

      1607623492912:{"className":"ListCommandsPayload","accessToken":"","verificationToken":"d415ca5965b37f4f0cac59fd33de7b94e396284e897d0fb8a070d0a5e1b7f2d3","userId":"2kawvQ4F6GM6"}

   3. Use HMAC SHA256 to hash the string.

5. Compare the calculated hash with the one you get from the X-Space-Signature header. If they are equal, the application is allowed to process the request, if not, the application must return the HTTP 401 Unauthorized response code.

The idea behind the method is to compare the verification token in the request body with the request your application obtained during registration in Space. As the verification token is a part of the payload, the SDK provides an extension method for the ApplicationPayload class:

This is how a simple implementation of this method can look like:

The typical verification workflow looks as follows:

1. During registration of your application, Space can issue it a verification token. To get the token, you should open the Endpoint tab of the application settings and click Generate under Verification token.

2. Save this token in your application, for example, as a string constant.

3. When Space sends a request to your application, it puts this verification token in the request body. For example, this is how the body of a slash command request looks like (a user presses / in the chatbot's channel):

   { "className": "ListCommandsPayload", "accessToken": "", "verificationToken": "d415ca5965b37f4f0cac59fd33de7b94e396284e897d0fb8a070d0a5e1b7f2d3", "userId": "2kawvQ4F6GM6" }

4. The task of the application is to get the verificationToken from the request payload and compare it to the token stored in the application. If they are equal, the application is allowed to process the request, if not, the application must return the HTTP 401 Unauthorized response code.

Space SDK doesn't provide any helper methods to perform this verification method. Most of the modern frameworks provide support for HTTP authentication out of the box. For example, here you can find the instructions for Ktor.