Overview

OTP Request Service is used by Authentication/e-KYC Partners to generate OTP for an individual's UIN/VID. The generated OTP is stored in IDA DB for validation during OTP Authentication.

The documentation here will guide you through the prerequisites required for the developer' setup.

Software setup

Below are a list of tools required in ID Repository Services:

1. JDK 11

2. Any IDE (like Eclipse, IntelliJ IDEA)

3. Apache Maven (zip folder)

4. pgAdmin

5. Postman

6. Git

7. Notepad++ (optional)

8. lombok.jar (file)

9. settings.xml (document)

Follow the steps below to set up ID Repository Services on your local system:

1. Download lombok.jar and settings.xml from here.

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

3. Install Eclipse, open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update.

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building of a project

1. Open the project folder where pom.xml is present.

2. Open command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true to build the project and wait for the build to complete successfully.

4. After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar and add to project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).

2. Clone mosip-config repository.

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

4. As ID Authentication is using two properties files, id-authentication-default and application-default, you will have to configure them according to your environment. The same files are available here for reference.

Properties to be updated:

application-default.properties

• mosip.mosip.resident.client.secret = <current_password>.

• db.dbuser.password=<password>.

• mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

• Comment this out auth.server.admin.issuer.internal.uri in application-default.properties file because you already have this auth.server.admin.issuer.uri , and hence there is no need of auth.server.admin.issuer.internal.uri.

• mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json)

id-authentication-default.properties

• ......

• ......

5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

7. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

1. Open Eclipse and run the project for one time as Java application, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Auth-Otp-Service-Dev").

2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

4. Click Apply and then debug it (starts running).

Authentication OTP Service API

• For API documentation, refer here.

Overview

ID Authentication is built as an independent service that can be seeded with data for authentication by any system, including MOSIP. In the current design, we can have multiple IDA modules running from a single issuer.

The ID Authentication (IDA) module of MOSIP consists of the following services:

1. Authentication Services

2. OTP Service

3. Internal Services

To learn more about it, refer to the below video:

Authentication Services

The services mentioned below are used by Authentication or e-KYC Partners.

• Authentication Service: used to authenticate an individual's UIN/VID using one or more authentication types.

• KYC Authentication Service: used to request e-KYC for an individual's UIN/VID using one or more authentication types.

OTP Request Service

OTP Request Service is used by Authentication/e-KYC Partners to generate OTP for an individual's UIN/VID. The generated OTP is stored in IDA DB for validation during OTP Authentication.

Internal Services

1. Internal Authentication Service - The authentication service used by internal MOSIP modules such as Resident Service, Registration Processor and Registration Client to authenticate individuals.

2. Internal OTP Service - used by Resident Service to generate OTP for an Individual for performing OTP Authentication.

3. Authentication Transaction History Service - used by Resident Service to retrieve a paginated list of authentication and OTP Request transactions for an individual.

Credential issuance callback

Key generation

1. IDA IDENTITY_CACHE(K18) symmetric key to encrypt and decrypt the Zero-knowledge 10K random keys

2. IDA ROOT master key(K15)), IDA module master key(K16), IDA-SIGN master key

3. Base keys CRED_SERVICE(K22), IDA-FIR(K21), INTERNAL(K19), PARTNER(K20)

Authentication client demo app

Below is the sample authentication demo UI image.

Authentication Error Eventing

The ID Authentication service now offers an Authentication Error Eventing feature. When an authentication related error occurs, a message will prompt to the user to retry after a few minutes. In the meantime, Kafka event will be triggered to publish the data to the designated topic, allowing subscribers to receive a message for further processing.

This feature can be utilized for different use cases such as on demand template extraction, report generations, to identify any fraudulent occurrence etc.

