Single Sign On

How todo integration

To be able to integrate a website with SSO, we must register your web application in SSO. Later your web application will be called an SSO client product. To become an SSO client, we need this following information.

After being registered with SSO, the client will get a Product Token. It will be used as an authentication method during the data transfer process. The product token will be static and consists of random characters in string form.

Example : lVC3WbusmJFK4UClg3wlJFOp4A6bxSxj1S2ezUqkSNIg8347fkOiovkAlGnfc.

Note:

If you don't want to use the default path generated by SSO for data communication, you can customize the URL. Below is a list of URLs and actions that you can customize based on your product.

When accessing product custom endpoint, SSO will send Product Token as an authorization header.

API Responses

Each response provided by SSO will have the following json format. Apart from the following JSON format, you can also check the state of the process you are carrying out via the http response code which is responded to by SSO.

Success Response

{
  "status": "success",
  "message": "This is success message",
  "data": ""
}

Fail Response

{
  "status": "error",
  "message": "Unable to proccess",
  "data": ""
}

Client Login

Before integration with SSO, the client may be have had its own login page which was accessed if the user had not logged in to the website. If you have integrated with SSO, you can redirect to the BASE_URL of SSO to carry out the user login process.

When redirected to that page, you also have to enter a query parameters in the URL.

• redirect, Contains the URL that SSO will redirect to when the login process is successful. By default, if you do not include this parameter, a redirect will be made to the SSO dashboard. For example : https://pos.domain.com

The final URL will look link this:

https://sso.bnlstg.com?redirect=https://pos.domain.com

SSO Login Callback

After successful login on the SSO page, the user will be directed to the URL you provided in the section above by reading the user token. This user token is a key that will later be used to verify the user. This token will be sent to the SSO Client via the parameters in the callback URL. SSO will automatically add the path "sso/callback" to the redirect URL you used previously.

Example : https://pos.domain.com/sso/callback?token=sj9293uruwejdwe923jfee

On this path, the next task is for the client to process the token. The client must carry out a verification process to ensure that the token is valid. The verification process can be done using the endpoint API_BASE_URL/user/verify-by-product .

GET : API_BASE_URL/user/verify-by-product

curl --location 'API_BASE_URL/user/verify-by-product' 
\ --header 'Authorization: Bearer sj9293uruwejdwe923jfee..' 
\ --header 'ProductAuthorization: Bearer lVC3WbusmJFK4UClg3wlJFOp4A6bxSxj1S2ezUqkSNIg8347fkOiovkAlGnfc'

Header Parameter

Response Parameters

{
  "status": "success",
  "message": "Logged in user",
  "data": {
    "user": {
      "id": 2,
      "username": "johndoe",
      "email": "user@domain.com",
      "first_name": "John",
      "last_name": "Doe",
      "phone": "",
      "phone_verified": false,
      "email_verified": false,
      "status": true,
      "mfa_active": true,
      "remember_token": "",
      "last_login": "2024-01-10T02:04:14.692Z",
      "last_login_ip": "127.0.0.1",
      "created_at": "2023-11-21T09:03:28.119Z",
      "updated_at": "2024-01-10T02:04:14.693Z",
      "main_user_id": null
    },
    "user_product": {
      "user_id": 2,
      "product_id": 1,
      "external_id": "16",
      "role": "admin",
      "product": {
        "id": 1,
        "name": "Point Of Sales",
        "url": "https://pos.domain.com",
        "description": "",
        "status": true,
        "image_url": "https://pos.domain.com/assets/logo.png",
        "ip": "",
        "token": "zIXOfxkiuFQny966eAU1mT4abkaWcz8v3v8psN88",
        "api_endpoint": "https://pos.domain.com/sso/callback",
        "created_at": "2023-11-03T15:40:42.419Z",
        "updated_at": "2023-11-03T15:40:42.419Z"
      }
    }
  }
}

Error Responses

Check User

If you don't import all user data, you can use this endpoint as an alternative. In this process, SSO will POST user credentials in the form of email and password to your API product.

The product must handle searching for user data based on email and password then returning it so that it can be processed by SSO. This process will be called if the user is not found on the SSO page during the login process.

POST : https://pos.domain.com/sso/callback/check_user

Body Parameter

Expected API Responses

{
  "status": "success",
  "message": "User founded",
  "data": {
    "external_id": "1",
    "main_user_external_id" : "0",
    "username": "johndoe",
    "email": "user@domain.com",
    "first_name": "John",
    "last_name": "Doe",
    "status": 1,
    "role" : "staff",
    "phone": "",
    "phone_verified": 0,
    "email_verified": 1,
    "mfa_active": 1
  }
}

Check User by Email

If the user has never synchronized with SSO, but its the first time they access SSO, and wants to reset the password. SSO will use this endpoint to synchronize from product. If a user is found on the product, we will save the user data and continue by sending a password reset email.

