Custom Application REST API Integration

This document explains how to implement MonoSign with a Custom Application. It covers the Single Sign-On.

📑 Instructions

This documentation contains 2 main steps for integration.

Creating an Application on MonoSign
Configuration of the Single Sign-On for the Custom Application

1- Creating an Application on MonoSign

Create your application on MonoSign and configure your access policy. Once you create, click “Keys” and add a new Access Key for REST API Key for access.

We will need this information for the Custom application’s sign-in integration.

Property	Value	Description
Base API URL	https://monosign-api.domain.com	MonoSign API Service URL
MonoSign-AppId	0000000-0000-0000-000000000000	MonoSign-AppId for API Integration
Monosign-AppKey	0000000-0000-0000-000000000000	MonoSign-AppKey for API Integration

The application needs to have access to groups. If it is not configured yet, the application can be edited by going to the “Source, Provider and Profile” tab and configuring User Group Access Type “Assigned Users and Defined Sources”. It means this application can access users’ groups when they are signed in.

Property	Description	Options
User Access Type	Defines which Users will access this application.	Only Assigned Users All Users
User Group Access Type	Defines the application’s user group access	Only Assigned Users Assigned Users and Defined Sources All Users
Profile Access Type	Defines Application’s user’s profile access	Restricted - Only restricted user profile attributes All - All user profile attributes

2- Configuration Single Sign-On on Custom Application

You must add your Rest API methods to your API and Frontend application.

The following information is needed for your configuration file or environment file.

POST User SignIn to MonoSign
GET User SignIn information
POST User Logout from Custom application and MonoSign

2.1- POST SignIn Method

MonoSign Rest API is supporting SigIn operation with the below information. So when the users try the login custom application with https://custom-app-url you need to use the below API to get “LoginUrl” from MonoSign Rest API and redirect the user Login to MonoSign.

Property	Values
Type	POST
URL	https://monosign-api.domain.com/v1.3/signin
Header	MonoSign-AppId: MonoSign-AppKey: Content-Type: application/json
Body(Raw:Json)	JSON `{ "callbackUrl": "https://custom-application-url", "type": 1 }`

Example :

You can call API with your programming language. The below cURL example shows what the output of the Rest API request is.

BASH

curl --location --request POST 'https://monosign-api.monofor.dev/v1.3/signin' \
--header 'MonoSign-AppId: 6fd40377-79a4-4728-99bd-e7d95ed881ce' \
--header 'MonoSign-AppKey: 50e46448-8436-48d5-9936-76adc2a1192e' \
--header 'Content-Type: application/json' \
--data-raw '{
  "callbackUrl": "https://www.monofor.com",
  "type": 1
}'

The output of the request.

JSON

{
    "Code": 1,
    "Data": {
        "LoginUrl": "https://monosign.monofor.dev/login/d875a40a-d002-4d35-8a5e-ab41733096af",
        "RegisterUrl": "https://monosign.monofor.dev/register/d875a40a-d002-4d35-8a5e-ab41733096af",
        "ForgettenPasswordUrl": "https://monosign.monofor.dev/passwordrecovery/d875a40a-d002-4d35-8a5e-ab41733096af",
        "LogoutUrl": "https://monosign.monofor.dev/logout/d875a40a-d002-4d35-8a5e-ab41733096af",
        "AuthToken": "d875a40a-d002-4d35-8a5e-ab41733096af"
    },
    "Success": true
}

Request returns below information.

Property	Value
LoginUrl	`https://monosign.monofor.dev/login/d875a40a-d002-4d35-8a5e-ab41733096af`
RegisterUrl	`https://monosign.monofor.dev/register/d875a40a-d002-4d35-8a5e-ab41733096af`
ForgettenPasswordUrl	`https://monosign.monofor.dev/passwordrecovery/d875a40a-d002-4d35-8a5e-ab41733096af`
LogoutUrl	`https://monosign.monofor.dev/logout/d875a40a-d002-4d35-8a5e-ab41733096af`
AuthToken	`d875a40a-d002-4d35-8a5e-ab41733096af`

Now you can redirect users' Login requests to “LoginUrl”. Users will see the below page when redirected.

After successfully signing in, the user will redirect to your custom application page.

2.2- GET SignIn Method

MonoSign Rest API gives detail about details users' sessions and profile information after successfully signing in. In addition, you can find the details about GET SignIn methods.

Property

Values

Type

GET

URL

https://monosign-api.domain.com/v1.3/signin/authtoken

Header

MonoSign-AppId:

MonoSign-AppKey:

Content-Type: application/json

AuthToken is provided when the POST method is requested, which is explained here.

Example :