One such use case is on demand template extraction. In an instance where a user has successfully registered and obtained a valid UIN/VID but encounters an error during authentication due to unavailability of the entered UIN/VID in the IDA DB, this feature comes into play. This issue tends to occur particularly during periods of high registration and UIN generation volumes, where additional time is needed for data transmission from the ID Repo to the IDA DB. This authentication error eventing feature will help in capturing the errors related to this issue and event will be created. subscribers can capture this event and process them accordingly to enable the template extraction to proceed with the authentication/verification process.

This feature is designed to be a plugin feature in IDA, which can be configured based on the requirement. To enable the feature below property should be marked as True:

mosip.ida.authentication.error.eventing.enabled=true

Once this property is enabled, related kafka property setup should be installed to utilize the feature.

Subscribers who will be subscribing to the event should be onboarded as authentication partners. To on board subscribers below steps needed to be followed:

Steps to onboard the subscribers:

1. Create a policygroup by the name mpolicygroup-default-tempextraction

2. The policy should be configured to not allow any authentication to be carryout but the partner except reading the kafka event. To attain this, allowedAuthTypes should be marked as null

For example:

{"authTokenType":"partner","allowedKycAttributes":[{"attributeName":"fullName"},{"attributeName":"gender"}, {"attributeName":"residenceStatus"},{"attributeName":"dateOfBirth"},{"attributeName":"photo"}],"kycLanguages":["ara","eng"],"allowedAuthTypes":[]}

1. Publish the policygroup and policy

Configuration

Developer Guide

To know more about the developer setups, read:

API

Source code

Overview

• Internal Authentication Service: The authentication service used by internal MOSIP modules such as Resident Service, Registration Processor, and Registration Client to authenticate individuals.

• Internal OTP Service: used by Resident Service to generate an OTP for an Individual for performing OTP Authentication.

• Authentication Transaction History Service: used by Resident Service to retrieve a paginated list of authentication and OTP Request transactions for an individual.

The documentation here will guide you through the prerequisites required for the developer's setup.

Software setup

Below is a list of tools required in ID Repository Services:

1. JDK 11

2. Any IDE (like Eclipse or IntelliJ IDEA)

3. Apache Maven (zip folder)

4. pgAdmin

5. Postman

6. Git

7. Notepad++ (optional)

8. lombok.jar (file)

9. settings.xml (document)

Follow the steps below to set up ID Repository Services on your local system:

1. Download lombok.jar and settings.xml from here.

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

3. Install Eclipse, open the lombok.jar file, wait for some time until it completes the scan for the Eclipse IDE, and then click Install/Update.

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately, as it is auto-configured by Eclipse.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

For the code setup, clone the repository and follow the guidelines mentioned in the Code Contributions.

Importing and building a project

1. Open the project folder where pom.xml is present.

2. Open the command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true to build the project and wait for the build to complete successfully.

4. After building a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successfully importing of project, update the project by right-clicking on Project → Maven → Update Project.

Environment setup

1. For the environment setup, you need an external JAR that is available here with different versions. (E.g.: You can download kernel-auth-adapter.jar and add to the project Libraries → Classpath → Add External JARs → Select Downloaded JAR → Add → Apply and Close).

2. Clone mosip-config repository.

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

4. As ID Authentication is using two property files, id-authentication-default and application-default, you will have to configure them according to your environment. The same files are available here for reference.

Properties to be updated:

application-default.properties

• mosip.mosip.resident.client.secret = <current_password>.

• db.dbuser.password=<password>.

• mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

• Comment this out auth.server.admin.issuer.internal.uri in application-default.properties file because you already have this auth.server.admin.issuer.uri, and hence there is no need for auth.server.admin.issuer.internal.uri.

• mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json)

id-authentication-default.properties

• ......

• ......

5. To run the server, two files are required- kernel-config-server.jar and config-server-start.bat.

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

7. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

1. Open Eclipse and run the project for one time as Java application, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with the environment - "Auth-Internal-Service-Dev").

2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

4. Click Apply and then debug it (starts running).

Authentication Internal Service API