The product must handle searching for user data based on email then returning it so that it can be processed by SSO.

POST : https://pos.domain.com/sso/callback/check_email

Body Parameter

Expected API Responses

{
  "status": "success",
  "message": "User founded",
  "data": {
    "external_id": "1",
    "main_user_external_id" : "0",
    "username": "johndoe",
    "email": "user@domain.com",
    "first_name": "John",
    "last_name": "Doe",
    "status": 1,
    "role" : "staff",
    "phone": "",
    "phone_verified": 0,
    "email_verified": 1,
    "mfa_active": 1
  }
}

Assign User

The register or assign user process is the process of registering users and integrating them with SSO. There are 2 integration options that will be carried out. First, create a user from SSO and then send it to the SSO Client to be registered. Second, clients register users from local applications and then send them to SSO for data integration.

Assign User From SSO to Product

On assigning a user, SSO will include the role and properties of the product or client to be assigned. Role and properties will become a select dropdown, so that each SSO client must provide an endpoint that is used by SSO to retrieve these options.

The suffix of this endpoint has been determined by SSO, while the base URL of this API is the base URL registered when registering the client product in SSO. In this example, the API base URL used is https://pos.domain.com/sso/callback so the list of endpoints you must prepare is:

Get Properties

GET : https://pos.domain.com/sso/callback/get_property/{external_user_id}

Path Variable

Expected API Responses

Your endpoint must return JSON responses that will look like this.

{
  "status": "success",
  "message": "Property option by user",
  "data": [
    {
      "id": 5,
      "label": "Colosseum PIZZA"
    }
  ]
}

Option Result

SSO will creating select option based on your id as the value, and label as option label.

Get Roles

GET : https://pos.domain.com/sso/callback/get_roles

Expected API Responses

{
  "status": "success",
  "message": "Role list",
  "data": [
    {
      "value": "admin",
      "label": "Admin"
    },
    {
      "value": "sales",
      "label": "Sales"
    },
    {
      "value": "waiter",
      "label": "Waiter"
    },
    {
      "value": "kitchen",
      "label": "Kitchen"
    }
  ]
}

Option Result

SSO will create a role select option based on the application you created.

Assigning User in Product

Once a user is successfully assigned to a product in SSO, SSO will send the user data via API to the SSO Client. In this process, the client must handle the user data to be stored in the user database. Once the user data is successfully saved, you must provide a response back to SSO, so that SSO will process the user data.

POST : https://pos.domain.com/sso/callback/assign_user

Body Parameter

Expected API Responses

{
  "status": "success",
  "message": "User successfully assigned",
  "data": "{user_id}"
}

Assign User From Client Product to SSO

This is a reverse scenario that registers users is on your product, then the product must send the user data to SSO to be integrated. SSO will return a successful or failed response according to the condition of the data you sent.

POST : API_BASE_URL/user/product/add-user

curl --location 'API_BASE_URL/user/product/add-user' \
--header 'ProductAuthorization: Bearer lVC3WbusmJFK4UClg3wlJFOp4A6bxSxj1S2ezUqkSNIg8347fkOiovkAlGnfc' \
--form 'username="johndoe"' \
--form 'email="user@domain.com"' \
--form 'first_name="John"' \
--form 'last_name="Doe"' \
--form 'password="supersecurepassword"' \
--form 'status="1"' \
--form 'phone=""' \
--form 'phone_verified="1"' \
--form 'email_verified="1"' \
--form 'external_id="1000"' \
--form 'main_user_external_id="1"' \
--form 'role="kitchen"'

Response Parameters

{
    "status": "success",
    "message": "User saved successfully",
    "data": {
        "id": 2,
        "username": "johndoe",
        "email": "user@domain.com",
        "first_name": "John",
        "last_name": "Doe",
        "phone": "082xxxxxxx",
        "phone_verified": true,
        "email_verified": true,
        "status": true,
        "mfa_active": true,
        "meta_data": "",
        "remember_token": "",
        "last_login": null,
        "last_login_ip": "",
        "created_at": "2023-10-30T14:32:51.877Z",
        "updated_at": "2023-10-30T14:44:48.992+08:00",
        "main_user_id": null,
    }
}

Error Responses

Note: If this error was occurred, you can delete your user in your local database, or rollback you database transaction.

Update User

There are 2 scenarios for the user update process.

1. First, updates are initiated by users through the SSO (Single Sign-On) dashboard. In this scenario, SSO will send the update results to the relevant product to reflect the changes made.
2. Second, the scenario involves users updating their profiles directly from the product. The product must send these updates to the SSO for data integration.

Update User from SSO to Product

Once a user is successfully updated in SSO, SSO will send the user data via API to the SSO Client. In this process, the client must handle the user data to be update by external_id.

POST : https://pos.domain.com/sso/callback/update_user

