How to Using an External Authenticator through Monosign

This document describes how an Identity Provider (IdP) can integrate with Monosign to perform multi-factor authentication (MFA) using an external authenticator.

Overview

In this integration model, the Identity Provider (IdP) is responsible for performing primary authentication and making the final access decision. Monosign acts as the central authentication service, orchestrating the authentication workflow and collecting the user's approval or rejection through a registered authenticator application.

To initiate an authentication request, the user must already exist in Monosign and have at least one active authenticator associated with the account.

When a user attempts to sign in to an application integrated with the Identity Provider, the IdP first validates the user's primary credentials. If additional authentication is required, the IdP initiates an authentication request through Monosign.

Monosign identifies the user's registered authenticator and delivers the authentication request to the authenticator application. The user can then approve or reject the authentication request using the application.

After the user responds, Monosign stores the authentication result and exposes it through its APIs. The Identity Provider periodically checks the authentication request status and uses the returned result to determine whether access should be granted or denied.

The following sections describe the API calls required to implement this authentication workflow.

1. Authenticate the User and Retrieve User Information

The first step of the authentication workflow is to authenticate the user against Monosign.

Upon successful authentication, Monosign returns the UserId and SessionId, which are required for the subsequent API calls.

URL: {{Api Url of the environment}}/v1.4/users/login

Headers:
Monosign-AppId: {{AppId Created on Monosign for External Idp}]} - Such as Access Manager
Monosign-AppKey: {{AppKey Created on Monosign for External Idp}]} - Such as Access Manager

Method: POST

Request Body:

{
  "userName": "{UserName}",
  "password": "{Password}",
  "isPasswordEncrypted": false,
  "permanent": true
}

Response:
{
    "Message": "Login successful.",
    "Code": 10188,
    "Data": {
        "UserId": "9ca71310-eddf-4976-b684-f9204fd62b74",
        "Session": {
            "SessionId": "a7bc6ea0-360b-49fe-84b8-f3a31cb44cc3",
            ...
        },
        ...
    },
    "Success": true
}

After a successful authentication, the following values should be retained for subsequent API calls:

UserId – Used to retrieve the user's registered authenticator information.
SessionId – Represents the current authentication session and must be included in subsequent requests using the Monosign-SessionId request header.

2. Retrieve User Authenticator Information

Before initiating an authentication request, the Identity Provider (IdP) must retrieve the user's registered authenticators from Monosign.

This operation returns all active authenticators associated with the user. Since a user may have multiple authenticators, the Identity Provider must identify the appropriate authenticator before initiating the authentication request.

URL: {{Api Url of the environment}}/v1.3/mfa/options/{UserId}

Headers:
Monosign-AppId: {{AppId Created on Monosign for External Idp}]} - Such as Access Manager
Monosign-AppKey: {{AppKey Created on Monosign for External Idp}]} - Such as Access Manager

Method: GET

Response:
{
    "Message": "There are active authenticators for this user.",
    "Code": 10131,
    "Data": [
        {
            "Id": "b47d6b96-2adc-412b-b6c8-f70eb2017eca",
            "AuthenticatorId": "d15ff26c-5e06-4d40-9a7c-8927ab47d783",
            "Title": "API Service Authenticator",
            "Name": "Service",
            ...
        },
        ...
    ],
    "Success": true
}

For authentication requests initiated through the external authentication service, the Identity Provider must select the authenticator whose Name property is "Service".

The Id value of the Service authenticator represents the UserAuthenticatorId and must be used when initiating the authentication request in the next step.

3. Initiate an Authentication Request

After obtaining the UserAuthenticatorId, the Identity Provider (IdP) can initiate a new authentication request through Monosign.

This operation creates a new authentication transaction associated with the user's registered authenticator. Monosign uses the provided UserAuthenticatorId to identify the appropriate authenticator and initiate the authentication request.

The user is then prompted through the authenticator application to either approve or reject the authentication request.

The user's decision is processed by Monosign and made available through its APIs.

If the user does not respond within the initial 30-second waiting period, the API returns a UsageId that uniquely identifies the authentication transaction. This value should be used to query the authentication status in the subsequent API calls.

URL: {{Api Url of the environment}}//v1.3/mfa/request/{UserAuthenticatorId}

Headers:
Monosign-AppId: {{AppId Created on Monosign for External Idp}]} - Such as Access Manager
Monosign-AppKey: {{AppKey Created on Monosign for External Idp}]} - Such as Access Manager
Monosign-SessionId: {{SessionId information copied from first request}}

Method: POST

Request Body:
{
    "userIp": "192.168.55.90"
}

After sending request, Monosign services wait 60 seconds to respond the request.
The reason behind it, if the user approves or reject within firt 5 second, API will respond the state of the push notification

1. If User Approves within 5 seconds

Response:
// Verified
{
    "Message": "Your MFA is verified. Please follow the instructions.",
    "Code": 10117,
    "Data": {
        "UserAuthRequestId": "00000000-0000-0000-0000-000000000000",
        "UsageId": "a76dc5ea-0981-4068-b67f-53be6666905c",
        "SessionId": "ce964229-1bd9-4ed3-9533-239c0af81b54",
        "UserId": "16736b04-b3c2-4c86-9a90-a92be54603f3",
        "RedirectUrl": null,
        "IsInteractive": false,
        "IsCompleted": true,
        "ExpirationDate": "0001-01-01T00:00:00"
    },
    "Success": true
}