• For API documentation, refer here.

Demographic data normalization is the process of applying rules for formatting of the demographic data (such as the address) into a common format before demographic data matching is verified during the demographic authentication in IDA. For example, for address lines, the '1st Street' can be replaced with '1 st' and 'C/o' can be removed from both the input and database data before the match is verified. These rules will be different for different languages, and may be configured/implemented differently.

The ID-Authentication Demographic data normalization mentioned here is specific to the Demo-SDK reference implementation of the Kernel Demographic API. It takes the below configuration to apply the name and address normalization rules.

For any other custom implementation of the normalization, the Demo-SDK needs to be implemented accordingly.

Demographic name/address normalization using regular expressions and their replacement configurations

The below configuration is used to define the separator for normalizing regex (pattern) and the replacement word. The default is set to '='.

ida.norm.sep==

The format for configuring the name/address normalization rules for any language is given below:

ida.demo.<name/address/common>.normalization.regex.<languageCode/any>[<sequential index starting from 0>]=<reqular expression>${ida.norm.sep}<replacement string>

* name/address/common - type of normalization, common applies to both name and address

* languageCode - this is the code for languages like hin, eng, any('any' applies to any language)

If replacement string is not specified, the regular expression will be replaced with empty string.

Note: It is recommended that the sequence is not broken in the middle otherwise all normalization properties will not be read for the particular type.

Normalization rules for English language

