Authenticator Plugin

The Authenticator plugin is the main interface for eSignet, which provides methods to authenticate the end-user with control of the supported authentication factors.

The two main functionalities of the authenticator interface, KYC Auth and KYC Exchange, are depicted in the below diagram

Below is the eSignet authenticator interface:

public interface Authenticator {

    /**
     * Delegate request to authenticate the user, and get KYC token
     * @param relyingPartyId relying Party (RP) ID. This ID will be provided during partner self registration process
     * @param clientId OIDC client Id. Auto generated while creating OIDC client in PMS
     * @param kycAuthDto
     * @return KYC Token and Partner specific User Token (PSUT)
     * @throws KycAuthException
     */
    @Deprecated
    KycAuthResult doKycAuth(String relyingPartyId, String clientId, KycAuthDto kycAuthDto)
            throws KycAuthException;

    /**
     * Delegate request to exchange KYC token with encrypted user data
     * @param relyingPartyId relying Party (RP) ID. This ID will be provided during partner self registration process
     * @param clientId OIDC client Id. Auto generated while creating OIDC client in PMS
     * @param kycExchangeDto
     * @return signed and encrypted kyc data.
     * @throws KycExchangeException
     */
    KycExchangeResult doKycExchange(String relyingPartyId, String clientId, KycExchangeDto kycExchangeDto)
            throws KycExchangeException;

    /**
     * Delegate request to send out OTP to provided individual Id on the configured channel
     * @param relyingPartyId relying Party (RP) ID. This ID will be provided during partner self registration process
     * @param clientId OIDC client Id. Auto generated while creating OIDC client in PMS
     * @param sendOtpDto
     * @return status of send otp response.
     * @throws SendOtpException
     */
    SendOtpResult sendOtp(String relyingPartyId, String clientId, SendOtpDto sendOtpDto)
            throws SendOtpException;

    /**
     * supported OTP channel to validate in Send-otp request.
     * @return true if supported, otherwise false
     */
    boolean isSupportedOtpChannel(String channel);

    /**
     * Get list of KYC signing certificate and its details.
     * @return list
     */
    List<KycSigningCertificateData> getAllKycSigningCertificates() throws KycSigningCertificateException;

    /**
     * Authenticate and return individual's claims metadata if requested
     * @param relyingPartyId
     * @param clientId
     * @param claimsMetadataRequired
     * @param kycAuthDto
     * @return
     * @throws KycAuthException
     */
    default KycAuthResult doKycAuth(String relyingPartyId, String clientId, boolean claimsMetadataRequired, KycAuthDto kycAuthDto)
            throws KycAuthException {
        return doKycAuth(relyingPartyId, clientId, kycAuthDto);
    }

    /**
     * Providioned to return verified userinfo based on the provided verification requirement
     * @param relyingPartyId
     * @param clientId
     * @param kycExchangeDto
     * @return
     * @throws KycExchangeException
     */
    default KycExchangeResult doVerifiedKycExchange(String relyingPartyId, String clientId, VerifiedKycExchangeDto kycExchangeDto)
            throws KycExchangeException {
        return doKycExchange(relyingPartyId, clientId, kycExchangeDto);
    }
}

Note: For the latest version of the interface please check our code base - Authenticator.java

Who should implement the Authenticator plugin interface?

The authenticator plugin is implemented by Identity Systems, which wishes to integrate with eSignet to leverage the digital usage of identities.

An Identity system can be as simple as a table in a database or an Excel file storing user identity data or it can be a complex Identity System.

How to implement this plugin?

The Authenticator implementation class must be annotated with ConditionalOnProperty with mosip.esignet.integration.authenticator property.

Below is an example of how our Mock Identity System has implemented the eSignet Authenticator plugin.

@ConditionalOnProperty(value = "mosip.esignet.integration.authenticator", havingValue = "mock-authentication-service")
@Component
@Slf4j
public class MockAuthenticationService implements Authenticator {
    //Implement authenticator methods
}

For example, if OTP is one of the supported authentication factors in your identity system, the authenticator interface provides a method to,

• Define the supported OTP channels,

• Implement the send-OTP functionality

If the identity system does not support OTP based authentication then you could throw an exception with the appropriate error code.

    SendOtpResult sendOtp(String relyingPartyId, String clientId, SendOtpDto sendOtpDto) {
        throw new SendOtpException("not_supported");
    }

    boolean isSupportedOtpChannel(String channel) {
        return false;
    }

And also configure eSignet to expose only supported auth factors in the well-known endpoint.