// Declined
{
    "Message": "Your MFA is declined.",
    "Code": 10118,
    "Data": {
        "UserAuthRequestId": "00000000-0000-0000-0000-000000000000",
        "UsageId": "00000000-0000-0000-0000-000000000000",
        "SessionId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "RedirectUrl": null,
        "IsInteractive": false,
        "IsCompleted": false,
        "ExpirationDate": "0001-01-01T00:00:00"
    },
    "Success": false
}

The API responds "MFA Verified/MFA Declined" state by the below codes.
Code: 10117 -> MFA Verified
Code: 10118 -> MFA Declined

2. If User Does Not Approves within 60 seconds, the response will include usage Id.

{
    "Message": "Warning",
    "InternalMessage": "Waited 5 seconds for push notification but didn't get any answer. If you want to try it again, re-try the request with state.",
    "Code": 499,
    "Data": {
        "UserAuthRequestId": "00000000-0000-0000-0000-000000000000",
        "UsageId": "a76dc5ea-0981-4068-b67f-53be6666905c",
        "SessionId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "RedirectUrl": null,
        "IsInteractive": true,
        "IsCompleted": false,
        "ExpirationDate": "0001-01-01T00:00:00"
    },
    "Success": false
}

The usage id can be used to check MFA state of the current push notification.

The Idp should check the MFA state for every five seconds using below informations.

After the authentication request is created, Monosign keeps the request open for up to 5 seconds while waiting for the user to respond through the authenticator application.

If the user approves or rejects the authentication request during this period, the API immediately returns the final authentication result.

Authentication Approved

Response Code: 10117

The user has approved the authentication request. The Identity Provider may proceed with granting access to the user.

Authentication Rejected

Response Code: 10118

The user has rejected the authentication request. The Identity Provider should deny access to the user.

No Response Within the Initial 5 Seconds

If the user does not respond within the initial 60-second waiting period, the API returns a 499 response together with a UsageId.

The UsageId uniquely identifies the authentication transaction and must be used to query the authentication request status in the next step.

4. Check Authentication Request Status

If the user does not respond within the initial 5-second waiting period, Monosign returns a UsageId that uniquely identifies the authentication transaction.

The Identity Provider (IdP) should use this UsageId to query the current status of the authentication request.

The authentication request remains valid for 60 seconds. During this period, the Identity Provider may periodically poll the authentication request status using the returned UsageId.

The polling process may continue until one of the following conditions is met:

The user approves the authentication request.
The user rejects the authentication request.
The 60-second validity period expires.

If the authentication request expires without user interaction, the authentication process should be considered unsuccessful, and the Identity Provider should deny access or restart the authentication flow, depending on the application's authentication policy.

Parameters

URL: {{Api Url of the environment}}//v1.3/mfa/request/{{UserAuthenticatorIdCopiedFromTheSecondSecuest}}/{{UserAuthenticatorUsageIdFromPreviousResponse}}

Headers:
Monosign-AppId: {{AppId Created on Monosign for External Idp}]} - Such as Access Manager
Monosign-AppKey: {{AppKey Created on Monosign for External Idp}]} - Such as Access Manager
Monosign-SessionId: {{SessionId information copied from third request}}

Method: POST

Request Body:
{
    "userIp": "192.168.55.90"
}

If User Approves within 5 seconds

Response:
// Verified
{
    "Message": "Your MFA is verified. Please follow the instructions.",
    "Code": 10117,
    "Data": {
        "UserAuthRequestId": "00000000-0000-0000-0000-000000000000",
        "UsageId": "a76dc5ea-0981-4068-b67f-53be6666905c",
        "SessionId": "ce964229-1bd9-4ed3-9533-239c0af81b54",
        "UserId": "16736b04-b3c2-4c86-9a90-a92be54603f3",
        "RedirectUrl": null,
        "IsInteractive": false,
        "IsCompleted": true,
        "ExpirationDate": "0001-01-01T00:00:00"
    },
    "Success": true
}

// Declined
{
    "Message": "Your MFA is declined.",
    "Code": 10118,
    "Data": {
        "UserAuthRequestId": "00000000-0000-0000-0000-000000000000",
        "UsageId": "00000000-0000-0000-0000-000000000000",
        "SessionId": "00000000-0000-0000-0000-000000000000",
        "UserId": "00000000-0000-0000-0000-000000000000",
        "RedirectUrl": null,
        "IsInteractive": false,
        "IsCompleted": false,
        "ExpirationDate": "0001-01-01T00:00:00"
    },
    "Success": false
}

The API responds "MFA Verified/MFA Declined" state by the below codes.
Code: 10117 -> MFA Verified
Code: 10118 -> MFA Declined

If the response code 10117, the user is approved the push notification. Idp should grant access to user.
If the response code 10118, the user is declined the push notification. Idp should not grant access to user.
If the response code 499, the push notification was not responded to within 5 seconds. Idp can check multiple times in case of user decide within 30 seconds.