You can call API with your programming language. The below cURL example shows what the output of the Rest API request is.

CODE

curl --location --request GET 'https://monosign-api.monofor.dev/v1.3/signin/d875a40a-d002-4d35-8a5e-ab41733096af' \
--header 'MonoSign-AppId: 6fd40377-79a4-4728-99bd-e7d95ed881ce' \
--header 'MonoSign-AppKey: 50e46448-8436-48d5-9936-76adc2a1192e' \
--header 'Content-Type: application/json' \
--data-raw ''

The output of the Request

JSON

{
    "Code": 1,
    "Data": {
        "UserId": "bbce41c7-f363-4724-999e-16c3d2293f78",
        "ApplicationUserId": "4a89376b-5294-4284-bc66-83c17ba74d25",
        "UserName": "john.smith",
        "Email": "john.smith@monofor.dev",
        "Session": {
            "SessionId": "0b12a388-e60e-4a78-ba2b-7b5abe4dba94",
            "UserId": "bbce41c7-f363-4724-999e-16c3d2293f78",
            "ApplicationUserId": "4a89376b-5294-4284-bc66-83c17ba74d25",
            "StartDate": "2022-10-09T18:56:50.9208496",
            "UpdatedDate": "2022-10-09T19:03:45.6591353Z",
            "ApplicationId": "00000000-0000-0000-0000-000000000000",
            "Application": null,
            "ExpirationDate": "2022-10-09T19:33:45.6591343Z",
            "IsLocked": false,
            "LockMessage": "",
            "LogoutUrl": null,
            "IsMfaVerified": false,
            "IsExpired": false,
            "BrowserName": null,
            "BrowserVersion": null,
            "OperatingSystem": null,
            "DeviceType": 0,
            "DeviceBrand": null,
            "DeviceModel": null,
            "DeviceName": null,
            "Location": null,
            "User": null,
            "IsTwoFactorVerified": false,
            "IsTwoFactorRequired": false,
            "LocationInfo": null,
            "UserIp": null
        },
        "Profile": {
            "ProfileId": "6a2790f2-a02a-413b-9535-2c3b0aab8fa1",
            "IsRequireUpdate": false,
            "Values": {
                "Title": "IAM Engineer",
                "Department": "Identity Access and Management",
                "FormattedName": "John Smith [MonoFor.Dev]",
                "LastName": "Smith",
                "FirstName": "John",
                "Company": "MonoFor"
            }
        },
        "SourceName": "monofor-dev",
        "SourceTitle": "MonoFor.Dev",
        "SourceUserName": "",
        "State": 1,
        "IsActive": true,
        "Culture": "en",
        "MfaRequired": false,
        "PasswordChangeRequired": false,
        "PasswordChangeType": 0,
        "TimeZone": "",
        "IsFavorite": false,
        "ApplicationId": "00000000-0000-0000-0000-000000000000",
        "ApplicationName": null,
        "ApplicationTitle": null,
        "CreatedDate": "0001-01-01T00:00:00",
        "ExpirationDate": "2023-10-09T18:55:42.353",
        "IsExpired": false
    },
    "Success": true
}

UserId, SessionId, ApplicationId and Profile details can be found in this output.

UserId, SessionId and ApplicationId can be used for the Logout request.

2.3- POST Logout Method

MonoSign Rest API POST Logout method is used when the user logs out from a custom application and if you want users to log out from MonoSign.

You can find the details about GET SignIn methods.

Property	Values
Type	POST
URL	https://monosign-api.domain.com/v1.4/users/logout
Header	MonoSign-AppId: MonoSign-AppKey: Content-Type: application/json
Body(Raw:Json)	JSON `{ "sessionId": "SessionId", "applicationUserId": "ApplicationUserId", "userId": "UserID" }`

Example :

You can call API with your programming language. The below cURL example shows what the output of the Rest API request is.

CODE

curl --location --request POST 'https://monosign-api.monofor.dev/v1.4/users/logout' \
--header 'MonoSign-AppId: 6fd40377-79a4-4728-99bd-e7d95ed881ce' \
--header 'MonoSign-AppKey: 50e46448-8436-48d5-9936-76adc2a1192e' \
--header 'Content-Type: application/json' \
--data-raw '{
  "sessionId": "0b12a388-e60e-4a78-ba2b-7b5abe4dba94",
  "applicationUserId": "4a89376b-5294-4284-bc66-83c17ba74d25",
  "userId": "bbce41c7-f363-4724-999e-16c3d2293f78"
}'

The output of the Request

JSON

{
    "Message": "User logged out successfully.",
    "Code": 1,
    "Data": false,
    "Success": true
}

You can see session details in MonoSign below example.