GSD REST API Login

There are three options to log in to the database, each of them is characterized by a different level of security due to the various authentication process in performing requests. A more detailed description of them is below.

/v1/login

After successfully logging in to the database, we get a "sessionId", which must be declared in request header as "sessionId" when performing subsequent requests to carry out successful authentication process.

Example

POST request
1
2
3
4
5
6
7
8
POST http://localhost:8080/v1/login

POST data:
{"user": "test","pass": "098f6bcd4621d373cade4e832627b4f6","appNames":["test1","test2"]}

Request Headers:
appkey: 123
Content-Type: application/json
Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "status": {
    "internalStatus": "0",
    "statusMessage": "ok"
  },
  "data": {
    "sessionId": "c75e48cd-4f9e-4fe6-bbaf-61725d019a0d",
    "user": {
      "~ClassName": "User",
      "~ObjectID": "2S49",
      "~StoreTime": "20180905T114022+02:00",
      "Name": "GSDWebService",
      "Description": "Benutzer für Web-Service",
      "Groups": {
        "~Count": 1,
        "~UnfilteredCount": 1,
        "~Elements": [
          {
            "~ClassName": "UserGroup",
            "~ObjectID": "2S1Y",
            "~StoreTime": "20180711T160940+02:00",
            "Name": "Jeder",
            "Description": "Rechte für jeden Benutzer"
          }
        ]
      },
      "Employee": {
        "~ClassName": "Mitarbeiter",
        "~ObjectID": "6NB9",
        "~StoreTime": "20180718T080522+02:00",
        "Name1": "webservice",
        "Name2": "",
        "Name3": "",
        "Bild": {
          "~ClassName": "Bild",
          "~ObjectID": "8ZWX",
          "~StoreTime": "20180516T074606+02:00"
        },
        "Mitarbeiteransprechpartner": {
          "~ClassName": "Ansprechpartner",
          "~ObjectID": "CQKN",
          "~StoreTime": "20180718T080526+02:00",
          "Name1": "webservice",
          "Name2": "",
          "Name3": "",
          "Bild": {
            "~ClassName": "Bild",
            "~ObjectID": "8ZWX",
            "~StoreTime": "20180516T074606+02:00"
          }
        }
      }
    },
    "databaseName": "testDatabase"
  }
}

/v2/login

After successfully logging in to the database, we get a "token" (JWT), which must be declared in request header as "Authorization" when performing subsequent requests to carry out successful authentication process. More info about JWT.

Example

POST request
1
2
3
4
5
6
7
8
POST http://localhost:8080/v2/login

POST data:
{"user": "test","pass": "098f6bcd4621d373cade4e832627b4f6","appNames":["test"]}

Request Headers:
appkey: 123
Content-Type: application/json
Response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
{
  "status": {
    "internalStatus": "0",
    "statusMessage": "ok"
  },
  "data": {
    "user": {
      "~ClassName": "User",
      "~ObjectID": "2S49",
      "~StoreTime": "20180905T114022+02:00",
      "Name": "GSDWebService",
      "Description": "Benutzer für Web-Service",
      "Groups": {
        "~Count": 1,
        "~UnfilteredCount": 1,
        "~Elements": [
          {
            "~ClassName": "UserGroup",
            "~ObjectID": "2S1Y",
            "~StoreTime": "20180711T160940+02:00",
            "Name": "Jeder",
            "Description": "Rechte für jeden Benutzer"
          }
        ]
      },
      "Employee": {
        "~ClassName": "Mitarbeiter",
        "~ObjectID": "6NB9",
        "~StoreTime": "20180718T080522+02:00",
        "Name1": "webservice",
        "Name2": "",
        "Name3": "",
        "Bild": {
          "~ClassName": "Bild",
          "~ObjectID": "8ZWX",
          "~StoreTime": "20180516T074606+02:00"
        },
        "Mitarbeiteransprechpartner": {
          "~ClassName": "Ansprechpartner",
          "~ObjectID": "CQKN",
          "~StoreTime": "20180718T080526+02:00",
          "Name1": "webservice",
          "Name2": "",
          "Name3": "",
          "Bild": {
            "~ClassName": "Bild",
            "~ObjectID": "8ZWX",
            "~StoreTime": "20180516T074606+02:00"
          }
        }
      }
    },
    "token": "eyJhbGciOiJIUzI1NiIsImtpZCI6ImdCZGFTLVZGZFMzNDIzM2RhUCJ9.eyJzZXNzaW9uSWQiOiJlMWYyN2VmZS04OTM3LTQ0YzUtOTBmMC0xN2E0MmI5NzE4ZTIifQ.2vAN8m00YF5jZa7Psd2S-jl66TvO3NAsRNIndyje3-4",
    "databaseName": "testDatabase"
  }
}

