1. Identity Server Service definition
You can access to the definition
2. Configuring Visual-Guard Authentication Service
This guide provides a detailed walkthrough on how to establish a new authentication service for a Visual-Guard application.
Step 1: Launch Visual-Guard WinConsole
Begin by launching the Visual-Guard WinConsole. Please note that you will require administrator privileges to access the VGRepository.
Step 2: Choose the Application
Navigate through the VGRepository and select the application for which you wish to establish the new authentication service.
Step 3: Initiate Identity Client Configuration
Click on the “Configure Identity Client for Application” option. This action will open a new window that displays all existing “VG Identity Client for Application” services associated with the chosen application.
Step 4: Define a New Platform
Select the “New Platform” button. You will be presented with a variety of platform options, including:
- Web Application (supports Java, Asp.Net, etc.)
- SPA (Single Page Application)
- Native Application (compatible with Mobile/Desktop, Powerbuilder, PowerServer, etc.)
- Service Application (Machine to Machine)
Choose the platform that aligns with your application’s requirements.
Step 5: Configure the Identity Client
Each “VG Identity Client for Application” comprises several sections that require configuration:
Primary Information
- Name: Assign a unique name to the identity client.
- Platform types: Specify the type of platform (e.g., WebApp).
- Description: Provide a concise description of the identity client.
Identity Resources
This section encompasses various identity resources:
- VGActivityDate: Define the activity’s start and end dates.
- VGApplications: Enumerate the applications accessible to the current user.
- VGDeveloper: Grant access to the API Developer.
- VGISApproved: Indicate the approval status of the current user.
- VGIsLocked: Specify if the current user is locked.
- VGPermissions: List the permissions assigned to the current user.
- VGProfile: Detail the profile of the current user.
- VGRoles: List the roles assigned to the current user.
- VGToken: Provide the security token of the current user.
URI Information
This section contains URI-related information:
- Allowed Redirect URIs: Specify URIs to which the user can be redirected post-authentication.
- POST Logout URIs: Specify URIs to which the user can be redirected after logout.
- Overwrite URI Information When Deployed: Enable this option to overwrite URI information upon deployment.
CORS Information
- Allowed Cors Origins: Specify origins permitted to make cross-origin requests.
Grant Types
This section allows you to select the grant types for the identity client:
- AuthorizationCode
- Hybrid
- ClientCredentials
- ResourceOwnerPassword
Secrets Key
This section allows you to manage secret keys. The system can support multiple secret keys.
By following these steps meticulously, you can successfully establish a new authentication service for your Visual-Guard application.
3. Documentation on Postman
The Visual-Guard Identity Server API documentation provides a comprehensive guide on how to use Postman to view, explore, and test the API methods.
Postman is a popular tool used by developers for API testing. It allows you to send requests to the web server and get the response back. In the context of Visual-Guard Identity Server, it can be used to understand the various API methods available.
The documentation provides a link to the complete API of Visual-Guard Identity Server. This allows you to easily view and explore the various methods available in the API.
To start testing the API methods, you need to download and install Postman. The documentation provides a link to the official Postman download page.
Once you have Postman installed, you need to download the ‘VGIdentityServer Environment variables’ and ‘VGIdentityServer API Collection’ files. These files are to be imported into Postman. The documentation provides step-by-step instructions on how to do this.
After importing the files, you can start using Postman to test the API methods. You need to authenticate your user first, and then you can call any API.
In summary, the Visual-Guard Identity Server API documentation provides a detailed guide on how to use Postman to view and test the API methods. It provides all the necessary resources and instructions to get you started. Whether you are a seasoned developer or a beginner, this documentation is a valuable resource for understanding and testing the Visual-Guard Identity Server API.
View the complete API of Visual-Guard Identity Server
To easily view and explore VG Identity Server API methods, we have a documentation/api collection available on postman tool.
- VG2024.X: https://documenter.getpostman.com/view/25890945/2s9YJhwzbo
- VG2020.X: https://documenter.getpostman.com
Note: You can also go to the postman site directly, and search VGIdentityServer 2020, and you will be able to see a documentation/API collection.
Use Visual-Guard Identity Server API
Exploring the Visual-Guard Identity Server API
The Visual-Guard Identity Server API offers a collection of methods that can be conveniently explored and tested using the Postman tool. To get started, follow these steps:
- Download and Install Postman: Postman is a powerful tool for API testing. You can download it from the official website: Postman Downloads.
- Prepare for Import: Download the following files which will be imported into Postman:
- VGIdentityServer Environment Variables: These are essential for configuring your API requests in Postman.
- VGIdentityServer API Collection: This is a collection of all the API methods available for testing.
To easily explore and test VG Identity Server API methods, we have an API collection available on postman tool.
Exploring and Testing the VG Identity Server API
To explore and test the VG Identity Server API, follow these steps:
- Launch the Postman tool: Postman is a powerful tool that allows you to interact with APIs in a user-friendly environment.
- Download the ‘VGIdentityServer Environment Variables’: These variables are essential for configuring your API requests in Postman.
- Import the downloaded environment variables into Postman: To do this, navigate to the ‘File’ menu in Postman, select ‘Import’, and choose the file you just downloaded.
- Configure your environment variables: In Postman, click on the ‘Environment’ section. Here, you can adjust the variables according to your specific configuration.
By following these steps, you can effectively explore and test the VG Identity Server API using Postman.
Downloading the ‘VGIdentityServer API Collection’
- Download the ‘VGIdentityServer API Collection’: This file contains a collection of all the API methods available for testing.
Importing the API Collection into Postman
- Open Postman and navigate to the ‘File’ menu. Select ‘Import’ from the dropdown menu.
- In the Import dialog box, select the ‘VGIdentityServer API Collection’ file that you just downloaded.
After successfully importing the file, the API collection will be visible in your Postman interface, as shown below. Now, you’re all set to explore and test the various methods offered by the Visual-Guard Identity Server API.
Getting Started with Postman
- Launch the Postman tool: Open the Postman application on your device.
- User Authentication: Before you can start using the API, you need to authenticate your user. This step is crucial for ensuring secure access to the API.
- Using the API: Once your user is authenticated, you’re all set to start using the API. You can now explore and test any of the methods provided by the Visual-Guard Identity Server API.
4. How to get a security token ?
The VG Identity Server provides various methods to obtain a security token, granting access to your VG application. Here’s how to get started:
1. Define Platform Authentication:
Before requesting a token, your VG application requires a configured platform authentication. This sets the ground rules for secure communication.
2. Making the Authentication Request:
Once the platform authentication is in place, your application can initiate the token request by sending an HTTPS POST request. This triggers the authentication process on the Identity Server.
Explore the different authentication methods below:
Following section contains list of possible http post variables for authentication methods
| Post Variable | Description | Value |
|---|---|---|
| client_id | What Platform is used to authenticate the user The name is <application id>_<Platform mode> Like ADCC6B64-8577-4993-B934-77B9A5BA157B_Native | |
| scope | Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted. The OAuth spec allows the authorization server or user to modify the scopes granted to the application compared to what is requested, although there are not many examples of services doing this in practice. OAuth does not define any particular values for scopes, since it is highly dependent on the service’s internal architecture and needs. | openid profile VGActivityDate VGApplications VGDeveloper VGIsApproved VGIslocked VGPermissions VGProfile VGRoles VGToken IdentityServerAPI offline_access |
| client_secret | You need to use one secret of your VGIdentityServerClient | |
| grant_type | Define the type of authentification controller | VGAuthenticator |
| VGAuthenticationModule | Define the type of authentication | VGUser WindowsByCredential Passwordless |
| Username | This variable is used for the account type: Visual-Guard, Windows by credentials, etc.. | |
| Password | This variable is used when the account has password | |
| AuthenticationRequestId | RequestId of the selected mfa available method (Guid). Once you authenticate with first factor authentication, available options will be shown in the response | |
| MFAAvailableId | Id of the selected mfa available method (Guid). Once you authenticate with first factor authentication, available options will be shown in the response | |
| MFASecureCode | MFA Secure Code (OTP), that you might have received for multi factor authentication |
Please find below the example responses for authentication procedure.
- Success response
- acccess_token is your secure token
- expires_in is duration of the token
- token_type is always Bearer Token
- scope define what this token have access
- VGReponse is the response of VGSecurityRuntime
- AuthenticationState is the status of the authentication
- AuthorizationState is the state of your current request
- Error is set if VGSecurityRuntime get an error
- VGToken is your internal security token
{
"access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjIxODRFQzQ1MDMzMEM1QURFOTRDQjNBOUY5QjE1NkQwQkE5REE1NTBSUzI1NiIsInR5cCI6ImF0K2p3dCIsIng1dCI6IklZVHNSUU13eGEzcFRMT3AtYkZXMExxZHBWQSJ9.eyJuYmYiOjE3MDc4MTE1MzIsImV4cCI6MTcwNzgxMzMzMiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo1MDAwIiwiY2xpZW50X2lkIjoiMThkZThjZTctODBlNy00YzY2LWE2NzItNGZmYTNlYjU2ZDU0X05hdGl2ZSIsInN1YiI6Imt1bmFsIiwiYXV0aF90aW1lIjoxNzA3ODExNTMyLCJpZHAiOiJWaXN1YWxHdWFyZCIsInZnSWRlbnRpdHlQcm92aWRlck5hbWUiOiJWaXN1YWxHdWFyZCIsInZnVG9rZW4iOiIxM0E5Qjc2REM0NDQ5QUFGQzI3MkU1RDUxMEY5ODkwQTAwRkYzMjk0NzVFMkZERTlBNzlEQUM4MkFGNDZGRTY2ODE5QTQyQURBMjRGRDJEQjhDREU0OTdDRDFBNzYyQTlEQTc3NjNGNTM3RTAwREYzMTJBQjBCMUJBQzA2MTVFMyIsInZnVXNlcklkIjoia3VuYWwiLCJqdGkiOiIwNjAzMTY3RDRGQkZBN0YwQTVCOTlBNzg2Q0MwMkVCMSIsImlhdCI6MTcwNzgxMTUzMiwic2NvcGUiOlsiSWRlbnRpdHlTZXJ2ZXJBcGkiLCJvcGVuaWQiLCJwcm9maWxlIiwiVkdBY3Rpdml0eURhdGUiLCJWR0FwcGxpY2F0aW9ucyIsIlZHRGV2ZWxvcGVyIiwiVkdJc0FwcHJvdmVkIiwiVkdJc0xvY2tlZCIsIlZHUGVybWlzc2lvbnMiLCJWR1Byb2ZpbGUiLCJWR1JvbGVzIiwiVkdUb2tlbiIsIm9mZmxpbmVfYWNjZXNzIl0sImFtciI6WyJWaXN1YWxHdWFyZCJdfQ.lRVgFqyK45UATrgtVWekAPk_c0HsMzfxIhOxJ3xa8Y-48LHo3VkZmjdNhPuTjHMiI9dXM5wKn6KuP_uf4ZLgpG8f-bSAd9pQZ7VVTP1wwRzeh_dbmz8j7tXyZSCZQkWd--b44ao_CwFyxoChc-rnuIC-cMQUuzS99ugjeGwi8S64RfjUmHfmp80ajuvjj7DlekUIlFSYdJ9pYjYdjfYOTo11eiNTPZJ-YxLMwFu6zLTIrXiN4XY3K5BIM6gMxMmH8nbXcrwnxdQ8RPSRF8jg4nyYjt_x15mCuAtVb8sMkomAYXX6UG430OKZgjC-o2rwfiICVg30s1qdNd10JJgauA",
"expires_in": 1800,
"token_type": "Bearer",
"refresh_token": "61C074C8435CDE9F83A30E9A5FE937CFB72D57302B43C7B9955D17FA1D59D0CD",
"scope": "IdentityServerApi offline_access openid profile VGActivityDate VGApplications VGDeveloper VGIsApproved VGIsLocked VGPermissions VGProfile VGRoles VGToken",
"VGResponse": {
"RequestId": "b8082385-27fe-46cb-bea4-0878b6b220c3",
"AuthenticationState": {
"Status": 2048,
"IsFailed": false,
"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": false,
"IsMFATimeOut": false,
"HasUserAccountMissingEmail": false,
"HasUserAccountMissingMobilePhone": false,
"IsMFAEnrollmentRequired": false
},
"AuthorizationState": {
"Status": 16,
"IsFailed": false,
"IsCanceled": false,
"IsUserNotFound": false,
"IsUserNotAuthorized": false,
"IsVersionNotCompatible": false
},
"AuthenticationResponse": {
"RequestId": "b8082385-27fe-46cb-bea4-0878b6b220c3",
"Identity": {
"Name": "test",
"AuthenticationType": "VGUSER",
"IsAuthenticated": true
},
"MFAAvailables": [],
"Status": 2048,
"IsFailed": false,
"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": false,
"IsMFATimeOut": false,
"HasUserAccountMissingEmail": false,
"HasUserAccountMissingMobilePhone": false,
"IsMFAEnrollmentRequired": false
},
"Error": {
"Message": "",
"StackTrace": ""
},
"AuthorizationStatus": "Success",
"AuthenticationStatus": "Success",
"VGToken": "13A9B76DC4449AAFC272E5D510F9890A00FF329475E2FDE9A79DAC82AF46FE66819A42ADA24FD2DB8CDE497CD1A762A9DA7763F537E00DF312AB0B1BAC0615E3"
}
}
2. Response when MFA Authentication is required:
You can get MFAAvailableId and AuthenticationRequestId from response, and create second request using these parameters.
Note: you can check ‘MultifactorAuthentication’ section in postman documentation.
{
"error": "invalid_request",
"error_description": "Failure, MFA_AuthenticationRequired",
"VGAuthenticationStatus": "Failure, MFA_AuthenticationRequired",
"AuthenticationMethod": "None",
"VGResponse": {
"RequestId": "6984a56e-1674-4f90-9cfd-4573c049d250",
"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": "6984a56e-1674-4f90-9cfd-4573c049d250",
"Identity": {
"Name": "test",
"AuthenticationType": "VGUSER",
"IsAuthenticated": true
},
"MFAAvailables": [
{
"RequestId": "6984a56e-1674-4f90-9cfd-4573c049d250",
"TransportMode": 2,
"AuthenticationMode": 1,
"DestinationDisplay": "m****************s@g****.com",
"AuthenticationModeDisplay": "Link",
"TransportModeDisplay": "Email",
"Id": "674a1ed0-e987-4cd6-a0d2-01aa12a83231"
},
{
"RequestId": "6984a56e-1674-4f90-9cfd-4573c049d250",
"TransportMode": 2,
"AuthenticationMode": 2,
"DestinationDisplay": "m****************s@g****.com",
"AuthenticationModeDisplay": "OTP",
"TransportModeDisplay": "Email",
"Id": "ff2b9756-bfef-4209-86d3-1c5ca0e0aa23"
},
{
"RequestId": "6984a56e-1674-4f90-9cfd-4573c049d250",
"TransportMode": 1,
"AuthenticationMode": 2,
"DestinationDisplay": "+91*****34003",
"AuthenticationModeDisplay": "OTP",
"TransportModeDisplay": "SMS",
"Id": "881193d7-a65a-4d64-bea6-99fc8db64fbe"
}
],
"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": ""
}
}
4.1 How to authenticate a Visual Guard User?
To authenticate a Visual Guard user, you need a POST request
- client_id : the application to which the user wants to connect
- scope: the details the application needs to secure roles, permissions, user attributes, etc.
- client_secret: is a secret of the connection
- Username: name of the user
- Password: password of the user
- VGAuthenticationModule: needs to be VGUser
curl --location --request POST 'https://<Your Identity Server>/connect/token'
--header 'Content-Type: application/x-www-form-urlencoded'
--data-urlencode 'client_id=6f209594-fc04-4e96-9f9f-7daf57b0fb12_Native'
--data-urlencode 'scope=openid profile VGActivityDate VGApplications VGDeveloper VGIsApproved VGIsLocked VGPermissions VGProfile VGRoles VGToken offline_access IdentityServerApi'
--data-urlencode 'client_secret=secret'
--data-urlencode 'Username=<Your Visual-Guard user>'
--data-urlencode 'Password=<Password of the user>'
--data-urlencode 'grant_type=VGAuthenticator'
--data-urlencode 'VGAuthenticationModule=VGUSER'
5. What is scope of OAuth ?
Scope is a mechanism in OAuth 2.0 to limit an application’s access to a user’s account. An application can request one or more scopes, this information is then presented to the user in the consent screen, and the access token issued to the application will be limited to the scopes granted.
The OAuth spec allows the authorization server or user to modify the scopes granted to the application compared to what is requested, although there are not many examples of services doing this in practice.
OAuth does not define any particular values for scopes, since it is highly dependent on the service’s internal architecture and needs.
What is openid ?
6. How to get more information of the user ?
Visual-Guard Identity server provide user information method.
Url: https://<your VG Identity Server>/connect/userinfo
This method return many information like VGToken, user information, profile of the user, roles, permissions and etc…
Inside of your get http you need insert Authorization with bearer <SecurityToken>
Result of the request
{
"vgToken": "EF4ECC087AE7F56C4E6E66E24782079635F8A805E6565CFDED808F8902559BD8F6F95C207FFC690695835F96062201F3D02BE09C981D55169134AD1A70C0FDB1",
"vgUserId": "admin",
"vgApplications": "Visual Guard Console,Angular demo,AddressBookV3,Appeon_salesdemo,PB_Salesdemo,WSL_VGLinuxConsoleApp,WSL_VGLinuxWebApp,VG Angular",
"vgRoles": "Auditor,Default",
"vgPermissions": "/PowerServer/Address/CanReadAddress,/PowerServer/Customer/CanReadCustomer",
"vgIsApproved": "True",
"vgIsLocked": "False",
"vgStartDate": "7/14/2020 12:00:00 AM",
"vgEndDate": "12/31/9999 12:00:00 AM",
"vgFirstname": "",
"vgLastname": "",
"vgEmail": "admin@gmail.com",
"vgUA_City": "Paris",
"vgUA_Salary": "1000",
"vgUA_Height": "10.1",
"vgUA_BirthDate": "04/06/2021 00:00:19",
"vgUA_Married": "True",
"vgUA_DropDownlist": "Item2",
"vgUA_Binary": "",
"vgUA_City2": "1234567890123456789012345678901234567890123456789012",
"vgUA_Company": "",
"vgUA_Country": "",
"vgUA_Department": "",
"vgUA_Description": "",
"vgUA_DisplayName": "",
"vgUA_EmailAddress": "admin@gmail.com",
"vgUA_Fax": "",
"vgUA_HomePhoneNumber": "",
"vgUA_Manager": "",
"vgUA_Middlename": "",
"vgUA_MobileNumber": "+336655223399",
"vgUA_Name": "",
"vgUA_PostalZipcode": "",
"vgUA_Title": "",
"vgUA_Photo": "",
"vgDevApps": "[{\"ApplicationId\":\"a9efce21-c32a-47d5-a49b-b0953f2888b9\",\"ApplicationName\":\"Visual Guard Console\"},{\"ApplicationId\":\"4395b0a5-a5f4-4fac-84e0-5e0285e92e1d\",\"ApplicationName\":\"Angular demo\"},{\"ApplicationId\":\"da9217f7-4f3b-4f64-8bc4-3237dc8a2a65\",\"ApplicationName\":\"AddressBookV3\"},{\"ApplicationId\":\"7503e1ea-212a-4903-abb6-93702214fa87\",\"ApplicationName\":\"Appeon_salesdemo\"},{\"ApplicationId\":\"6f209594-fc04-4e96-9f9f-7daf57b0fb12\",\"ApplicationName\":\"PB_Salesdemo\"},{\"ApplicationId\":\"0d988715-2570-4d99-8e92-4a9e8461efb3\",\"ApplicationName\":\"WSL_VGLinuxConsoleApp\"},{\"ApplicationId\":\"249ae96a-6599-4ebd-808b-764ee244b3fa\",\"ApplicationName\":\"WSL_VGLinuxWebApp\"},{\"ApplicationId\":\"713e30bc-130d-4ec2-94eb-8ad3032b11db\",\"ApplicationName\":\"VG Angular\"}]",
"vgDevRoles": "[{\"Id\":\"30ebc3f1-8c0c-4b93-a8ba-d7e41e11c81d\",\"Name\":\"Auditor\",\"IsMembershipRole\":false,\"IsAdministrationRole\":false,\"IsActive\":true,\"IsContextual\":true,\"IsSharedRole\":false,\"ProfileValues\":[{\"Name\":\"RoleBoolean\",\"Id\":\"9d4625a6-5522-48c7-9f1a-4a396cf5c115\",\"Value\":\"False\",\"ValueImage\":null,\"ProfileAttributeId\":\"faa7ec69-4c67-486f-be4a-665fea29f458\",\"LastModification\":\"2021-10-13T11:42:58.58\"}],\"Description\":null,\"CanBeGrantedToUser\":false,\"CanBeGrantedToGroup\":false,\"IsDefault\":false,\"IsAnonymous\":false,\"ApplicationId\":\"00000000-0000-0000-0000-000000000000\"},{\"Id\":\"0c4857b2-69cf-438b-8c10-6c2ab1b60b98\",\"Name\":\"Default\",\"IsMembershipRole\":false,\"IsAdministrationRole\":false,\"IsActive\":true,\"IsContextual\":true,\"IsSharedRole\":false,\"ProfileValues\":[{\"Name\":\"RoleBoolean\",\"Id\":\"dd62645b-6fc0-4f77-a5d8-2450d881bb89\",\"Value\":\"False\",\"ValueImage\":null,\"ProfileAttributeId\":\"faa7ec69-4c67-486f-be4a-665fea29f458\",\"LastModification\":\"2021-10-13T10:08:13.583\"}],\"Description\":null,\"CanBeGrantedToUser\":false,\"CanBeGrantedToGroup\":false,\"IsDefault\":false,\"IsAnonymous\":false,\"ApplicationId\":\"00000000-0000-0000-0000-000000000000\"}]",
"vgDevPermissions": "[{\"Id\":\"55fb7f63-2ffc-4025-a238-265d20013d82\",\"FolderId\":\"774a0986-3d26-4cb3-975d-b53fa2ccf40b\",\"Name\":\"CanReadAddress\",\"FullName\":\"/PowerServer/Address/CanReadAddress\",\"Description\":\"\",\"Attributes\":[]},{\"Id\":\"6c57b68e-afbd-4667-a8c8-0b4b2a288e65\",\"FolderId\":\"cf7d7117-3180-4fd0-8cb8-109c7e6a10ab\",\"Name\":\"CanReadCustomer\",\"FullName\":\"/PowerServer/Customer/CanReadCustomer\",\"Description\":\"\",\"Attributes\":[]}]",
"sub": "admin"
}
7. Which API is available?
The Identity Server proposes an extended API
To access the extended API, click “How to you API”
https://identityserver.demo.visual-guard.com/documentation/index.html
8. How to Implement Microsoft Authenticator TOTP through an API
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
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
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
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.
{{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.