Skip to main content

Service Integration Guide

This document describes how to integrate the SERVICEME NEXT application with other websites or SSO (Single Sign-On) services to achieve unified identity authentication and seamless access across systems.

1. Basic Process​

The overall process of service integration is as follows:

  1. Configure login button on SERVICEME NEXT login page (optional)

    • Used to display the single sign-on entry on the product login page.

  2. Redirect to custom SSO frontend page

    • Handle login logic with the customer system (such as user information retrieval, biometric authentication initiation, etc.).

  3. Access custom SSO backend API

    • Complete interaction with the SERVICEME backend, such as unified user registration, token issuance, etc.

  4. Redirect back to SERVICEME NEXT login page

    • Redirect back to SERVICEME NEXT with the token to achieve automatic login.

Process diagram:

2. Detailed Operation Instructions​

2.1 Single Sign-On Button Configuration on Login Page​

This step is optional. If you want to provide a "custom login" button on the login page, you can add the configuration in the environment variables.

Go to the SERVICEME NEXT Environment Variable Management page and configure the following content in SSO_LOGIN_CONFIG:

{
  "type": "Custom",
  "code": "my-custom-sso",
  "config": {
    "LOGIN_BUTTON_I18N_KEY": "login.sso.custom.login",
    "LOGIN_URL": "/custom-login",
    "APP_ID": "BskGfSXPNt5AfQXMO6b1M"
  }
}

After configuration, a button will appear on the login page. Clicking it will redirect to the target link:

https://<frontend-deploy-host>/custom-login?code=my-custom-sso&APP_ID=BskGfSXPNt5AfQXMO6b1M

For custom mounting pages, please refer to Product Frontend Custom Mount Static Resources Guide - Overview.

2.2 Custom Development of Single Sign-On Page​

The page corresponding to LOGIN_URL is the customized login page, which needs to implement the following logic:

  1. Authenticate and interact with the customer SSO system;
  2. Synchronize information with the custom SSO backend;
  3. After obtaining the token, redirect to the SERVICEME NEXT login route.

The redirect format is as follows:

https://<frontend-deploy-host>/login-token?token=<new-jwt-token>

The SERVICEME frontend will verify the token's trustworthiness, and upon success, log into the system.
Please ensure the JWT token is valid and issued by a legitimate client.

2.3 Custom Development of SSO Backend​

The custom SSO backend is mainly responsible for user token issuance and account management.
Issuance depends on Client ID + Secret; please create a client in the SERVICEME backend first.

Related APIs include:

  • User APIs: query, create, update users; support search by username, email, employee number;
  • Third-party login APIs: manage third-party account bindings;
  • Client APIs: issue tokens (ignore trusted domain fields);
  • Role/Organization APIs: used for role and department synchronization.

2.4 Mounting Custom Frontend and Backend Services​

The SERVICEME NEXT frontend image provides two mount points:

Mount PathDescription
/etc/nginx/custom_confMount custom Nginx configuration
/usr/share/nginx/staticMount custom static resources (frontend pages)

2.4.1 Mount Custom Frontend Pages​

Place the custom HTML pages at:

/usr/share/nginx/static/app2/

And add the following content in custom.conf:

location /app2 {
  root /usr/share/nginx/static/;
  index index.html index.htm index.shtml;
  try_files $uri $uri/ /index.html;

  if ($request_filename ~* .*\.html$) {
    add_header Cache-Control "no-cache, no-store";
  }
}

Mount the directory when running the container:

docker run -p 80:80 \
-v ./custom.conf:/etc/nginx/custom_conf/custom.conf \
-v ./static:/usr/share/nginx/static \
servicemerelease.azurecr.io/serviceme-frontend:4.0.0

2.4.2 Mount Custom Backend Service​

Assuming the custom backend service is located at the intranet address http://delivery-backend,
and you want to access it under the frontend path /custom-backend/, add the following configuration in custom.conf:

location /custom-backend/ {
  proxy_pass http://delivery-backend/;
  proxy_connect_timeout 240s;
  proxy_read_timeout 240s;
  proxy_send_timeout 240s;
  proxy_buffering off;
}

Conclusion​

By following the above steps, you can achieve seamless integration between SERVICEME NEXT and internal enterprise systems,
supporting single sign-on (SSO), unified user authentication, and flexible frontend and backend custom extensions.