/v2/login/secure/key

This request returns server's public key needed for /v2/login/secure. REMEMBER - use _HTTPS_ to fetch public key. Otherwise we can not guarantee that you get valid data.

Secure login sequence diagram


Sequence diagram

Examples

GET request
1
2
3
4
5
GET http://localhost:8080/v2/login/secure/key

Request Headers:
appkey: 123
Content-Type: application/json
Response
1
2
3
4
5
6
7
8
9
{
  "status": {
    "internalStatus": "0",
    "statusMessage": "ok"
  },
  "data": {
    "key": "-----BEGIN PUBLIC KEY-----\r\nHr78gy7sd08bgdw0gf8w0j2g0f2g2wgfweg80ewgbuwegbewbgeggbewrewgaefJ\r\neworfjewvg8w976g89erb6g7sew7r09wg9q83ht4ggsdf78g7s9g87fsbh89sh7f\r\nfgsdgdsg67f67sd69fsg67g6re90bs9h6sj906gsgh0ag7ag67ag6ag6a90g690a\r\fregd8es9g85gb9gfase685rgf89aewrfds8fd6agh7fs6gfd9sg69fsg9gs6fg9s\r\nfdsagfdz78g5a89hf59hnjfa5hgd8a5f8fa0ajhsgdasgh5fdhfatawefaewewfC\r\nfsgfsgDSGFygoGIsdfuhf789sg690agfGY0Dgy90DGY7vgfdyvd07fewnvuwi77w\r\nFDSREWWF\r\n-----END PUBLIC KEY-----\r\n"
  }
}

/v2/login/secure

This case is different from the previous login options. First, it is necessary to get the public key - "key" using the /v2/login/secure/key request. Having the key it is possible to log in to the database. After successfully logging in to the database, we get a "sessionId" (securely encrypted by server-side), which must be declared in request header as "Secure-Token" when performing subsequent requests to carry out successful authentication process.

/v2/login/secure uses RSA Encryption for request and response.

However RSA message has a maximum length of 1/8 of the key [eg. 2048 key may contain only 256 bytes of message].
To overcome this limitation, we are using common technique of connecting multiple RSA messages into one string and then encoding it with base64.
This means that if your message has 600 bytes it will be 256 + 256 + 256 in length. [The last one contains a RSA padding of 168 bytes].

Tip

You can verify if the response/request string is correct when the length of bytes is a multiplication of maximum message length [eg. 256/512/768/1024 bytes (for 2048 byte key)].
We currently use 2048 bit keys for REST API, however this may change in a future to meet modern standards of encryption.
You can also generate your own key and place them where the encryption config points.

Examples

POST request

Logging in via secure path requires to provide two json keys:

1. credentials:

which must contain following json:

1
2
3
4
5
{
  "appNames": [],
  "user": "",
  "pass": ""
}

This json must be RSA encrypted using server's public key you get from /v2/login/secure/key and then encoded in base64.

2. publicKey: - your public key encoded in base64.

Having those data encoded correctly you should end up having similar data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
POST http://localhost:8080/v2/login/secure

POST data:
{
  "credentials": "B7p04IFqCSz2W/zTTwmpFmr17wSKi3/C9nuHBK4vyW4xRBWXTwatWH+T9PhCWYfc7pNed38/bs8g4xXPlmxP17J8pMpqee2ryOjjnnl3702HuS+O1w8p6dsrQotppbuB1XKjscdVWwqmfjgxYbeReQtHOG+gVHSwpi1BXh+uBk+stkxORqtzVzvfUnmB7mLMyXg/fJzmUrj5iTYe7QtM0UD0FhbXfV3yjc3Q0DbZtiAPRtA6Z+83RwApkiuCwGUPdvVXkHC1IxicaE/i60Oaw+nge15sAOcdAou7TxpKVLFq/RJwfJosyHtWsAq0DODDHgaLMeXhAWO9s4twTLJgVw==", 
  "publicKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0KTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUE0bTBjckVMTFd3c1VxWkVRUnh6QQp3MDcxd3NONFVxTTFmbEx5dzhUVlliWURVNW1MVVhLdmpUUDRRY3JoS255TjZ1R3k2QThiNEw0ZzBvT1NVT2FNClhLYVU4Tnh0ZkNrbHM2R21ML3k3RWJQMTltQVJEMUE2d3d3UGs0bTE1Z1MvRTd2a3dUbDJOZ252ayt0amloUnUKb0pPOUFNK3lvNjg0YkgzMXRVeG9rNU92MU9GMmJaUzJUbEpkaDV4NnN0ZHNweGdpN0Q0NHFqakpuOW9UYS9jaAp6MmJFN1czS1IzcE1TSlc5Syt3UzA0L3IyYkI4RHBTU2I3VWpYVWZUdVY2M2xBNnIzbktMM2QxeEwvQkc1clhUClNoTkNTeGsybmR2OWFVREhRN29EM0o2ZnNycExaOFpFRU9MRjNYaW94TDFoQU5SY3Y3dk9xQm1oNTNIdjkvWWEKdXdJREFRQUIKLS0tLS1FTkQgUFVCTElDIEtFWS0tLS0tCg=="
}

