# @beedgtl/mobile-id > Mobile ID Web SDK for B2B clients. This SDK allows to use authentication with a Mobile ID in DI mode. Latest version **1.0.0** (published 2021-12-17) · MIT license · 0 weekly downloads ## Install ```sh npm install @beedgtl/mobile-id pnpm add @beedgtl/mobile-id yarn add @beedgtl/mobile-id bun add @beedgtl/mobile-id ``` ## Health **Score 25/100 (F)** — status: abandoned. Positive: has types; esm support; no vulnerabilities. Warnings: low downloads. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.0.0 | | Published | 2021-12-17 | | First published | 2021-12-17 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Node | >=14.5.0 | | Dependencies | 1 | | Unpacked size | 39.7 KB | | Known vulnerabilities | 0 | | Install scripts | no | | Author | Beeline Digital, PJSC VimpelCom | | Maintainers | bee.divergent044, imalyugin | | Keywords | beeline, vimpelcom, mobileid, mobile-id, beeline-mobileid, beeline-mobile-id | ## Links - npm: https://www.npmjs.com/package/@beedgtl/mobile-id - npm.io page: https://npm.io/package/@beedgtl/mobile-id ## Dependencies (1) - [classnames](https://npm.io/package/classnames.md) ^2.3.1 ## Alternatives - [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads - [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads - [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads - [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads - [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads ## Recent versions - 1.0.0 (latest) — 2021-12-17 ## README

Beeline Mobile ID Web SDK