Body Parameter

Success API Responses

{
  "status": "success",
  "message": "User updated successfully",
  "data": null
}

Error API Responses

{
  "status": "error",
  "message": "Unable to update user",
  "data": null
}

Update User from Product to SSO

This is a reverse scenario that user update their profile in product, then the product must send the user data to SSO to be integrated with SSO. SSO will return a successful or failed response according to the condition of the data you sent

PUT : API_BASE_URL/user/{external_id}/product/update-user

curl --location --request PUT 'API_BASE_URL/user/1/product/update-user' \
--header 'ProductAuthorization: Bearer lVC3WbusmJFK4UClg3wlJFOp4A6bxSxj1S2ezUqkSNIg8347fkOiovkAlGnfc' \
--form 'username="johndoe"' \
--form 'email="user@domain.com"' \
--form 'first_name="John"' \
--form 'last_name="Doe"' \
--form 'avatar="http//example.com/avatar-image.png"'

Path Variables

Body Parameter

Response Parameters

{
  "status": "success",
  "message": "User updated successfully",
  "data": {
    "id": 2,
    "username": "johndoe",
    "email": "user@domain.com",
    "first_name": "John",
    "last_name": "Doe",
    "avatar" : "http//example.com/avatar-image.png",
    "phone": "081xxxxxxxx",
    "phone_verified": true,
    "email_verified": true,
    "status": true,
    "mfa_active": true,
    "meta_data": "",
    "remember_token": "",
    "last_login": null,
    "last_login_ip": "",
    "created_at": "2023-10-30T14:32:51.877Z",
    "updated_at": "2023-10-30T14:44:48.992+08:00",
    "main_user_id": null
  }
}

Error Responses

Note : If this error occurred, you can rollback the changes

Un Assign User

The user unassign process is carried out on the SSO dashboard for users on the product. For the unassign process, SSO will send unassigned user data from the related product. You can carry out a soft delete process or deactivate the user on your product.

POST : https://pos.domain.com/sso/callback/remove_user

Body Parameter

Expected API Responses

{
  "status": "success",
  "message": "User deleted successfully",
  "data": null
}

Import User

This endpoint is used when you want to carry out the bulk data import process for users

POST : API_BASE_URL/user/import

curl --location 'API_BASE_URL/user/import' \
--header 'ProductAuthorization: Bearer lVC3WbusmJFK4UClg3wlJFOp4A6bxSxj1S2ezUqkSNIg8347fkOiovkAlGnfc' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "external_id": "1",
        "main_user_external_id" : "0",
        "username": "admin",
        "email": "admin@domain.com",
        "first_name": "admin",
        "last_name": "Admin User",
        "status": 1,
        "phone": null,
        "phone_verified": 0,
        "email_verified": 1
    },
    {
        "external_id": "28",
        "main_user_external_id" : "1",
        "username": "john",
        "email": "john.doe@domain.com",
        "first_name": "JOhn",
        "last_name": "Doe",
        "status": 1,
        "phone": null,
        "phone_verified": 0,
        "email_verified": 1
    }
]'

Header Parameter

Body Parameter

Response Parameters

{
    "status": "success",
    "message": "User data imported successfully",
    "data": {
        "imported": 0,
        "error_validation": 0,
        "unique_validation": 2,
        "total_error": 0,
        "total_data": 2
    }
}

• On importing user data process, the password will be set empty in the Single Sign-On (SSO), so when attempting to log in to SSO, users will need to go through the password reset process first before being able to proceed with the login process.

Get Product List

This endpoint is used to get a list of products based on logged in users. On this endpoint, you can display a list of products in your user dashboard. This is useful so that users can easily navigate to each product without remembering the product URL.

Note: This endpoint will only return a list of products other than the product you used in the Auth Product Token in the header parameters.

GET : API_BASE_URL/product/list/by-user-product

curl --location 'API_BASE_URL/product/list/by-user-product' \
--header 'Authorization: Bearer sj9293uruwejdwe923jfee..' \
--header 'ProductAuthorization: Bearer lVC3WbusmJFK4UClg3wlJFOp4A6bxSxj1S2ezUqkSNIg8347fkOiovkAlGnfc...'

Header Parameter

Response Parameters

{
    "status": "success",
    "message": "Product list by user product",
    "data": [
        {
            "id": "2",
            "name": "Channel Manager",
            "url": "https://cm.domain.com",
            "description": "Some product description",
            "status": true,
            "image_url": "https://cm.domain.com/assets/logo.png",
            "external_id": "272"
        }
    ]
}

Error Responses

Logout User

During the logout process, SSO marks the user's token as expired. To carry out this process, you can direct your user to the BASE_URL + /auth/logout page.

GET : BASE_URL/auth/logout

Next, SSO will carry out the logout process and end by redirecting your user to the SSO login page.