Request Headers:
appkey: 123
Content-Type: application/json

If there were an encryption errors (wrong key/wrong data encoding), response will not encrypted so you can easily fix it.

Once you provide properly encoded/encrypted data, all of the further requests you receive will contain only an encrypted payload.

Encrypted response
1
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

You must base64 decode then decrypt it using your private key. It will contain login data:

Decrypted response
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
{
  "status": {
    "internalStatus": "0",
    "statusMessage": "ok"
  },
  "data": {
    "sessionId": "ZVrH2ogDA1eU4UMHqB6eux8hKmd1ycnpKQYW1oIVTcbNpLMBwFHWggCbsKiTRphYPxgupJeC1Yksi7OFHclDnmlokLVorr4dTtqT0V4frN+H8BWGDvo3XWQQfxnVTJuMWTp9Yq69IS8xrjBOZ+LmrTNYqWtcSsqdke4LCFJYab9P9vKSvL29tjUnrPOJrobIWK3O/3n13XNxdxBCvDN6n1Y5tDt7u/E6zgbYbuc3OkY5jyRtgdKHKugAkWgaT3uRllSIhpsD3pH5W2cUHeNfqR0xL0FwItUOT7eWYTbkxU5lKSr7oorKUm4nb5TS/pfBeyUZwuKd4kVBXTdVcqDhaQ==",
    "user": {
      "~ClassName": "User",
      "~ObjectID": "2S49",
      "~StoreTime": "20180905T114022+02:00",
      "Name": "GSDWebService",
      "Description": "Benutzer für Web-Service",
      "Groups": {
        "~Count": 1,
        "~UnfilteredCount": 1,
        "~Elements": [
          {
            "~ClassName": "UserGroup",
            "~ObjectID": "2S1Y",
            "~StoreTime": "20180711T160940+02:00",
            "Name": "Jeder",
            "Description": "Rechte für jeden Benutzer"
          }
        ]
      },
      "Employee": {
        "~ClassName": "Mitarbeiter",
        "~ObjectID": "6NB9",
        "~StoreTime": "20180718T080522+02:00",
        "Name1": "webservice",
        "Name2": "",
        "Name3": "",
        "Bild": {
          "~ClassName": "Bild",
          "~ObjectID": "8ZWX",
          "~StoreTime": "20180516T074606+02:00"
        },
        "Mitarbeiteransprechpartner": {
          "~ClassName": "Ansprechpartner",
          "~ObjectID": "CQKN",
          "~StoreTime": "20180718T080526+02:00",
          "Name1": "webservice",
          "Name2": "",
          "Name3": "",
          "Bild": {
            "~ClassName": "Bild",
            "~ObjectID": "8ZWX",
            "~StoreTime": "20180516T074606+02:00"
          }
        }
      }
    },
    "symmetricKey": "N8O8w5bCs8KRF8OKw7rCs8K8EcOWSk5XwoDCh8KHVcOrw7nColPCuQjDpcKiw5powp/CosKX",
    "databaseName": "testDatabase"
  }
}

Valid login request will contain two important json keys:

$.data.sessionId - your secure sessionId that you must provide as Secure-Token Header for each further request you wish to call.

$.data.symmetricKey - an unique AES-CTR key bound to your session you must use to encrypt request data.

Important information:

  1. Do not share symmetricKey with anyone. Store it for current session, each login provides new secure key and session.
  2. Remember to use Content-Type: application/text for encrypted data.
  3. All encrypted payload (except for binary downloading/uploading) must be encoded in base64 to ensure consistent data flow.
  4. Only login request/response are encrypted via RSA keys, each next request/response must be encrypted with AES-CTR encryption using symmetricKey
  5. AES-CTR IV Counter is incremented by one.
  6. All encrypted responses will contain Encrypted header.