Setup Chave Movel Digital

What is Chave Movel Digital

Chave Movel Digital is a means of authentication and digital signature certified by the Portuguese government. It allows the person holding a CMD to access various public or private portals and sign digital documents with a single login.

Chave Movel Digital associates a mobile phone number with a person’s identification document. If you have Portuguese citizenship, it associates with the Citizen Card or Identity Card. In the case of a foreign person, it associates with the passport, residence permit, or identity card.

Chave Movel Digital - Website

Chave Movel Digital is a service that is billable to your company but is free to use for any citizen.

How eSign uses Chave Movel Digital

eSign provides out-of-the-box integration with CMD, which allows users to sign their documents using CMD.

No developments are necessary, only configuration steps.

Important Acronyms

Acronym Meaning

CMD

Chave Movel Digital

AMA

Agencia para a Modernizacao Administrativa

Contracting Steps

We are describing the required steps for contracting and certifying CMD with eSign as they were when this document was written. It is possible for AMA to change the cerfification process at any time.

All the prerequisites described in the section must be complete before CMD can be used in a production environment:

1. Contract service with AMA

As a company you first need to contract the service provided by AMA.
If do not have any contact please refer to the their contact page: https://www.autenticacao.gov.pt/contactos

The contact must refer your intent to contract Chave Movel Digital’s signature.
Not to be confused with Chave Movel Digital’s authentication, which a completely separated feature.

2. Request credentials for AMA’s Pre-Prod Environment

You MUST request AMA to give you credentials for their pre-production environment so you can quickly start with integration tests and produce the required evidences for production certification.

3. Fill AMA’s Guidelines

Upon contracting Chave Movel Digital’s signature, AMA will provide an excel with a checklist for all guidelines that must be abide.
The answers to this checklist are specific to each company, and may vary based on your use case.

However, you can check our pre-populate check list to speed-up the fulfillment of the document.

The check list answers are in portuguese as requested per AMA.

4. Configure eSign to use CMD

Configure your non-production eSign instance to integrate with CMD pre-production environment.

See the Configuration section.

5. Produce Video Evidence of the process

Produce a video of eSign being used to sign with CMD between your business process, in your non-prod environment.

6. Provide Code Sample

AMA will request a snippet of the code used to sign with CMD.

Open a support ticket to request this information to eSign’s support team.
A contact of an eSign team member will be provided to include in the email thread with AMA, and we will share the code sample directly to AMA.

7. Provide Sign Document Evidence

Sign 5 documents with CMD in eSign e share the signed PDF’s wil AMA.

8. Collect Production Credentials

After all the steps above are completed, AMA will provide the following information:

Artifact Description

APP ID

The unique identifier of your institution when using CMD

Username

Unique username used to call CMD services

Password

Unique password used to call CMD services

Encryption Certificate

A certificate used by eSign to encrypt client credentials before sending them to the CMD service

Configuration

Once all the prerequisites are complete, you will now have all the information required to configure CMD in eSign for a productive environment.

Configure eSign

  1. Open your esign.config file and add a new block in the extensions section:

    This will enable the CMD signature feature.

    {
	"name": "signature-tfa-cmd",
	"class": "novabase.connect.paperless.esign.web.extensions.CMDSignatureProviderAddin",
	"params": {
		"appid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", (1)
		"url": "https://cmd.autenticacao.gov.pt/Ama.Authentication.Frontend/SCMDService.svc", (2)
		"basicUser": "xxxxx", (3)
		"basicPass": "xxxxx", (4)
		"cert": "${resources}/scmd.cer" (5)
	}
}
    1 Unique App ID provided by AMA (see: Required Credentials)
    2 Production endpoint for CMS service
    3 Username name provided by AMA to call CMS service.
    4 Password name provided by AMA to call CMS service.
    5 Path to the location of the Encryption Certificate provided by AMA.
    You may opt to leave the "cert" location as it is, and simply copy the Encryption Certificate to esign-home/resources/scmd.cer.
    Ensure Encryption Certificate is renamed to scmd.cer.

  2. Open your esign.config file and add a new block in the addins section:

    This will set the CMD signature as the default addin for TFA (Two-Factor) signatures.

    {
    "type": "artifact_tfa",
	"extension": "signature-tfa-cmd"
}

