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://api.monofor.com`	Monosign API Service URL in the “Rest API Information“ image as shown.
MonoSign-AppId	3adfa5ce-1a5a-47b7-a42a-e8217efda62d	MonoSign-AppId for API Integration in the “Rest API Information“ image as shown.
Monosign-AppKey	a0ca9849-42ff-47be-af6f-28eecb1e5017	MonoSign-AppKey for API Integration in the “Rest API Information“ image as shown.

The information shown above is an example. This information will change based on your domain

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 information below. 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://api.monofor.com/v1.3/signin`
Header	MonoSign-AppId: `From Custom Application Created in the first section` MonoSign-AppKey: `From Custom Application Created in the first section` Rest API Information 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.

JSON

curl --location --request POST 'https://api.monofor.com/v1.3/signin' \
--header 'MonoSign-AppId: 3adfa5ce-1a5a-47b7-a42a-e8217efda62d' \
--header 'MonoSign-AppKey: a0ca9849-42ff-47be-af6f-28eecb1e5017' \
--header 'Content-Type: application/json' \
--data-raw '{
  "callbackUrl": "https://custom-application-url",
  "type": 1
}'

The output of the request.

JSON

{
    "Code": 1,
    "Data": {
        "LoginUrl": "https://api.monofor.com/login/ea6955a6-7e0d-4768-a1a9-975a8003458a",
        "RegisterUrl": "https://api.monofor.com/register/ea6955a6-7e0d-4768-a1a9-975a8003458a",
        "ForgettenPasswordUrl": "https://api.monofor.com/passwordrecovery/ea6955a6-7e0d-4768-a1a9-975a8003458a",
        "LogoutUrl": "https://api.monofor.com/logout/ea6955a6-7e0d-4768-a1a9-975a8003458a",
        "AuthToken": "ea6955a6-7e0d-4768-a1a9-975a8003458a"
    },
    "Success": true
}

Request returns below information.

Property	Value
LoginUrl	`https://api.monofor.com/login/ea6955a6-7e0d-4768-a1a9-975a8003458a`
RegisterUrl	`https://api.monofor.com/register/ea6955a6-7e0d-4768-a1a9-975a8003458a`
ForgettenPasswordUrl	`https://api.monofor.com/passwordrecovery/ea6955a6-7e0d-4768-a1a9-975a8003458a`
LogoutUrl	`https://api.monofor.com/logout/ea6955a6-7e0d-4768-a1a9-975a8003458a`
AuthToken	`ea6955a6-7e0d-4768-a1a9-975a8003458a`

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

After successfully signing in, the user will be redirected to your custom application URL with the authentication token as shown.

JSON

https://custom-application-url?auth_token=6212baac-51b4-4285-8ea2-324f3ceda201

The authentication token sent in the URL will be used to get users information.

When the user signs into the application, the system will create a session on the SSO application and the Custom application as shown.

2.2 - GET SignIn Method

Monosign sign-in API gives details 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://api.monofor.com/v1.3/signin/{{authenticationToken}}

The authentication token is provided when signin method is triggered

Header

MonoSign-AppId: From Custom Application Created in the first section

MonoSign-AppKey: From Custom Application Created in the first section

Content-Type: application/json

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://api.monofor.com/v1.3/signin/{{authenticationToken}}' \
--header 'MonoSign-AppId: 3adfa5ce-1a5a-47b7-a42a-e8217efda62d' \
--header 'MonoSign-AppKey: a0ca9849-42ff-47be-af6f-28eecb1e5017' \
--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.com",
        "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"
            }
        },
        "Groups": [
            {
                "Id": "2dc714cb-9361-465f-bc2a-666c6e3315b0",
                "Name": "Monosign MonoDev",
                "Title": "MonoSign MonoDev",
                "Source": "monofor"
            },
            {
                "Id": "48a9f8f8-ece4-4473-948f-f3a32fcd4b79",
                "Name": "Monosign VPN Users",
                "Title": "MonoSign VPN Users",
                "Source": "monofor"
            },
            {
                "Id": "d3778d58-b333-4ac1-a6ca-9e00f95891c5",
                "Name": "Domain Users",
                "Title": "Domain Users",
                "Source": "monofor"
            },
            {
                "Id": "faf816a1-5194-4d07-b99c-d439b2afb5b7",
                "Name": "Monosign SAML Users",
                "Title": "MonoSign SAML Users",
                "Source": "monofor"
            },
            {
                "Id": "9628b54c-2c35-4439-8e25-c518876c641a",
                "Name": "Splunk Admins",
                "Title": "Splunk Admins",
                "Source": "monofor"
            },
            {
                "Id": "38857477-e3b8-417e-8219-c3614fbd0602",
                "Name": "k8s Admins",
                "Title": "k8s Admins",
                "Source": "monofor"
            },
            {
                "Id": "631e3b0a-8589-45d4-913a-a034632bdc73",
                "Name": "Monosign Prod Admins",
                "Title": "Monosign Prod Admins",
                "Source": "monofor"
            },
            {
                "Id": "99758cc8-a14f-48f2-ae25-600420f81cb0",
                "Name": "OWA Users",
                "Title": "OWA Users",
                "Source": "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, Profile and User Groups details can be found in this output.

Profile can be used to display user information in the custom application. User Groups can be used to give permissions based on the groups in the custom application.

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://api.monofor.com/v1.4/users/logout`
Header	MonoSign-AppId: `From Custom Application Created in the first section` MonoSign-AppKey: `From Custom Application Created in the first section` Rest API Information 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://api.monofor.com/v1.4/users/logout' \
--header 'MonoSign-AppId: 3adfa5ce-1a5a-47b7-a42a-e8217efda62d' \
--header 'MonoSign-AppKey: a0ca9849-42ff-47be-af6f-28eecb1e5017' \
--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"
}'

You can use one of the key value to logout user.

sessionId → It will logout the user using the specific session id. It will end the specific session in the application.
applicationUserId → It will logout the user using the user’s application id. It will end all sessions that the user has in the application.
userId → It will logout the user using the user’s id. It will end all sessions that the user has in the application.

The output of the Request

JSON

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

The user is now signed out from the Custom Application.

If the user sign-in request triggers with the same authentication token, the response will be as shown below.

CODE

{
    "Message": "Error",
    "InternalMessage": "This session is expired. Please login again.",
    "Code": 3,
    "Success": false
}

You can see session details in MonoSign below example.