Telegram

Telegram Provider is designed for user authentication with the following technologies:

• One-time passwords
• Push notifications with a request to confirm or reject the sign-in

Users receive the one-time passwords and the push notifications through a bot in the Telegram messenger.

Telegram Provider can be used for authentication in the following modules:

• ADFS Extension
• Identity Provider
• IIS Extension (in the one-time password mode only)
• NPS RADIUS Extension (in the one-time password mode only)
• Windows Logon (in the one-time password mode only)

Note

The component requires access to the Telegram servers both for the service and for the provider.

Provider ID

{CA4645CC-5896-485E-A6CA-011FCC20DF1D}

Preconfiguration

To configure Telegram Provider:

1. Install the provider.
2. Install the service.
3. Configure the phone number attribute.
4. Create a bot in the Telegram application.
5. Configure the service.
6. Define the settings in the Management Console.
7. Register the authenticator.

Install the provider

1. Run the installation file located at axidian <Version number>/Axidian Providers/Axidian Telegram OTP Provider/<Version number>.

Important

If several Core Servers are used in your infrastructure, install the provider on all the servers of the infrastructure.

2. After the component installation is complete, you must restart the system. In the installation wizard window, click Yes to restart immediately, or No to do it later manually.

Install the service

1. Run the Telegram.Service-<version number>.x86.en-us.msi file located at axidian <Version number>/Axidian Providers/Axidian Telegram OTP Provider/.

2. After the component installation is complete, you must restart the system. In the installation wizard window, click Yes to restart immediately, or No to do it later manually.

Configure the phone number attribute

To use the provider, specify the phone number in an Active Directory user attribute. By default, this is the telephoneNumber attribute. You can also configure any other attribute. If the number is not specified, the provider cannot be used.

Important

Before you configure the attribute, be sure to decrypt and back up the Core Server configuration file inetpub/wwwroot/am/core/Web.config.

To configure the phone number attribute:

With the configuration wizard

1. Run the configuration wizard on the computer with Core Server installed: Start → Axidian → Axidian Access configuration wizard.
2. Go to the User catalogs tab.
3. Select a catalog.
4. Click Edit.
5. A warning appears stating that if you reduce the catalog scope or change the domain, the user data becomes unavailable. If you have already decrypted and backed up the inetpub/wwwroot/am/core/Web.config file, click OK.
6. In the configuration wizard, click Configure attribute mapping.
7. In the Phone field, enter the name of the Active Directory user attribute that contains the phone number, for example, the mobile attribute.
8. Click Save twice.
9. Go to the Confirmation tab and click Apply.
10. After the configuration file is set up and the operation is verified, close the wizard.

With the configuration file

1. Open the Core Server configuration file inetpub/wwwroot/am/core/Web.config.

2. Add the following to the adUserCatalogProvider section:

               <userMapRules>
                       <adObjectMapRule attribute="Phone" adAttribute="attribute_name_in_Active_Directory"/>
                   <objectTypeSettings>
                       <objectSetting category="person" class="user"></objectSetting>
                   </objectTypeSettings>
               </userMapRules>

   where:

   • attribute="Phone" — the attribute name in Axidian Access
   • adAttribute="attribute_name_in_Active_Directory" — the name of the corresponding Active Directory attribute that the phone number value is taken from

Example

<adUserCatalogProvider id="userId" serverName="axidian.local" containerPath="DC=axidian,DC=local" userName="userAdmin" password="Q1q2E3e4">
                //highlight-grey-start
                <userMapRules>
                        <adObjectMapRule attribute="Phone" adAttribute="mobile"/>
                    <objectTypeSettings>
                        <objectSetting category="person" class="user"></objectSetting>
                    </objectTypeSettings>
                </userMapRules>
                //highlight-grey-end
        </adUserCatalogProvider>

Create a bot

1. Open the Telegram application, find the dedicated @botfather bot, and open a dialog with it.

2. Click Start and send the /newbot command.

3. Specify the name of the bot you create. This name is displayed in the dialog window with the bot. Enter any name, for example, AxidianOTP.

4. Specify the username for the bot account, ending with bot, for example, AxidianOTP_bot. This username is used for links to the bot.

5. If the registration is successful, the API access token is displayed. You need this token to configure the AM Telegram Service service and the bot in the Management Console.

Configure the service

To configure the service, you need a service user with the global administrator rights. Authenticators are registered on behalf of this user. For security reasons, we recommend that you create a separate user in Active Directory for the Telegram Provider registration.

To configure the Telegram Service:

1. Open the AM.Telegram.Service.exe.config service configuration file located at C:\Program Files (x86)\Axidian-Id\Axidian-Id Telegram Service.

   To save the changes in the configuration file, run the editor with administrator rights.

2. In the appSettings section, set the values in the value parameters for the corresponding key parameters:

culture	The localization language; Russian and English are supported. The default value is ru-RU.
EAWebAPIURL	The Core Server URL.
username	The name of the service user with the global administrator rights on whose behalf the authenticators are registered.
password	The service user password.
lognames	The user name logging format. The default value is Name. Supported formats Id — the user ID in Axidian Access in the rootUserCatalogProviderId_Guid format Name — the value of the name attribute from Active Directory CanonicalName — the user name in the Canonical-Name format (myserver.demo.local/users/UserName) PrincipalName — the value of the userPrincipalName attribute from Active Directory SamCompatibleName — the user name in the domainName\UserName format DistinguishedName — the value of the distinguishedName attribute from Active Directory Sid — the value of the objectSid attribute from Active Directory Email — the value of the mail attribute from Active Directory, or the value specified in the Core Server configuration file Phone — the value of the telephoneNumber attribute from Active Directory, or the value specified in the server configuration file Example: add key="lognames" value="PrincipalName,Sid"
botId	The token received when you created the bot in Telegram.
trustedId	An arbitrary unique identifier. The identifier value must match the one specified in the Telegram Service trusted ID setting in the Management Console.