![npm license](https://img.shields.io/npm/l/@beedgtl/mobile-id.svg?style=flat-square) ![npm version](https://img.shields.io/npm/v/@beedgtl/mobile-id.svg?style=flat-square) [![install size](https://packagephobia.com/badge?p=@beedgtl/mobile-id)](https://packagephobia.com/result?p=@beedgtl/mobile-id) ![npm downloads](https://img.shields.io/npm/dm/@beedgtl/mobile-id.svg?style=flat-square) Beeline Mobile ID Web SDK is a javascript package that allows web developers to easily integrate their web applications with the Mobile ID service. This module will allow you to add the authentication and enable the end user's personal data autofill functionality in your website. ## Concept General service interaction scenario: 1. The User enters your website and chooses authorization over Mobile ID. 2. The user is redirected to the Operator's page. 3. The Operator sends a PUSH message to the user's device with a request to confirm authentication on your resource. If the User's device cannot receive a PUSH, an SMS-message will be sent, containing an authentication confirmation link. 4. The user clicks "Accept" or "OK" (depending on the carrier) on the mobile phone. 5. The user is redirected to your `redirect_uri` and request completion of the authentication process is sent. 6. If user authentication was successful and "Form auto-completion" is provided by your price plan, a request for the user's personal data is sent by the SDK and fulfilled by the Operator. ## Contact Us Do you need help? Contact Support: mobileid_support@beeline.ru ## Browser Support Browsers supporting the ECMAScript 2015 (ES6) standard | ![Chrome](https://raw.github.com/alrra/browser-logos/main/src/chrome/chrome_48x48.png) | ![Safari](https://raw.github.com/alrra/browser-logos/main/src/safari/safari_48x48.png) | ![Firefox](https://raw.github.com/alrra/browser-logos/main/src/firefox/firefox_48x48.png) | ![Opera](https://raw.github.com/alrra/browser-logos/main/src/opera/opera_48x48.png) | ![Samsung Internet](https://raw.github.com/alrra/browser-logos/main/src/samsung-internet/samsung-internet_48x48.png) | ![Edge](https://raw.github.com/alrra/browser-logos/main/src/edge/edge_48x48.png) | ![IE](https://raw.github.com/alrra/browser-logos/main/src/archive/internet-explorer_9-11/internet-explorer_9-11_48x48.png) | |----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------:| | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | Latest ✔ | 11 ✗ Not supported | ## Get Started ### Registration To start working with the service, you need to: 1. Go through the registration process on the website https://mobileid.beeline.ru. You can register through your *Personal Account*, or fill out a questionnaire together with our manager: a. Decide on the connection method b. Choose a tariff: + **Sign In only** + **Autofill / base** + **Autofill / base and address** + **Autofill / full** c. Provide server-side implementation for a scheme with operator screens — **HTTPS Redirect URL** and **HTTPS JWKS URL** (for request personal data). 2. Create an entry for a digital resource. As a result, you will get `client_id` and `client_secret`, `client_name` values (field of the form – *Application Name*), that will be attached to request from the Mobile ID platform to the operator that serves the subscriber's phone number. ### Installation Install a stable version via Yarn or npm: ```sh yarn add @beedgtl/mobile-id # or npm i @beedgtl/mobile-id ``` ### Usage ```js // add the module to your code import { MobileIDClient } from '@beedgtl/mobile-id'; ``` Initialize client with appropriate configuration: ```js const mobileIDClient = new MobileIDClient({ credentials: { id: 'your_client_id', name: 'your_client_name', key: 'your_encoded_access_key', }, redirectUrl: 'https://your-app.domain.ru/', scope: ['mc_authn'], acrValues: 3, onError: (error) => { /* Body of the error handler function */ }, onSuccess: (tokenInfo, premiumInfo) => { /* Body of the success result handler function */ }, }); ``` Next, create button component and insert it in your DOM: ```js import { Text } from '@beedgtl/mobile-id'; const button = mobileIDClient.createButton('violet', 'xl', { text: Text.PRIMARY }); document.querySelector('#root').appendChild(button); ``` ### Important > ⚠️ If `redirectUrl` - your website redirect url, specified (as **redirect_uri**) during service provider account registration - **doesn't match** your login page url, you need to initialize MobileIDClient **again**. ❗**The SDK configuration must be identical in both calls** First, initialize `MobileIDClient` on the login page. ##### configuration.js ```js export const MOBID_CONF = { credentials: { id: 'your_client_id', name: 'your_client_name', key: 'your_encoded_access_key', }, redirectUrl: 'https://your-app.domain.ru/root/profile', scope: ['mc_authn'], acrValues: 3, premium: true, onError: () => { /* Some fn */ }, onSuccess: () => { /* Some fn */ }, }; ``` ##### login-page.js ```js import { MobileIDClient, Text } from '@beedgtl/mobile-id'; import { MOBID_CONF } from './configuration.js'; // Login page route // For example, https://your-app.domain.ru/login const mobileIDClient = new MobileIDClient(MOBID_CONF); const button = mobileIDClient.createButton('bright', 'm', { text: Text.DEFAULT }); document.querySelector('#root').appendChild(button); mobileIDClient.setMsisdn(someMsisdn); ``` Second, initialize `MobileIDClient` on the redirectUrl route page ##### profile-page.js ```js import { MobileIDClient } from '@beedgtl/mobile-id'; import { MOBID_CONF } from './configuration.js'; // After login page route // For example, https://your-app.domain.ru/root/profile const mobileIDClient = new MobileIDClient(MOBID_CONF); /* No need to create button yet */ /* If authentication fails, an onError callback will be invoked */ ``` If `premium` option is `true` and authentication process completes successfully, but personal data request fails, then `onSuccess` and `onError` callbacks will be invoked together. At that `onSuccess` will be invoked with only one argument `MCToken` and `onError` will be invoked with `Error.method` set to `personalData`. ### Result data An example js object `tokenInfo` (passed as first argument of `onSuccess` callback): ```js { accessToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6InM0aWo5Q1pwOVJNcGpwTFFISGlRSVJLcU9MSDEyZEFFNndGL1kyRloxNlU9IiwidHlwIjoiSldUIn0.eyJzdWIiOiJjYWIxMWJmZS1hMGJiLTQzZmUtYjVhNi1mNDUyODNiNDFjMTciLCJpYXQiOjE2MzcwNjIyMTEsImV4cCI6MTYzNzA2MjgxMSwianRpIjoiODFlOGI1MjItZDkwZS00MzMwLTg3NGYtZDUxMjcwZjdlZWFhIiwiYXpwIjoidmFzLXRlc3QiLCJhdWQiOiIiLCJpc3MiOiJodHRwczovL2FnZ3Jtb2JpbGVpZC5iZWVsaW5lLnJ1IiwibmJmIjoxNjM3MDYyMjExfQ.Bse3IH5Tvgdw1QcyYvNbt4iVWIU1mxw5Qmb0gvuX43INJIIVMc_WauCyw41t4mftAsvLn6pEHqGSge6OT3BraYbK_ZO0kgGbmLmdan_FTUTHZBzEVUO3JGJHs5jk9MzZQZUQPyupj9VcXXNrw9102e6EzCpZqe9_CQ2W-RWaAgWnwVZk1pYZi-rYeDxgoZEaMPpkx7u8qal2x6fNPBW68jNjg-cvlaPsZIy-ZD3otiOi0Fpq-HM0fofEa8Z4tDDapv3FPA5ahTB7CEU9Z6iwQ5qpeJSWv0SOYFvdCuOy7PBWVc-X7EuhaM_v4wtWnudmIEsKzg-o0fsGMIsTP5XkFA", expiresIn: 599, scope: 'openid mc_identity_basic mc_authn', idToken: "eyJhbGciOiJSUzI1NiIsImtpZCI6InM0aWo5Q1pwOVJNcGpwTFFISGlRSVJLcU9MSDEyZEFFNndGL1kyRloxNlU9IiwidHlwIjoiSldUIn0.eyJhdF9oYXNoIjoiZlQtX2gwcGFkWEtwSmxMVV90ckdlZyIsInN1YiI6ImNhYjExYmZlLWEwYmItNDNmZS1iNWE2LWY0NTI4M2I0MWMxNyIsImFtciI6IlNJTV9PSyIsImtpZCI6InNpZ0tleSIsImlzcyI6Imh0dHBzOi8vYWdncm1vYmlsZWlkLmJlZWxpbmUucnUiLCJhdWQiOiJ2YXMtdGVzdCIsImFjciI6MiwiYXpwIjoidmFzLXRlc3QiLCJhdXRoX3RpbWUiOjE2MzcwNjIyMTEsInJlY2lwaWVudCI6Imh0dHBzOi8vYWdncm1vYmlsZWlkLmJlZWxpbmUucnUvbm90aWZpY2F0aW9uIiwiaWF0IjoxNjM3MDYyMjExLCJleHAiOjE2MzcwNjI4MTEsImp0aSI6IjgzYjQ3Y2QyLTAwYjMtNGQxNS05MjA1LTgwODM2ZWJlZjYxNSIsIm5iZiI6MTYzNzA2MjIxMX0.UMMcw-QsEJw22VDHASJ7Vr0W4_u1jeFbTuK5auaIbW6qGaPlQI-FXJLFkM7KrDTtr1qD4CP1f9BLNy4xQ_Pzzlfqwpcq6sMfRB84kEVoVDujhDUEngbSDFvuvjsJGAJf3buWC-7I1q5_B_6XRiOHpiH-q31FDMAFsZf4uagK6432gHcA3pX947wsE42PVJYnhFB0zvM6SGryF933Jiy6b3SrNTQ9ztZEFWNzxaon4LtVDw9XyMdQR15ZJAylOJcMAHsiFEPUDJe997OfMgwFP0JgmGvjXVTix8GfsScbrngozPuDsmJv4Ee1s64iT7ca9VBkcBla4tH74R7z8q53jA", } ``` An example string of `premiumInfo` (passed as second argument of `onSuccess` callback): ``` eyJ0eXAiOiJKV1QiLCJlbmMiOiJBMTI4R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.Wk_DFYjpCnS_87LU1pf1Fzub9_SfRGei9twHi9GYT-MZeD8daYrUW-SJkfl6idH_2lRtRsfZiiXHo8QrSJi4NyQxi_4SD4P2FncJnLKe0gyUCCboc6IEfnpdw4D8kTaw0FLv8_MdeM0Wb1NKBV4CK52mVZSNcNj7KaXBaueByzbrS5Hf98bYxiPgRmYNL84xMMlEOuIJdZYBJOICVlXBXi63LDa75PzyuJQkKxlxdNX5c5F1lm4E ``` ## Documentation ### MobileIDClient constructor properties
Property Required Type Description
credentials yes Credentials Credential parameters of your service provider, issued during account registration. Credentials type definition is provided below
redirectUrl yes string Website redirect url, specified (as redirect_uri) during service provider account registration
scope yes Array<string> Access types, issued during service provider account registration.
⚠️ IMPORTANT, access type 'openid' set as default, don't need to pass this value in scope array.

Your Tariff Sign in only - requires scope to include mc_authn value
Your Tariff Autofill/base - to enable main tariff option, add mc_identity_basic value to array
Your Tariff Autofill/base and address - to enable main tariff option, add mc_identity_basic_address value to array
Your Tariff Autofill/full - to enable main tariff option, add mc_identity_full value to array
acrValues no 2 | 3 | 4 Authentication method type. Defaults to 2
2 - authentication by Push acceptation (press OK button)
3 - authentication by PIN-code
4 - authentication by crypto key (mobile digital signature). Only supported by SIM cards with a crypto-applet
premium no boolean When set to true, the encrypted personal data will be fetched after successful user authentication. The result will be passed in onSuccess callback
msisdn no string The user phone number, format: eleven digits starts with '7' symbol (example '79001234567'). The user's phone number is unknown during MobileIDClient initialization, you can set this value later, before the MobileId button is clicked. For this call mobileIDClient.setMsisdn(msisdn)

But you can choose not to ask the user a phone number. Then the user will enter the phone number in the authentication process.
onError yes function Invoked when an error is encountered in the process of authentication or fetching personal data. Function API is seen below
onSuccess yes function Invoked when a success result is encountered in the process of authentication and/or fetching personal data. Function API is seen below
### MobileIDClient methods and callbacks
Function Method / Callback Arguments Returns Remarks
onError callback Error void Error type definition is seen below
onSuccess callback (MCToken, string | undefined) void MCToken type definition is seen below. The received MCToken guarantees successful user authentication. Second argument is JWE string containing encrypted personal data
setMsisdn method string void User’s phone number, format ‘79001234567’
createButton method (Theme, Size, ButtonConfig | undefined) HTMLButtonElement | null Creates a styled button component. Returns `null` during server-side rendering
### Custom types #### Theme ```ts type Theme = 'light' | 'violet' | 'bright'; ``` | --- | ``light`` | ``violet`` | ``bright`` | |:----------:|--------------------------------------------------------------------|--------------------------------------------------------------------|--------------------------------------------------------------------| | logo | ![](https://via.placeholder.com/15/5400ba/000000?text=+) `#5400ba` | ![](https://via.placeholder.com/15/ffffff/000000?text=+) `#fff` | ![](https://via.placeholder.com/15/333333/000000?text=+) `#333` | | text | ![](https://via.placeholder.com/15/333333/000000?text=+) `#333` | ![](https://via.placeholder.com/15/ffffff/000000?text=+) `#fff` | ![](https://via.placeholder.com/15/333333/000000?text=+) `#333` | | background | ![](https://via.placeholder.com/15/ffffff/000000?text=+) `#fff` | ![](https://via.placeholder.com/15/5400ba/000000?text=+) `#5400ba` | ![](https://via.placeholder.com/15/ffcb00/000000?text=+) `#ffcb00` | #### Size Differences in padding, height, logo and font sizes. The button component has a width `100%`. Use a wrapper block if needed. ```ts type Size = 's' | 'm' | 'l' | 'xl'; ``` #### ButtonConfig ```ts interface ButtonConfig { text?: string, isSubmit?: boolean, } ``` - `isSubmit` - when set to `true`, the button will be created with `type="submit"`. Default: false (`type="button"`) - `text` - when left empty or falsy, a simple circle-shaped button with a logo will be created. **Recommend**, use one of the available texts (see `enum Text`). If it isn't clear from context of the page, how the login will be performed, **recommend** add an explanatory caption under the button. #### Text ```ts export declare enum Text { DEFAULT = 'Войти по номеру телефона', PRIMARY = 'Войти с Мобильным ID', SECONDARY = 'Войти через Мобильный ID', } ``` #### Credentials ```ts interface Credentials { id: string, // client_id from service provider account key: string, // btoa(`${client_id}:${client_secret}`), client_secret from service provider account name: string, // client_name from service provider account } ``` #### MCToken ```ts interface MCToken { scope: string, idToken: string, expiresIn: number, accessToken: string, } ``` #### Error ```ts interface Error { error: string, errorDescription?: string, method: 'authentication' | 'personalData', } ``` ## How to decrypt user's personal data To work with encrypted data in the response from premium info, you must: 1. Generate a pair of RSA keys (public and private) in JWK format with following parameters: + Key Size = 2048 + Key Use = encryption + Algorithm = RSA-OAEP 2. Place the public key on the **JWKS Url** 3. Give the **JWKS Url** that contains **JWK** for encryption to the operator. There is a corresponding field in the application form for registration in the Mobile ID service 4. Keep the private key secret and use it to decrypt the data received in the responses from premiuminfo endpoint To generate a key, you can use the online service — https://mkjwk.org/. An example of public key: ```json { "keys": [ { "kty": "RSA", "e": "AQAB", "use": "enc", "kid": "UCGQkw55DlgzhRp88dkdOiTVn1EUtTTYFytL7GagOAA", "alg": "RSA-OAEP", "n": "24M0ceQ2gzUENyPi8lg98V1jNv727XOc5JC1oBMWt71BcWVgzEkHnfrJQ_iPIehj1103utBcB2nZzPW7bTo3vUAFuiJTIzIlpm6LBEAB6ayF2wBP_IBUppYcuIs0M0lvDPwGbahgYez0IoiJ8aNowg8g_C2tcUYMOAjKTfs13tqUUrzj5_Xkmw8ZlSciUWuVZdopMXuxWsOOfgOlKW_gCpiodTfSvnPXvdU1Wy6enopBP1ELDOWbvp-_5eGunPEmjWDFgPMCJUnLrUikki6UIwClMLYvnTDQ4ee_kH5zqZ0l_vgGE1cedXlzgTdByH0e9nY1d5a8AQbQfEHuEFoQ" } ] } ``` ### Public key description: | Field | Description | |-------|----------------------------------------------------------------------------------------------------------| | kty | The encryption algorithm. To work with the service — always "RSA" | | e | The exponent of the public key in the BASE64URL encoded format. To work with the service — always "AQAB" | | use | The method of "use". For encryption — "enc" | | kid | Key id (id) | | alg | Name of the encryption algorithm | | n | Public key module in BASE64 URL encoded format | ### General procedure for processing the `premiumInfo` response The content of the response is a JWE token consisting of 5 components: ``` BASE64URL(JWE Protected Header) + '.' + BASE64URL(JWE Encrypted Key) + '.' + BASE64URL(JWE Initialization Vector) + '.' + BASE64URL(JWE Ciphertext) + '.' + BASE64URL(JWE Authentication Tag) ``` The definitions of the components can be found in the standard [RFC 7516 (section 2)](https://datatracker.ietf.org/doc/html/rfc7516#section-2). ### Response body decryption The response should be processed according to the standard [RFC 7516 (section 5.2)](https://datatracker.ietf.org/doc/html/rfc7516#section-5.2). Decryption should be performed using a private key according to the following algorithm: 1. Extract and decode values from JWE from BASE64URL 2. Calculate the Secret - **Content Encryption Key** —CEK) - decrypt the values of the JWE Encrypted Key with the Recipient's private key using the algorithm specified in the JWE Protected Header 3. Calculate **plaintext** - decrypt the JWE Ciphertext by the method specified in the JWE Protected Header using the secret (*CEK*), initialization vector (*JWE InitializationVector*) and authentication Tag (*JWE Authentication Tag*) Example, JAVA decryption: ```java import org.forgerock.json.jose.common.JwtReconstruction; import org.forgerock.json.jose.jwe.EncryptedJwt; import org.forgerock.json.jose.jwk.RsaJWK; String encrypted; // premiuminfo response String jwkValue; // a string containing JWK RsaJWK jwk = RsaJWK.parse(jwkValue); EncryptedJwt jwt = new JwtReconstruction().reconstructJwt(encrypted, EncryptedJwt.class); jwt.decrypt(jwk.toRSAPrivateKey()); String result = jwt.getClaimsSet().toString(); ``` Example, Node.js decryption: ```js const jose = require('node-jose'); const PID = 'premiumInfo_response_encrypted'; const privatekey = 'string containing JWK'; const decrypt = async (encData, privatekey) => { const keystore = jose.JWK.createKeyStore(); const key = await keystore.add(privatekey, 'pem'); const result = await jose.JWE.createDecrypt(key).decrypt(encData); const decriptPID = new TextDecoder().decode(result.payload); return decriptPID }; const decryptedData = decrypt(PID, privatekey); ``` --- _Source: https://npm.io/package/@beedgtl/mobile-id · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._