ida.demo.address.normalization.regex.eng[0]=[CcSsDdWwHh]/[Oo]
ida.demo.address.normalization.regex.eng[1]=(M|m|D|d)(rs?)(.)
ida.demo.address.normalization.regex.eng[2]=(N|n)(O|o)(\\.)?
ida.demo.address.normalization.regex.eng[3]=[aA][pP][aA][rR][tT][mM][eE][nN][tT]${ida.norm.sep}apt 
ida.demo.address.normalization.regex.eng[4]=[sS][tT][rR][eE][eE][tT]${ida.norm.sep}st 
ida.demo.address.normalization.regex.eng[5]=[rR][oO][aA][dD]${ida.norm.sep}rd 
ida.demo.address.normalization.regex.eng[6]=[mM][aA][iI][nN]${ida.norm.sep}mn 
ida.demo.address.normalization.regex.eng[7]=[cC][rR][oO][sS][sS]${ida.norm.sep}crs 
ida.demo.address.normalization.regex.eng[8]=[oO][pP][pP][oO][sS][iI][tT][eE]${ida.norm.sep}opp 
ida.demo.address.normalization.regex.eng[9]=[mM][aA][rR][kK][eE][tT]${ida.norm.sep}mkt 
ida.demo.address.normalization.regex.eng[10]=1[sS][tT]${ida.norm.sep}1 
ida.demo.address.normalization.regex.eng[11]=1[tT][hH]${ida.norm.sep}1 
ida.demo.address.normalization.regex.eng[12]=2[nN][dD]${ida.norm.sep}2 
ida.demo.address.normalization.regex.eng[13]=2[tT][hH]${ida.norm.sep}2 
ida.demo.address.normalization.regex.eng[14]=3[rR][dD]${ida.norm.sep}3 
ida.demo.address.normalization.regex.eng[15]=3[tT][hH]${ida.norm.sep}3 
ida.demo.address.normalization.regex.eng[16]=4[tT][hH]${ida.norm.sep}4 
ida.demo.address.normalization.regex.eng[17]=5[tT][hH]${ida.norm.sep}5 
ida.demo.address.normalization.regex.eng[18]=6[tT][hH]${ida.norm.sep}6 
ida.demo.address.normalization.regex.eng[19]=7[tT][hH]${ida.norm.sep}7 
ida.demo.address.normalization.regex.eng[20]=8[tT][hH]${ida.norm.sep}8 
ida.demo.address.normalization.regex.eng[21]=9[tT][hH]${ida.norm.sep}9 
ida.demo.address.normalization.regex.eng[22]=0[tT][hH]${ida.norm.sep}0 
# Note: the common normalization attributes will be replaced at the end.
# Special characters are removed : . , - * ( ) [ ] ` ' / \ # "
# Replace special char with space. Trailing space is removed from property. As a workaround first replacing with " ." then removing the "."
ida.demo.common.normalization.regex.any[0]=[\\.|,|\\-|\\*|\\(|\\)|\\[|\\]|`|\\'|/|\\|#|\"]${ida.norm.sep} .
# Trailing space is removed from property. As a workaround first replacing with " ." then removing the "."
ida.demo.common.normalization.regex.any[1]=\\s+${ida.norm.sep} .
ida.demo.common.normalization.regex.any[2]=\\.${ida.norm.sep}

Normalization rules for Non-English language

For non-english languages, the non-english words needs to be converted into UTF-16 and then copied to the configuration. For example, convert the Unicode characters to UTF-16.

Before conversion: ida.demo.address.normalization.regex.hin[0]=पहली${ida.norm.sep}पहला

After conversion: ida.demo.address.normalization.regex.hin[0]=\u092a\u0939\u0932\u0940${ida.norm.sep}\u092a\u0939\u0932\u093e

Overview

What is ID Authentication?

MOSIP recommends using eSignet for authentication, which leverages the IDA module to ensure secure and unified identity verification. eSignet simplifies the process by streamlining authentication across services, ensuring compliance with MOSIP’s security protocols. This enables both governmental and private entities to securely authenticate residents without needing multiple solutions.

Authentication types

The following types of authentication are offered by MOSIP's ID Authentication (IDA) module and are utilized through eSignet for ID verification by external parties:

1. Yes/No Authentication

MOSIP offers a yes/no API that can be used for the verification of attributes supplied along with authentication factors. The API verifies the identifier and the provided demographic attributes and also validates other authentication factors such as the OTP or biometrics and responds with a yes or a no. Successful verification of the data results in a yes. This kind of API can be typically used to support the verification of a limited set of demographic data about the person or for simple presence verification when biometrics are used.

2. KYC Authentication

MOSIP additionally offers a KYC API, which can be used to get an authorized set of attributes for the resident in the response of the API. This API is intended for use by authorized relying parties to perform KYC requests. The authentication includes an identifier along with authentication factors such as OTP and biometrics. The information returned is governed by a policy. Different relying parties can be provided with different KYC data based on their needs. The policy helps implement selective disclosure as part of the KYC data. The data thus returned is digitally signed by the server and can be used by the relying party with confidence.

3. Multifactor authentication

The authentication APIs support multiple factors. These can be:

• Biometric: Finger, face, iris

• Demographic: Name, date of birth, age, gender, etc.

• OTP: One-Time Password Based on the level of assurance needed for the transaction, the relying party can decide which factors are sufficient for identity verification.

• Password-based authentication.

Biometric authentication is performed using third-party matcher SDK that performs 1:1 matches on a given modality. Each biometric modality is treated as an independent factor in authentication.

VID

All authentications in MOSIP operate on a 1:1 matching principle. This requires the authentication request to include an identifier for the individual, along with authentication factors to verify the identity. MOSIP supports multiple identifiers for each person, which enhances privacy and prevents profiling. The individual can be authenticated using their UIN or alternate identifiers like VIDs. When a VID is used, additional checks ensure it hasn't expired or been revoked. The expiration of a VID is governed by the policy set during its creation.

Tokenization

In certain contexts, identity verification can be performed anonymously for one-time use. However, when identity verification is tied to transactions requiring identity assurance, it becomes necessary to link the user's identity to the transaction. This is done by providing relying parties with a "sticky" token identifier, which can serve as a reference ID for the individual in their system. When authentication is successful, the APIs return a token. Depending on the relying party’s policies, the token may be random or "sticky." The relying party is expected to store this token for future reference, customer identification, and audit or redressal purposes.

Relying parties and policies

Consent

MOSIP has a provision for specifying the user consent associated with an authentication transaction. This can be stored for audit purposes and the authentication flow can be extended to verify the consent if needed.

Hotlisting

MOSIP has a provision to help protect against the misuse of identity. For any report of lost identity or detection of fraudulent activity by fraud, the module can require the temporary suspension of authentication activities on a user. This is enabled by the hotlisting feature. The authentication service checks if the identifier used is hotlisted and if so, the authentication process is aborted and fails. The hotlisting service can be used by helpdesk and fraud solutions to list and delist the identifiers that need to be blocked temporarily.

Overview

The services mentioned below are used by Authentication/e-KYC Partners.

• Authentication service- used to authenticate an individual's UIN/VID using one ore more authentication types.

• KYC Authentication service- used to request e-KYC for an individul's UIN/VID using one ore more authentication types.

The documentation here will guide you through the prerequisites required for the developer' setup.

Software setup

Below are a list of tools required in ID Repository Services:

1. JDK 11

2. Any IDE (like Eclipse, IntelliJ IDEA)

3. Apache Maven (zip folder)

4. pgAdmin

5. Postman

6. Git

7. Notepad++ (optional)

8. lombok.jar (file)

9. settings.xml (document)

Follow the steps below to set up ID Repository Services on your local system:

2. Unzip Apache Maven and move the unzipped folder in C:\Program Files and settings.xml to "conf" folder C:\Program Files\apache-maven-3.8.4\conf.

3. Install Eclipse, open the lombok.jar file and wait for some time until it completes the scan for Eclipse IDE and then click Install/Update.

4. Check the Eclipse installation folder C:\Users\userName\eclipse\jee-2021-12\eclipse to see if the lombok.jar is added. By doing this, you don't have to add the dependency of lombok in your pom.xml file separately as it is auto-configured by Eclipse.

5. Configure the JDK (Standard VM) with your Eclipse by traversing through Preferences → Java → Installed JREs.

Code setup

Importing and building of a project

1. Open the project folder where pom.xml is present.

2. Open command prompt from the same folder.

3. Run the command mvn clean install -Dgpg.skip=true to build the project and wait for the build to complete successfully.

4. After building of a project, open Eclipse and select Import Projects → Maven → Existing Maven Projects → Next → Browse to project directory → Finish.

5. After successful importing of project, update the project by right-click on Project → Maven → Update Project.

Environment setup

3. Create an empty folder inside the mosip-config with sandbox-local name and then copy and paste all config files inside sandbox-local folder except .gitignore, README and LICENSE.

Properties to be updated:

application-default.properties

• mosip.mosip.resident.client.secret = <current_password>.

• db.dbuser.password=<password>.

• mosip.kernel.xsdstorage-uri=file:///home/user/Desktop/tspl/mosip-config/sandbox-local/(i.e. sandbox-local folder location).

• Comment this out auth.server.admin.issuer.internal.uri in application-default.properties file because you already have this auth.server.admin.issuer.uri , and hence there is no need of auth.server.admin.issuer.internal.uri.

• mosip.identity.mapping-file=<Path_to_identity_mapping_json_file>. (For Example: file:///home/user/Desktop/tspl/mosip-config/sandbox-local/identity-mapping.json)

id-authentication-default.properties

• ......

• ......

6. Put both the files in the same folder and change the location attribute to sandbox-local folder in config-server-start.bat file and also check the version of kernel-config-server.jar towards the end of the command.

Example:

java -jar -Dspring.profiles.active=native -Dspring.cloud.config.server.native.search-locations=file:C:\Users\myDell\mosipProject\mosip-config\sandbox-local -Dspring.cloud.config.server.accept-empty=true -Dspring.cloud.config.server.git.force-pull=false -Dspring.cloud.config.server.git.cloneOnStart=false -Dspring.cloud.config.server.git.refreshRate=0 kernel-config-server-1.2.0-20201016.134941-57.jar.

7. Run the server by opening the config-server-start.bat file.

The server should now be up and running.

Below are the configurations to be done in Eclipse:

1. Open Eclipse and run the project for one time as Java application, so that it will create a Java application which you can see in debug configurations and then change its name. (e.g.: project name with environment - "Auth-Service-Dev").

2. Open the arguments and pass this -Ddomain.url=dev.mosip.net -Dapplication.base.url=http://localhost:8090 -Dspring.profiles.active=default -Dspring.cloud.config.uri=http://localhost:51000/config -Dspring.cloud.config.label=master in VM arguments.

3. Here, the domain URL represents the environment on which you are working (eg., it can be dev2.mosip.net or qa3.mosip.net).

4. Click Apply and then debug it (starts running).

Authentication Service API

Overview

The MOSIP Authentication SDK is a (Python-based) wrapper designed to simplify interaction with the MOSIP Authentication Service, enabling seamless integration of robust identity verification workflows into Python applications. This SDK abstracts complex details such as request/response structures, encryption/decryption mechanisms, and error handling, allowing developers to implement authentication workflows quickly and efficiently. Currently, the SDK supports OTP authentication and demographic authentication. Future updates will expand its functionality to include biometric authentication. Additionally, although the SDK is currently Python-based, we will soon be expanding support to other languages to offer broader compatibility.

Purpose

This page provides an overview of the Authentication SDK, outlining its functionality and providing a detailed process for installing and testing the IDA API using the SDK.

Why Use This SDK?

While building your solution around MOSIP, it is recommended to use eSignet, MOSIP's OAuth- and OIDC-based solution, for most online and scalable authentication needs due to its modern, standards-compliant design. However, the MOSIP Authentication SDK offers its own advantages, particularly in the flexibility it provides, making it an invaluable tool for addressing a wide range of identity verification requirements.

1. Ease of Integration: Simplifies the process of working with MOSIP’s APIs, reducing the learning curve for developers

2. Consistency: Provides a uniform interface for different authentication operations, ensuring a consistent experience

3. Security: Manages encryption and decryption of requests and responses, adhering to MOSIP's security standards

4. Flexibility: Supports multiple authentication methods, including demographic authentication, offering versatility in identity verification workflows

Key Features

1. Simplified API Interaction: Abstracts the complexity of direct API calls to MOSIP services

2. Support for Multiple Authentication Workflows: Includes controllers for both KYC-based and general authentication

3. Comprehensive Configuration: Allows customization via a configuration file (authenticator-config.toml)

4. Secure Handling: Automatically encrypts requests and decrypts responses to ensure secure communication

5. Error Management: Provides clear error messages and handling mechanisms

Controllers

The SDK provides two primary controllers, each designed for a specific authentication workflow:

1. kyc-auth-controller Used for Know Your Customer (KYC) authentication. This controller facilitates verification using demographic data or OTP verification. Reference: KYC Auth Controller API Documentation

2. auth-controller Used for general authentication of individuals, allowing verification based on a wide range of identifiers such as demographic authentication and OTP authentication. Reference: Auth Controller API Documentation

Method Reference

The SDK provides two key methods for authentication:

1. kyc Method: Used for KYC-based authentication by verifying an individual's demographic data and OTP.

2. auth Method: Handles general authentication requests with similar parameters as kyc.

Both methods require the individual's ID (individual_id), ID type (individual_id_type), demographic data (DemographicsModel), optionally an OTP, biometric data, and consent confirmation. These methods streamline identity verification processes for diverse use cases. Please refer below to know more about the methods.

kyc Method

Authenticates an individual using KYC-based workflow.

kyc(
    individual_id: str,
    individual_id_type: str,
    demographic_data: DemographicsModel,
    otp_value: Optional[str] = None,
    biometrics: Optional[List[BiometricModel]] = None,
    consent: bool = False
) -> Response

auth Method

Performs a general authentication.

auth(
    individual_id: str,
    individual_id_type: str,
    demographic_data: DemographicsModel,
    otp_value: Optional[str] = None,
    biometrics: Optional[List[BiometricModel]] = None,
    consent: bool = False
) -> Response

Common Parameters

• individual_id (str): The unique ID of the individual (e.g., VID, UIN)

• individual_id_type (str): Specifies the type of ID used (e.g., VID, UIN)

• demographic_data (DemographicsModel): A model containing demographic details such as name and address

• otp_value (Optional[str]): The One-Time Password (OTP) for authentication, if applicable

• consent (bool): Indicates if the individual has given consent for authentication

Installation Process

Pre-requisites:

Before beginning the installation and configuration of this SDK, the user must complete the following steps:

1. Register as an Authentication Partner (AP): Register their organization as an Authentication Partner. Please refer to this link here and follow the steps for registration.

2. Obtain the IDA-FIR(K21) Certificate: The user must possess the IDA-FIR(K21) certificate. The certificate can be obtained here.

3. Provide required details in the request:

   1. app id: IDA

   2. ref : IDA-FIR

4. Install pip on the machine: The user should install pip to manage Python packages. Installation instructions can be found here.

Configuration

During installation, the SDK must be configured by updating the authenticator-config.toml file. Please refer to this link here for the configuration file, This file contains essential details, such as:

• Service Endpoints

• Encryption Keys

• Timeout Settings

• Logging Settings

Refer to this link here for a sample configuration file to guide you in the setup process.

Installation

Install the SDK using pip:

pip install git+https://github.com/mosip/ida-auth-sdk.git@v0.9.0

Usage

Users who wish to try out this SDK should follow these steps:

1. Initialize the Authenticator: Set up the authentication instance to begin interacting with the SDK

2. Create Demographic Data: Prepare the necessary demographic information required for authentication

3. Perform Authentication: Execute the authentication request using the SDK

4. Handle the Response: Process and utilize the response received from the authentication service

For detailed guidance on performing these steps during the installation process, please refer to the model implementation below.

Basic Example:

from mosip_auth_sdk import MOSIPAuthenticator
from mosip_auth_sdk.models import DemographicsModel, BiometricModel

# Initialize the authenticator
authenticator = MOSIPAuthenticator(config={
    # Configuration settings (refer to authenticator-config.toml for details)
})

# Create demographic data
demographics_data = DemographicsModel(
    name="John Doe",
    address="123 Main Street"
    # Add other fields as required
)

# Perform KYC authentication
response = authenticator.kyc(
    individual_id="123456789",
    individual_id_type="VID",
    demographic_data=demographics_data,
    otp_value="1234",
    consent=True
)

# Handle the response
if response.status_code == 200:
    decrypted_data = authenticator.decrypt_response(response.json())
    print("Authentication successful:", decrypted_data)
else:
    print("Authentication failed:", response.json())

Error Handling

The SDK provides clear error messages and codes to help diagnose issues effectively. Review the errors field in the response for details.

Encryption and Decryption

All communication with the MOSIP service is securely encrypted. Use the decrypt_response method to handle encrypted responses appropriately.

Conclusion

The MOSIP Authentication SDK simplifies the integration of robust authentication workflows into Python applications, ensuring secure, efficient, and compliant identity verification. By abstracting the complexities of direct API interaction, the SDK enables developers to focus on building impactful solutions without having to manage intricate implementation details.

Get in Touch

If you require any assistance or encounter any issues during the testing and integration process, kindly reach out to us through the support provided below.

• Navigate to Community.

• Provide a detailed description about the support you require or provide complete information about the issue you have encountered, including steps to reproduce, error messages, logs and any other required details.

Thank you. Wishing you a pleasant experience!