TABLE OF CONTENTS

Notes：
Our system provides two options for authentication and authorization: Access Token and JWT Authorization. 
① The Access Token is the default option and you can find more information about it in the Access Token.
② On the other hand, JWT Authentication is only available for a limited number of clients. If you want to know more about this option, please reach out to our CM or GO Help.

JWT Authentication Introduction

Authentication in DerbySoft GO is implemented using OAuth 2.0 and its extended protocol OpenID Connect. This authentication method provides a secure way to exchange data between distributors and DerbySoft GO during interface interaction. It ensures that interface calls and data access are secure for both parties.


Basic process

1. Distributors obtain Public Keys from DerbySoft GO.

2. Distributors cache the Public Keys locally.

3. DerbySoft GO sends a business request to the distributor with a token.

4. Distributors validate the token.

5. If authentication is successful, process the business request. Ignore it otherwise.

How to obtain Public Keys

1. Distributor gets JWK address from GO Console (planned)

2. Distirubtor access the JWK address to obtain Public Keys


Request parameter example:

GET https://xxxxxx/id/84A26B2FA77BCD1FF5130636F04C30C5/keys HTTP/1.1  
Content-Type: application/json;charset=utf-8

Successful response example:

{
    "keys": [
        {
            "alg": "RS256",
            "e": "AQAB",
            "kid": "1d9ead9856fa33d753eaa9d97e0cdb0e02c5694e",
            "kty": "RSA",
            "n": "hNIFX5GQDCpFOty1EnrCk-iA8czIjG7pGSxgKrE-saYt8HORPLquoQqv55cBZjEj2GSMnimEpRHckyNn-oUrLOyrpsvWIdanSE4hGBSe5bensc0RpoCOi0rbzkBiE6Yg28ANwrnJnShv236muIKmpyoMW_ZfkPojsJUm0KURR7JQ1-HsIdWXQN_-c-wDmsAPRHnqY33QVotlhALyQSNSpTj_snDkkz8_-y7bZHSJKgmhXFzKhb5ls7gRYTkKmMl3LoVmTacC-mT4bHtQ0xiztO-Fit1ag1EXWLXF3Z-jvow4vaFwhAibtMc7sAES0okqUCtR_RFZBHHb65hmvVyC7w",
            "use": "sig"
        },
        {
            "alg": "RS256",
            "e": "AQAB",
            "kid": "4033a0101d68472defe88f625833eb93384842b5",
            "kty": "RSA",
            "n": "0n6355e8v8-PUAgyMZO63uJbtddfh509Z31qJU_iVMJRLTYnD7E3j29hh6twE4nYXludf2cAwUX79BnXKl-XK4zkn_tUOvdbBJPT2LmKs_5ZCN8vJFH4QAoqIXWWGK9S42Q-KsFB3ADKP3I7YnPyXC8_j03dk0irPS2B21Eqjr4p6lBydGzyn2wmA_ZZnMYWiA-aFzdBj6h2_V2lru21PGDtpa9HQZn7a2jPwHLmdLatAbxS9x5oGzlFJ_oq4mNsePe4R78RZhu3LW94v68KWlIWW8eCo9O5OT7wt310pXtQx2PnW9-77FeL_DTVVNFs9j77FLpI9TitoNFi3qbo2Q",
            "use": "sig"
        }
    ]
}


Failure response example:

HTTP/1.1 404 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz


DerbySoft GO access Distributors with a token(JWT)

Token(JWT) Example:

eyJraWQiOiIzOTRiNTZjM2VhNTI0ZWU1OTAxNWY5YTdlODg2NjMxMiIsImFsZyI6IlJTMjU2In0.eyJpc3MiOiJodHRwczovL2lkLzg0QTI2QjJGQTc3QkNEMUZGNTEzMDYzNkYwNEMzMEM1Ly53ZWxsLWtub3duL29wZW5pZC1jb25maWd1cmF0aW9uIiwiYXVkIjoiWktUIiwiZXhwIjoxNzAzNTYwMDkwLCJqdGkiOiJRWGNxem5ldVZCYlJQbjE5NGtzOUFRIiwiaWF0IjoxNzAzNTU5NzkwLCJuYmYiOjE3MDM1NTk2NzAsInN1YiI6ImRzLWdvLW1vZHVsZSJ9.mNmpBZMm1lPFMvea75PSY1tn64l2XjeN5Y21KkaHyY9HHNzh5JUaG-XCn97WQwPgw7uTKs8zn5zWGgng9mZ8mie312qY0DILxCebZ2c_7Qt3drssa7EnRJf5kbFRHIay9S6lmuG9BE9o9lkAlnfFqOa7qHpzEFt35yKRS8ummlH3k_RjrBRBke7wb5VePRDryPb9LTd0hfu7e7guWOSEkR21rS6drHrd89dHHKwB28-SCs4KYeWPaUZFbBHG9vVaYn99ELoKs7cAKfBS_SX9-Ag9Z7e_wLoD-mgG9Bi8e8Mf0bfV4YdfusLTScxKnHeZwjGZkDDZN70aWZKVIaqimQ


Distributors decode and verify the token

A token is decoded with base64 example:

HEADER：
{
  "kid": "394b56c3ea524ee59015f9a7e8866312",
  "alg": "RS256"
}

PAYLOAD：
{
  "iss": "https://id/84A26B2FA77BCD1FF5130636F04C30C5/.well-known/openid-configuration", //Token Issuer
  "aud": "xxx", //Token Audience
  "exp": 1703560090, //Token Expiration Time
  "jti": "QXcqzneuVBbRPn194ks9AQ", //JWT ID
  "iat": 1703559790, //Token Issued Time
  "nbf": 1703559670, //Not Before
  "sub": "ds-go-module" //Subject of the JWT
}

SIGNATURE：
xxxxxx //signature


Distributors find the corresponding Publick Key from the Public Key set and then verify the token.

{
    "alg": "RS256",
    "e": "AQAB",
    "kid": "1",
    "kty": "RSA",
    "n": "rJzRIhtaVCJDg13QJearCXgiYQjXExd6xC8oD6hjRlyc-rACKIEedLTEkWskYMPEyK5ev7uSdQ8VLHVvrwL4GI_9NKex0MndePewaLL06LPHIK4enMGtMNUczWJ7HHT1_kYXiy259eh0xqOjDKkypGkU3Kq--M7qdIOfjMSXFHR-aBXz80qABbP7nUPJpLLHoNonr_VLDhYszQHL8k71pWsKYQO2Io4P3jT-pGdADp5OHAboizPwsZsasiGEw4UFq1A47R1XNKjeWqUwBqqVzhryWSQ606iPWEAle2cGBz7coiLWG59uhT39aDlUB6gRgi0vGxJn92sWGUmfnk698w"
}


Distributors check whether the token is valid,  whether the token's issuer is DerbySoft GO, and if the target audience is the distributor itself. If the verification is successful, it will process the business request and return success. On the other hand, if the verification fails, the business request will be ignored.