An example of the edited appSettings section

      <appSettings>
          <add key="culture" value="en-US" />
          <add key="EAWebAPIURL" value="https://server.axidian.local/am/core/" />
          <add key="username" value="telegram@axidian.local" />
          <add key="password" value="Q1q2E3e4" />
          <add key="lognames" value="Name" />
          <add key="botId" value="1156320278:AAG24_EODMotm_feYYQOfbPddK_2Z_JDiKQ" />
          <add key="trustedId" value="the unique identifier set when configuring the Telegram Service" />
        </appSettings>

3. In the logServer section, specify the values of the following parameters:

   • In the URL parameter, specify the URL to connect to Log Server in the http(s)://full_dns_server_name/ls/api format.

   • If the private key is in the registry and the certificate is in the computer storage, specify the certificate thumbprint in the CertificateThumbprint parameter.

   • If the key pair is in a pfx file, specify the path in the CertificateFilePath parameter and the pfx password in the CertificateFilePassword parameter.

     Example

     <logServer Url="https://logserver.axidian.local/ls/api/" CertificateThumbprint="YOUR_CERTIFICATE_THUMBPRINT" CertificateFilePath="PATH_TO_PFX" CertificateFilePassword="PFX_PASSWORD" />

4. Save the changes.

5. Start the AM Telegram Service.

   How to start the service

   1. Run Task Manager.
   2. In the window that opens, click More details and go to the Services tab.
   3. Find AM Telegram Service in the list, right-click it, and select Start.
   Note

   If you use several Core Servers, the service can only run on one of them at a time.

Define the settings in the Management Console

For the provider to work correctly, define the remaining settings in the Management Console. To do this:

1. In the Management Console side panel, open the Configuration section.

2. Go to the Authenticators tab.

3. Select the Telegram authenticator.

4. If required, define the general settings.

5. In the Telegram Service settings section, specify an arbitrary unique identifier. The identifier value must match the one specified in the AM.Telegram.Service.exe.config service configuration file.

6. In the Operating mode section, select the provider operating mode — Push or OTP.

7. In the Bot settings section:

   • In the Bot ID field, specify the token received when you created the bot in Telegram.
   • In the Message template field, configure the message appearance. The message can contain the one-time code to sign in to the application, the application name, the user name, the sign-in date and time, and the IP address of the computer used for the sign-in.

8. If you plan to use Telegram Provider in the one-time password mode, in the One-time password generation settings section:

   • In the One-time password length field, specify how many characters the one-time password contains.
   • In the Digits setting, specify whether the one-time password contains digits.
   • In the Lowercase Latin letters setting, specify whether the one-time password contains lowercase Latin letters.
   • In the Uppercase Latin letters setting, specify whether the one-time password contains uppercase Latin letters.
   • In the Special characters setting, specify whether the one-time password contains special characters.

9. If required, configure the following:

   Configure Telegram Provider to work through a proxy

   In the Bot settings section:

   • In the Use proxy setting, select Yes. No is selected by default.
   • In the Proxy address field, specify the proxy server address.
   Configure spam protection

   The spam protection mechanism is based on calculating the percentage of successful authentications relative to all sent messages over a specified time interval. The calculation process starts only if the number of sent messages exceeds the number that you have specified in the Evaluation Window setting.

   When a spam attack is detected, further message sending is blocked for a specified period of time, and a "Potential spam attack detected" error occurs when attempting to log in.

   Messages can be sent again either after the specified period expires or when a certain percentage of successful authentications is reached.

   To configure spam protection, perform the following actions:

   1. In Management Console, in the Configuration→Authenticators section, select an authenticator.
   2. In the Spam Protection Settings section, configure the following settings:
      • Enable or disable spam protection.
      • In the Authentication attempts evaluation window field, specify the time period during which the percentage of successful login attempts is calculated.
      • In the Authentication attempts threshold window field, specify how many login attempts must be made during the time specified in the authentication attempts evaluation window.
      • In the Percentage of successful authentication attempts field, specify the minimum percentage of successful logins relative to all sent messages.

   Example

   The setting is enabled with the following values:

   • Authentication attempts evaluation window — 600
   • Authentication attempts threshold window — 20
   • Percentage of successful authentication attempts — 85

   Spam protection is activated if 21 login attempts occur (21 messages sent). The authenticator will be blocked for 600 seconds.

   The authenticator will be unblocked in one of the following cases:

   • the percentage of successful logins (user successfully entered the one-time password from the message) reaches 85;
   • 600 seconds have passed since the blocking.

   Information

   Log server events:

   • 2090: Potential spam attack detected. Message sending suspended.
   • 1118: Message sending to users resumed.

Register the authenticator

Note

During the provider registration, the user is asked for the phone number from their Telegram account. The user phone number in Active Directory must match it exactly and be in the same format. The supported formats are +7xxxxxxxxxx and 8xxxxxxxxxx.

1. Open the chat with the bot you created. To do this, enter the name of your bot in the messenger search bar, or follow the link from the BotFather message.

2. Click Start.

3. Enter the /register command.

4. Enter the phone number of the Telegram account.

5. If the authenticator registration is successful, the You have been successfully registered message is displayed.