How to Implement Microsoft Authenticator TOTP through an API

Estimated reading: 3 minutes 184 views

User enrolment and Authentication can be done for Microsoft Authenticator TOTP through an API.

Below are the steps for the same.

Authenticate a user

After calling the authentication API, examine the response and look for the ‘AuthenticationEnrollmentRequest’ property within the ‘AuthenticationResponse’ object.” (highlighted below)

2. If user is not already enrolled, enroll the user to Microsoft Authenticator app

Generate a QR code to be scanned by Microsoft Authenticator app
- Via image (QR code)
- Via bytes array which represents image (QR code)
Validate OTP for successful enrolment of the user in VisualGuard.

Step1: Authenticate a user with Visual-Guard IdentityServer API

VG Authenticator

Please find below the example responses for authentication procedure

{
    "error": "invalid_request",
    "error_description": "Failure, MFA_AuthenticationRequired",
    "VGAuthenticationStatus": "Failure, MFA_AuthenticationRequired",
    "AuthenticationMethod": "None",
    "VGResponse": {
        "RequestId": "de908cdd-1e9f-47f4-a857-1737eb6912b4",
        "AuthenticationState": {
            "Status": 134217729,
            "IsFailed": true,
            "IsNotApproved": false,
            "IsCanceled": false,
            "IsCredentialInvalid": false,
            "IsUserNotAuthorized": false,
            "IsUserAccountExpired": false,
            "IsUserAccountNotYetAvailable": false,
            "IsUserAccountDisabled": false,
            "IsUserAccountLocked": false,
            "IsLastBadLogin": false,
            "IsLastGraceLogon": false,
            "IsPasswordExpired": false,
            "IsPasswordSecure": true,
            "IsUserAccountLockedOut": false,
            "IsUserAccountWillBeLockedOut": false,
            "MustChangePasswordAtNextLogon": false,
            "IsMFAWaitingUserAction": false,
            "IsMFAAuthenticationRequired": true,
            "IsMFATimeOut": false,
            "HasUserAccountMissingEmail": false,
            "HasUserAccountMissingMobilePhone": false,
            "IsMFAEnrollmentRequired": false
        },
        "AuthorizationState": {
            "Status": 1,
            "IsFailed": true,
            "IsCanceled": false,
            "IsUserNotFound": false,
            "IsUserNotAuthorized": false,
            "IsVersionNotCompatible": false
        },
        "AuthenticationResponse": {
            "RequestId": "de908cdd-1e9f-47f4-a857-1737eb6912b4",
            "Identity": {
                "Name": "tt29",
                "AuthenticationType": "VGUSER",
                "IsAuthenticated": true
            },
            "AuthenticationEnrollmentRequest": {
                "Id": "de908cdd-1e9f-47f4-a857-1737eb6912b4",
                "EnrollmentUrl": "http://localhost:5000/mfa/enroll/de908cdd-1e9f-47f4-a857-1737eb6912b4",
                "TransportModes": [
                    1,
                    4
                ],
                "DisplayTransportModes": [
                    "SMS",
                    "MicrosoftAuthenticator"
                ]
            },
            "MFAAvailables": [
                {
                    "RequestId": "de908cdd-1e9f-47f4-a857-1737eb6912b4",
                    "TransportMode": 2,
                    "AuthenticationMode": 1,
                    "DestinationDisplay": "m****************s@g****.com",
                    "ExpirationTime": 90,
                    "AuthenticationModeDisplay": "Link",
                    "TransportModeDisplay": "Email",
                    "Id": "3e6fe21b-6985-4938-b89d-5af6a98339ef"
                },
                {
                    "RequestId": "de908cdd-1e9f-47f4-a857-1737eb6912b4",
                    "TransportMode": 2,
                    "AuthenticationMode": 2,
                    "DestinationDisplay": "m****************s@g****.com",
                    "ExpirationTime": 60,
                    "AuthenticationModeDisplay": "OTP",
                    "TransportModeDisplay": "Email",
                    "Id": "dee54c8b-9191-4bfd-9ca2-bddc76a30b5b"
                }
            ],
            "Status": 134217729,
            "IsFailed": true,
            "IsNotApproved": false,
            "IsCanceled": false,
            "IsCredentialInvalid": false,
            "IsUserNotAuthorized": false,
            "IsUserAccountExpired": false,
            "IsUserAccountNotYetAvailable": false,
            "IsUserAccountDisabled": false,
            "IsUserAccountLocked": false,
            "IsLastBadLogin": false,
            "IsLastGraceLogon": false,
            "IsPasswordExpired": false,
            "IsPasswordSecure": true,
            "IsUserAccountLockedOut": false,
            "IsUserAccountWillBeLockedOut": false,
            "MustChangePasswordAtNextLogon": false,
            "IsMFAWaitingUserAction": false,
            "IsMFAAuthenticationRequired": true,
            "IsMFATimeOut": false,
            "HasUserAccountMissingEmail": false,
            "HasUserAccountMissingMobilePhone": false,
            "IsMFAEnrollmentRequired": false
        },
        "Error": {
            "Message": "",
            "StackTrace": ""
        },
        "AuthorizationStatus": "Failure",
        "AuthenticationStatus": "Failure, MFA_AuthenticationRequired",
        "VGToken": ""
    }
}

As shown above response contains AuthenticationResponse.AuthenticationEnrollmentRequest section. This section will contain all information for enrolment fields if not enrolled already. Ex. MicrosoftAuthenticator, SMS etc

Step 2: Enrolment of the field – MicrosoftAuthenticator

a) Generate QR code to be scanned by Microsoft Authenticator.

Visual Guard IdentityServer provides 2 different methods to get the QR code for enrolment of Microsoft Authenticator – TOTP. You can use any of them depending on the requirements and feasibility.

Method 1). EnrollUserToMicrosoftAuthenticatorByImage

ByImage

Here, you need to pass the authentication requestId which is received in the response in step 1.

{{VGIdentityServerUrl}}/api/MFAEnrollment/EnrollUserToMicrosoftAuthenticatorByImage?requestId=5162e29f-30ab-456c-abb5-9065143ec071.

On executing this method, it will return the image. And this image is QR Code which will be scanned by Microsoft Authenticator app.

Method 2). EnrollUserToMicrosoftAuthenticatorByBytes

ByBytes

Here, you need to pass the authentication requestId which is received in the response in step1.

{{VGIdentityServerUrl}}/api/MFAEnrollment/EnrollUserToMicrosoftAuthenticatorByBytes?requestId=5162e29f-30ab-456c-abb5-9065143ec071

On executing this method, it will return the image bytes (byte array). These byte array can be used to generate image, and this image is QR Code which will be scanned by Microsoft Authenticator app.

b) Validation of secure code for enrollment\registration.

Enrollment/Registration

{{VGIdentityServerUrl}}/api/MFAEnrollment/ValidateMicrosoftTOTP

Once the QRCode is scanned via Microsoft Authenticator app, secure code (OTP) needs to be validated for successful enrolment\registration, Where you need to pass authentication requestId and secure code generated by the Microsoft Authenticator app.