Enable CMD option in eSign

CMD signature is just a possible implementation of eSign’s TFA signature type, hence we will now refer to TFA during the configuration steps.

At this point, eSign should be fully integrated with CMD.
Now it is up to you to determine when should the possibility to sign with CMD be available.

Optional #1: Globally for all documents

If you want the CMD option to be available for every document that needs signing you simply need to make use of the property signing.signmethods in esign.config.

  1. Edit esign.config Add (or update) property signing.signmethods to include the list of all signature types you want to enable by default (you must include TFA).

    Example of the signing.signmethods property in esign.config
    {

  ...

  "signing.signmethods" : "HANDWRITTEN,SMARTCARD,CLICKTOSIGN,OTP,TRANSCRIPTION,TFA"
}
    Currently the TFA is already included in the default value of signing.signmethods so, unless you have changed this property, no actions might be required.

For more information on how to configure eSign, see: eSign Configurations

Optional #2: Enable CMD for specific documents

As an alternative to enable CMD for all documents, you may choose to enable CMD signatures for specific documents.

For this use case, we must add

Example of document creation request with support for CMD
{
    "artifact": "<BASE64>",

    ...

    "variables" : [

        ...

        {
            "name": "SIGN_METHODS",
            "value": "HANDWRITTEN,SMARTCARD,TFA" (1)
        }
    ]
}
1 List of all allowed signature types for this specific document (comma separated).
In this example, the document will allow signing the HANDWRITTEN, SMARTCARD and CMD.
When you explicitly specific the variable SIGN_METHODS only the signature types listed will be available for that document.
All other default signature types will not be available

Configure AMA Compliance

If these steps are not applied AMA will reject the certification.

Signing Context

Make sure that all documents created in eSign that may require CMD signatures include the variable ARTIFACT_NAME, where the value of this variable is the name of the process/document that the client is signing.
This information will be presented in the OTP message that AMA sends to the client.

Examples:

  • "Ficha de Informação Individual"

  • "Processo 123456789"

Present AMA’s terms and conditions in eSign

Since 1.11.6 this step is no longer necessary.

Go to: ESIGN_HOME/resources/locale/client/

  1. Change esign.en-US.properties to include the following entries:

modal_tfa_step1_confirmation.title=Signature Request
modal_tfa_step2_confirmation.title=Signature Confirmation
tfa_header=Document: #ID#
tfa_footer=By performing this action you are performing a non-repudible digital signature according do Chave Móvel Digital terms and conditions.<br>For more information about Chave Movel Digital check <a href="https://www.autenticacao.gov.pt/web/guest/politicas-e-informacao-sobre-chave-movel-digital" target="_blank">this link</a>

  1. Change esign.pt-PT.properties to include the following entries:

modal_tfa_step1_confirmation.title=Pedido de Assinatura
modal_tfa_step2_confirmation.title=Confirmação de Assinatura
tfa_header=Documento: #ID#
tfa_footer=Ao realizar esta ação está a realizar uma assinatura digital não repudiável de acordo com os termos e condições da Chave Móvel Digital.<br>Para mais informações sobre o serviço de assinatura da Chave Móvel Digital consulte <a href="https://www.autenticacao.gov.pt/web/guest/politicas-e-informacao-sobre-chave-movel-digital" target="_blank">este link</a>

Usage

This section is dedicated to the required steps for an end-user to sign with CMD.

Prerequisites

Activate Chave Movel Digital

A user will only be able to successfully sign with CMD after they activate their personal CMD.

Each user must follow the steps describe in the AMA portal to Activate the CMD.

CMD activation in pre-production is completely independent of the productive environment. Production credentials will not work on the pre-production environment.
Got here to go through your Pre-production CMD Activation.

Usage Experience

When the user opens a document configured to use CMD, if the user clicks on the signature field a new signature option will be available:

cmd step1

The user is than prompted to introduce the phone number associated with their CMD along with the personal PIN:

cmd step2

Afterwards, the user is notified via SMS (or CMD app) with an One-Time Password, which will be introduced in eSign:

cmd step3

If the credentials match the signature field will appear signed:

cmd step4