Skip to main content
Skip table of contents

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.

  1. Creating an Application on MonoSign

  2. 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.

Option -1 Passwordless Login

Option - 2 Login with Password

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.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.