# SSO Service
## What is SSO?
Single sign-on (SSO) is an authentication process that allows a user to access multiple applications with one set of login credentials.
## Which Types of SSO We Support?
The user authentication center platform/application is where we store user information like email, staff ID, password and so on.
The SSO protocol acts like a bridge that safely and easily guides us to the user authentication center.
### The Supported SSO Protocols
- SAML
- OIDC
- Oauth2.0
- Restful (insureMO Standard)
### The Supported Platforms and Applications
- OKTA
- Microsoft Entra ID
- ADFS
- AUTH0
- Cognito
- Keyloak
- GIMO Member
- Customer User Applications…
## Basic UI Operations
### Entrance
- Click **Sign in** to log in to [insureMO Portal](https://portal.insuremo.com/) with your personal account.
info
If you do not have a personal insureMO account, click **Sign up** to register one.
- At the top of the home page, click **Catalog**.
- On the Catalog page, in the left pane under **Utility & AI**, click **IAM**. You will find the **SSO Config** card. Click it and you will see the **API Details** and **Setting**.
- For creation and other actions, you need to click **Setting** to go to the **SSO Config** page.
- This will navigate to the main SSO configuration settings page where you can see the introduction of SSO and manage the service.
## How to Config SSO
- Click **How to config SSO**, you can select the environment and fill in your information in the upper panel and click **Generate**.
- You'll see the SSO configuration method that works for you below.
note
After configuring the IDP side, please provide the App Federation Metadata URL to the insureMO side for configuration.
insureMO tenant admin please go to **SSO card-> SSO config** to complete the configuration on the Service Provider side.
## SSO Configuration
### Create
- Click **Create SSO Config** on the SSO configuration console.
- Fill in the basic config information and click **Next**.
- In the config details, a config template will be generated for you. Replace the content with your relevant information, and click **Submit** to complete the creation.
### Edit
- Click **Edit** next to a particular record to edit the configuration.
* Config the sync_user_api:
after user login via sso, if you want to sync the user to our platform urp or GIMO app urp, you can set the sync user api like this:
1. Container platform urp :http://urp-v2-service/urpv2/account/sso/sync
2. GIMO APP urp :http://urp.platform/public/users/v1/sso/sync?role_policy=set_default_role
For Example：
```
{
"oidc": {
"client_id": "xARRposAjmPEV0TGAbAWvSKzJj0QwVvl",
"client_secret": "5d1-EMH************LAD4p27",
"authorization_api": "https://dev-wxexzn1gvkpz4a1v.us.auth0.com/authorize",
"sync_user_api": "http://urp-v2-service.mo-fo/urpv2/account/sso/sync",
"host": "https://dev-wxexzn1gvkpz4a1v.us.auth0.com/",
"username_param": "user_metadata.profile.auth0_user_id",
"redirect_uri": "https://portal.insuremo.com,https://ptdev.insuremo.com",
"userinfo_api": "https://dev-wxexzn1gvkpz4a1v.us.auth0.com/userinfo",
"token_api": "https://dev-wxexzn1gvkpz4a1v.us.auth0.com/oauth/token",
"scope": "openid email profile",
"insuremo_client_id": "tttdfsa"
}
}
```
### Delete
- Click **Delete** next to a particular record to delete the configuration.
### Test
- After the SSO configuration is created successfully, you can verify whether the current configuration is available through a test.
- Click **Test** next to a particular record to test the configuration.
- There are different test methods for different auth types:
1. `okta_oauth2`
This will navigate to OKTA's login page. If the user logs in successfully, the configuration is available.
2. oidc
This will navigate to the corresponding identity provider's login page. If the user logs in successfully, the configuration is available.
3. cognito
insureMO allows you to verify whether the token information from cognito is valid.
- Fill in your token in the pop-up test panel and click **Test**.
- In the pop-up **Online Test** page, the information required for the request to validate the token interface is generated based on the previous steps. After clicking the **Test**, if the token is valid, the user information corresponding to this token will be generated on the right.
4. saml
This will navigate to Microsoft Entra ID's login page. If the user logs in successfully, the configuration is available.
5. rest
This type is a standard for insureMO, allowing the CAS service to connect to different user sources for the username and password verification.
- Fill in your personal information in the test panel that pops up and click **Test**.
- In the pop-up **Online Test** page, the information required for the request to get the token interface is generated based on the previous steps. After clicking the **Test**, the corresponding token information will be generated on the right.
### SSO Developer Guide
#### Case 1: Login via External user service (Rest)
1. The external user service need to provides API according to CAS requirements. CAS calls the external user service through the Restful API to verify the user password. The parameters that will be passed are as follows:
```
curl --location --request POST 'http://user-mgmt-service.insuremo/account/signin'
--header 'Content-Type: application/json'
--data-raw
'{"name":"xxxx","password":"132xxxxxxdv!","tenantCode":"insuremo"}'
```
The format of the data returned after calling the user service is as follows:
accountName，email,tenantCode are required
```json
{
"body":"Check password success",
"data":{
"accountName":"xxxx",
"email":"xxxx@insuremo.com",
"mobile":"＋123xxxx123",
"tenantCode":"insuremo",
"tenantLockTimes":0,
"loginStatus":"1",
"autoUnlockTime":1800,
"accountLockNotifyFlg":""
},
"returnCode":"RC-00001"
}
```
The error is as follows:
```json
{
"data": {
"accountName": "xxxx",
"email": "xxxx@insuremo.com",
"mobile": "+153xxxx092",
"tenantCode": "insuremo",
"tenantLockTimes": 0,
"loginStatus": "",
"autoUnlockTime": 1800,
"accountLockNotifyFlg": ""
},
"errors": "CheckPassword error,password not right",
"returnCode": "RC-00099"
}
```
2. Configure in the SSO Card
if you have a new client,please go to **SSO Card->SSO Config** and config it,follow the web page guide.
- After the configuration is complete, directly use the interface to obtain the Token. The incoming client ID needs to be changed as follows:
- It's a must to add parameter: `x-mo-client-id`: member.
- You can add any parameter in JSON format to `Extend_params`, and CAS will store it temporarily for you to facilitate the subsequent use.
```
curl --location --request POST
'https://portal.insuremo.com/cas/get-token'
--header 'Content-Type: application/json'
--header 'x-mo-client-id: member'
--header 'Authorization: Bearer jqmUVqXlSla6Q4E-rhTZ0w'
--data-raw '{
"username":"REP0003","password":"dfsxxxxxj43","tenant_code":"tsubaddw","extend_params":[{"name":"testkey","value":"testparam"}]}'
```
- Authenticate user to identity and obtain additional parameters through the following API:
```
curl --location --request POST 'https://portal.insuremo.com/cas/validate-token'
--header 'Authorization: Bearer dfsadsafdesfds'
Response:
{
"user_name": "xxxx@insuremo.com",
"tenant_code": "gimo",
"status": "SUCCESS",
"accountExpireDate": "2028-01-31T00:00:00Z",
"extend_params": [
{
"name": "testkey",
"value": "testparam"
}
],
"email": "xxxx@insuremo.com"
}
```
#### Case 2: Customer Applications/UIs want to login via SAML or OIDC Identity Providers
The CAS service has integrated Microsoft Entra ID (AZURE AD), ADFS, OKTA, Cognito,Auth0 and other platforms through the SAML/OIDC protocol.
With the help of cas service, the applications could easily integrate with all these IDPs, only need to call CAS by Restful APIs.
**SAML integration**
**OIDC Intergration**
1. Config the SAML/OIDC IDP in SSO Card
* Follow the guide before, and remember the auth type and client ID
2. Develop APIs to redirect cas and the callback APIs after user login (SAML&OIDC the same process)
1. one API in step 2 redirect to cas
* OIDC API: `https://portal.insuremo.com/cas/sso/auth?tenant_code=mytenantcode&auth_type=oidc&client_id=mytenantcode&redirect_uri=https://myuiapi/gettokenbyexchangecode`
* SAML API: `https://portal.insuremo.com/cas/sso/auth?tenant_code=mytenantcode&auth_type=saml&client_id=mytenantcode&redirect_uri=https://myuiapi/gettokenbyexchangecode`
2. one API in step 13 to get token via exchange code
* The integrator needs to use this exchange code to call CAS in the background to obtain the real user information and token.
* Please refer to the following API about consume exchange code.
| Name | Desc | Example |
|--------------|-----------------------------------------------------------------------------------------------------|----------------------------------------------|
| tenant_code | TenantCode agreed by both parties | testtenant3809 |
| redirect_uri | The URL received by the project party. They get the request and receive the exchange_code parameter | |
| auth_type | saml,oidc | saml |
| client_id | If a tenant has multiple ADFS, use client_id to distinguish them | clientid1 |
##### SAML login initiated from IDP. The whole process is as follows:
###### 1: Customer login.
Select the current site on the customer's ADFS page.
###### 2: The login interface of the current client's IDP configuration is provided by the integrator, as follows:
curl --location --request POST 'https://myloginpage/saml/acs'\\
form `SAMLResponse="PHNhbWxwOlJlc3BvbnNlIElEPSYXNpcz....0aW9uPjwvc2FtbHA6UmVzcG9uc2U+`
###### 3: After receiving the login request from IDP, the integrator (usually the front end) calls the following interface of Container and sends SAMLResponse and tenant_code through formdata.
```
curl --location --request POST 'https://dev.insuremo.com/cas/saml/acs'
--form 'SAMLResponse="PHNhbWxwOlJlc3BvbnNlIElEPSYXNpcz....0aW9uPjwvc2FtbHA6UmVzcG9uc2U+"'
--form 'tenant_code="testchen3809"'
```
Container returns the token of the current user, where there is no username. When required by the integrator, the username needs to be replaced with the token.
```
Response：
{
"access_token": "bbmkLEg7TmmeKuMgDv5Q_A",
"expire_in": 7216,
"message": "",
"retry_times": 0
}
```
The interfaces for exchanging Token for user information are as follows:
```
curl --location --request POST 'https://portal.insuremo.com/cas/validate-token'
--header 'Authorization: Bearer JbiSwyWaSNWUEI85eTmH0w'
Response：
{
"user_name": "xxxx",
"tenant_code": "insuremo",
"status": "SUCCESS"
}
```
#### Customer configures ADFS/AZURE AD
##### To configure the ADFS server, follow the following process:
###### *A*. Configure Relying party trusts.
Import the Metadata file on the SP side provided by InsureMo, the address is: ``. Download it directly with the browser, or configure the URL directly. Each environment is different, adjust `` according to the actual domain address.
Import metadata file for application
Finish it in the next step
###### B. Configure claim rule
Right-click on the trusts to edit rule
Add send claim rule
Add incoming rule
###### C. Export the ADFS metadata file
This metadata is the ADFS IDP metadata.
##### Follow the following process to configure the AZURE AD
How to Config the SAML SSO in AZURE AD
###### Add a new application:
###### Set up the single sign on for the application
The identifier id (Entity ID) should
be: ``
Reply URL should be: ``
Relay State should be: valpas
After config, please provide the Federation Metadata XML to the insureMO team to complete the configuration.
###### C.give the metadata file URL to insureMO team, insureMO team do the SSO Configuration in SSO Configuration card
#### Test
##### AZURE AD Test the sso
1. IDP int test
1. Sp init test, go to
page: ``
,input the tenant code valpas, click **AZURE AD**
1. The `redirect_url` should be change to your homepage.
#### Post-maintenance of SAML
##### Change the default public key and private key: (Please arrange a suitable time,for SSO will be interrupted during this process)
If the public and private keys need to be replaced next time, the steps are as follows, and it is recommended to supplement the subsequent documentation on the project to prevent trouble caused by personnel replacement.
1. Generate RSA private key file
2. Use the private key to generate a certificate, and specify the period here, then you can see the content of the public key when you open the certificate.
3. Assign the private key and public key content to the configuration center
4. Restart CAS to get new metadata (the metadata contains public key information)
5. After modifying the metadata according to the requirements of the project team, provide it to the customer.
note
Links to external websites and third-party features contained in this document are for demonstration purposes only. Such links and features do not constitute our endorsement or recommendation. We neither control nor assume responsibility for the content, services, or privacy practices of these third parties. Users are advised to independently review the respective terms and privacy policies.
# FAQ
* Q: If I want to let the user login insureMO via my user service, how could I connect to the CAS service ?
* A: External user services that support Restful interfaces can be added to CAS,please go to External user service provides API according to CAS requirements.