Image Removed

Page Tree

Table of Contents

maxLevel	1
indent	circle

Image Added

Description

Alison-Server is a Remote Signing Service Provider. It is a service that manages credentials on behalf of multiple users and allowing them to create a remote signature with a stored credential. A credential is the combination of a public/private key pair and a public x.509 certificate.

Alison-Server allows:

The generation of credentials, protecting them with second-factor authentication (such as PIN

and OTP

, TOTP, eMail OTP, SMS OTP, and Passkey).
Use the credentials to create remote signatures in different formats.

Its REST interface allows managing the complete life cycle of a credential, and it may require the participation of the holder for some tasks, such as the renewal or re-issue of it.

Alison-Server has a modular

and robust

architecture, which allows defining several redundant modules to operate in high availability mode, with clusters replicated by means of a shared database.

Alison-Server is designed so the same instance can be shared between different organizations. It is also possible to separate different users of the same organization into isolated groups.

Below are some fundamental terms that are useful to understand the configuration and architecture:

Alison-Server

It refers to the installation of a component

(distributed in .WAR format) that must be installed on an Application Server

,

such as Wildfly or IBM WebSphere.It is also distributed as a docker image and is the recommended way to install it

distributed as a Docker component. Each component can manage several tenants.

Tenant

A Tenant defines the minimum control unit of Alison-Server

.

, and it store certificates and credentials from related end users. Each credential is created within a Tenant, which usually represents a complete

organization

organisation.

A Tenant can contain credentials with certificates that were issued by different issuers (

ACs

Certification Authorities) within the PKI of an

organization

organisation.

Alison-Server can manage several Tenants within its configuration and each of them managed with its own security policy.

Info
When a product or service wants to

list certificates that are within several

access certificates stored into different Tenants, it must use an API-Key that allows access to all of them at the same time

.
The query can be sent to the Meta-Tenant (which includes all of them), but the subsequent access for the signature operations must be done by making specific use of the name of the Tenant of the certificate that you wish to use

.

Seat

A Seat represents an individual, holder of

a

credential.

Each Seat belongs to a particular Tenant.

A Seat

Each seat can contain several credentials.

Credential

A credential is the combination of a public/private key pair and an x.509 public certificate.

It is protected with second-factor authentication (

OTP and PIN

PIN, TOTP, SMS-OTP, eMAIL-OTP, Passkey) to improve security.

Second Factor Authentication

An authentication factor is a piece of information used to verify the identity of an entity.

A second-factor authentication means that in order to access the protected resource (the credential) the user must have something to prove his identity. Alison-Server supports the use of PINs, OTPs or both.

OAuthClient

An OAuthClient is an application that can make use of Alison-Server services.

It must have a key (API-Key) that allows access to all Alison-Server resources.

Related Product

Alison SDK js

Alison SDK allows a developer to integrate Alison Desktop in its pages in an easier way. Go to the Alison SDK documentation.

Debbie

Debbie is used to validate certificates and signatures.

OAuth Clients

Each OAuthClient has the following attributes:

ClientId

An identifier of the client.

ClientSecret

A secret that is used to authenticate to the authorization server

Authorized Grant Types

The OAuth2 grant type that the client can use. Currently, only "client_credentials" is supported.

Access Token Validity

Defines the validity time (in seconds) of the generated token. Only values greater than 0 are accepted.

An example of this definition is below:

Code Block
{ "clientId": "acme", "clientSecret": "acme_password", "authorizedGrantTypes": "client_credentials", "accessTokenValidity": 3600 }

Authorization

Alison-Server protects its resources with OAuth2 mechanisms. In order to access any resource, it is necessary to send an authorization token, which is provided by an authorization server.

In order to get a token the following information must be sent:

ClientId

The ClientId that was used when creating the OAuthClient.

ClientSecret

The secret that was sent when creating the OAuthClient.

Grant Type

The OAuth2 grant type that will be used for authorization. Currently, only "client_credentials" is supported.

Scope

A string containing information of the seat and tenant that will be used in the following requests. Both seat and tenant are required.

The scope's format is:

seat:$value tenant:$value

All the information must be sent as form-data.

Example:

Code Block
client_id acme client_secret acme_password grant_type client_credentials scope seat:jdoe@acme tenant:acme

Tokens can be checked through the "check_token" service. This is useful to check if the token has expired before making a request to a service.

Tokens also can be revoked through the "revoke" service. When a token is revoked, it cannot be used again.

Generate a certificate

Any Alison-Client application can generate and install a certificate following these steps:

1. Obtain an OAuth2 token.

Alison-Client must obtain an OAuth2 token from Alison-Server to access get the right privilege to create a WebCertificate into the tenant.

2. Obtain a Credential.

Each WebCertificate must be protected by at least a Credential.
Alison-Client needs to obtain the UUID of the Credential before of create the WebCertificate.
Alison-Client can create a brand new Credential or can use an existing one.
Several services must be called to create a new Credential. Each one of these services creates a specific type of credential (facebook, mobileDID, AlisonID-Gateway, etc).
The Credential doesn't need to be validated during the process of creation of the WebCertificate.
This duty had to be done by Alison-Client before creating the WebCertificate.

Info
See DiD-Gateway or AlisonID-Gateway documentation.

3. Create a WebCertificate.

Create a WebCertificate sending all the required fields to generate the key pair.
At least one Credential UUID must be sent to create a WebCertificate.
A dummy WebCertificate is created internally, which can be used to sign. This certificate has no reference to any external data of the client, so it can't be used as proof of identity. This certificate must be replaced by a public certificate following the next step.

Info
See createWebCertificate service for more information.

4. Update WebCertificate with a public X.509 certificate.

The dummy certificate created on the previous step should be replaced by a public X.509 certificated issued by a Certification Authority.

A PKCS#7 structure can be informed to replace the certificate.

Generate a signature

Any Alison-Client application can generate a signature follow these steps:

1. Obtain an OAuth2 token.

Alison-Client must obtain an OAuth2 token from Alison-Server to access get the right privilege to access a WebCertificate into the tenant.

2. Select a WebCertificate

Alison-Client can use the token created previously to list all the WebCertificates belonging to a customer.

The UUID's webCertificate is used to call the following command.

Alison-Client can also use a locally registered UUID.

3. Use WebCertificate to generate a signature

Call signBase64 service to generate a signature response of the data to sign.

Multiple data blocks (in Base64 format) can be signed in the same call.

A credentialValidationRequest must be sent in the call to validate the credential that protects the certificate.

This field must contain the credential's UUID and with the data to validate (when is required, for example, the OTP value or OCRA value).

4. Process the Signature

The signature response is returned in a JSON structure.

Alison-Client must process the response to extract the signature value and store it locally.

Installation

CertiSur distribute Alison Server from Docker Hub (https://hub.docker.com/).

Download Docker image

In order to download the images, the user must be registered in the aforesaid platform. Contact CertiSur to request access, and inform the Docker Hub profile to grant access to the docker image.

Step 1- Login using a Docker Hub account

Code Block

language	bash
theme	DJango
title	Login Docker Hub

# docker login -u <docker hub account>
Password:
WARNING! Your password will be stored unencrypted in /root/.docker/config.json.
Configure a credential helper to remove this warning. See https://docs.docker.com/engine/reference/commandline/login/#credentials-store
Login Succeeded

Info

title	Inform your docker hub account

You have to inform your docker hub account in order to authorize to download the package. Send an email to support@certisur.com.

Note

title	Security warning

It is possible to save the user’s credentials so as to login safely following the steps on this link(https://docs.docker.com/engine/reference/commandline/login/#credentials-store).

Step 2- Pulling an image from Docker

Code Block

language	bash
theme	DJango
title	Downloading image

# docker pull certisursa/alison-server:latest

latest: Pulling from certisursa/alison-server
a02a4930cb5d: Pull complete
b5ffff9dbcda: Pull complete
...
7e5f58de12ac: Pull complete
Digest: sha256:332ee89371399b7c6235465beb00fbd2071868fecee33fc14d04b87ba99b265d
Status: Downloaded newer image for certisursa/alison-server:latest
docker.io/certisursa/alison-server:latest

Step 3- Run Alison-Server docker image

Code Block

language	bash
theme	DJango
title	Run Alison Wizard

# docker run -d \
-it \
-p 8080:8080 \
--name wizard \
--mount type=bind,source="$(pwd)"/config/tenants, target=/opt/jboss/config/tenants \
certisursa/wizard:latest

Info

title	Alison Wizard default configuration

Alison Wizard docker image includes an ACME tenant inside. You must overwrite that definition to include your own company or project tenants.

Step 4- Test Alison wizard

Open your browser pointing to localhost:8080 (or the port defined by you) to access the URL where you published your Alison Wizard installation. You'll see the following image.

Installation
(on-premise)

Alison-Server can be installed on a fresh Linux server.

Recommended Platform

CentOS 7.5 +
Wildfly 9.0.2 +
Java 8
PostgreSQL 9.2.23 +

Download package

Download the last published version of the package. This package is distributed as a WAR file.

DB Creation and configuration

Alison-Server requieres a SQL database. It's recommended to install PostgreSQL.

Create a user:

Code Block

# su - postgres
# createuser -P --interactive alison-server-user
  Enter password for new role:
  Enter it again:
  Shall the new role be a superuser? (y/n) n
  Shall the new role be allowed to create databases? (y/n) y
  Shall the new role be allowed to create more new roles? (y/n) n

Create a database in UTF-8 format.

Code Block
# su - postgres # createdb -h localhost -p 5432 -E 'UTF-8' -U alison-server-user alison-server-db Password:

Setup configuration file and packages

The configuration file template must be adapted to indicate a database, user and password.

When Alison-Server is started, it checks if the database is correct and makes the corresponding changes.

In the example below, you must modify the __name of the servers__, __name of the database__, __tenants__.

Code Block

language	text

{
	"jpaConfig": {
    	"ddlAuto": "update",
    	"dialect": "com.certisur.common.PostgreSQLDialectCustom"
  	},
	"datasource": {
    	"url": "jdbc:postgresql://alison-serve.verisur:5432/alison-server-db",
    	"username": "alison-server-user",
    	"password": "passwd",
    	"drivername": "org.postgresql.Driver"
  	},
	"loggersConfig": [
		{ // Se guarda informacion todas las excepciones
    		"name": "com.certisur.common", 
    		"fileName": "alison-server-common-general-exceptions.log",  
    		"level": "DEBUG"
   		},
		{ // Se guarda informacion de la aplicacion
    		"name": "com.certisur.alison.server",   
    		"fileName": "alison-server-application.log",
    		"level": "DEBUG"
   		}
  	],
  	"tenants": [
    	{
      		"name": "tenantA",
      		"defaultWebCertificateType": "PKCS12DBWebCertificate"
    	},
    	{
			"name": "tenantB",
			"defaultWebCertificateType": "PKCS12DBWebCertificate"
    	}
  	],
  	"oAuthClientDetails": [
    	{	// client para acceso a token de corta validez y un solo tenant
      		"clientId": "publicAppCompanyShortValidity",  
      		"clientSecret": "publicAppCompanyPassword",
      		"authorities": "trustLevel:untrustedClient,apiGroup:signer,
							apiGroup:lister,tenantName:tenantA",
      		"authorizedGrantTypes": "client_credentials",
      		"accessTokenValidity": 10
		},
    	{
      		// client para acceso a token de larga validez y un varios tenants
      		"clientId": "trustedAppCompanyLongValidity",
      		"clientSecret": "trustedAppPassword",
      		"authorities": "trustLevel:trustedClient,apiGroup:signer,
							apiGroup:lister,tenantName:tenantA,tenantName:tenantB",
      		"authorizedGrantTypes": "client_credentials",
      		"accessTokenValidity": 3600
    	},
    	{
      		// client para acceso a token de larga validez y que permite generar
      		"clientId": "trustedAppCompanyMkilara",
      		"clientSecret": "trustedAppPassword",
      		"authorities": "trustLevel:trustedClient,apiGroup:lister,
							apiGroup:generator,tenantName:tenantA,tenantName:tenantB",
      		"authorizedGrantTypes": "client_credentials",
      		"accessTokenValidity": 3600
    	},    
		{
      		// client para administrar otras credenciales.
      		// Se utiliza para la inicializacion, pero puede ser eliminado 
			// en un ambiente operativo.
      		// La contraseña debe ser compleja.
      		"clientId": "oAuthAdmin",
      		"clientSecret": "SUPER_PASSWORD",
      		"authorities": "trustLevel:trustedClient,apiGroup:oAuthAdmin",
      		"authorizedGrantTypes": "client_credentials",
      		"accessTokenValidity": 0
    	}
  	],
  	"didProperties": {
    	"url": "https://homo-alison-did-gateway.verisur:8443/did-gateway-santander",
    	"clientId": "alisonServer",
    	"clientSecret":"alisonServer",
    	"timeoutInSeconds": 300,
    	"pushApproveSubjectTemplate": "${NUMERO_DE_OPERACION}",
    	"pushApproveTextTemplate": "Please confirm this operation: ${TEXTO_A_FIRMAR}",
    	"pushMessageSubjectTemplate": "Notification ${NUMERO_DE_OPERACION}",
    	"pushMessageTextTemplate": "Generated Code: ${CODE}"
  	},
   	"enableCredentialValidationBypass": false
}

Copy the configuration file to a server directory.

It is possible to administer a flexible version mechanism where different versions for different companies may be running on the same server. And also allow controlled migration between versions.

In the example shown below, two companies have version 0.1.4 installed, and one of them has dedicated to migrating to version 0.1.5. In this case, a possible structure can be:

Code Block

title	Configuration example directory

$ ls -lR alison-server/
alison-server/:
drwxrwxr-x 2 wildfly opera 4096 	Oct 2 17:20 014
drwxrwxr-x 2 wildfly opera 4096 	Oct 2 18:01 015

alison-server/014:
-rw-rw-r-- 1 wildfly opera 2991 	Oct 2 16:25 	alison-server-company-a.json
-rw-rw-r-- 1 wildfly opera 43707197 Sep 28 14:48 	alison-server-company-a.war
-rw-rw-r-- 1 wildfly opera 2991 	Oct 2 16:25 	alison-server-company-b.json
-rw-rw-r-- 1 wildfly opera 43707197 Sep 28 14:48 	alison-server-company-b.war
-rw-rw-r-- 1 wildfly opera 64 		Oct 2 17:10 a	pplication.properties

alison-server/015:
-rw-rw-r-- 1 wildfly opera 2991 	Oct 2 16:25 	alison-server-company-b.json
-rw-rw-r-- 1 wildfly opera 43707197 Sep 28 14:48 	alison-server-company-b.war
-rw-rw-r-- 1 wildfly opera 64 		Oct 2 17:10 	application.properties

where .war files are copies of each version renamed with the name of the company. The .json file is the one that corresponds to each company in its configuration and the application.properties file simply contains the following lines:

Code Block
configuration.fileName=/opt/alison-server/014/$CONTEXT_NAME.json

where reference is made to where the configuration file is located.

Configure Application Server

In the application server used, configure the following system variable (each one must exist for each different version of Alison-Server running):

Code Block
KEY: alison-server-0.1.4.config.location VALUE: file:/opt/alison-server/014/application.properties

Initialization of the database

When Alison-Server executes, it detects whether the database verifies should perform any update on it. If so perform a corresponding migration.
It also initializes those records that correspond to the authentication client, such as (the process adds the new items found):

Code Block

"oAuthClientDetails": [
	{
		// client to access a short time access and only one tenant
		"clientId": 			"publicAppCompanyShortValidity", 
		"clientSecret": 		"publicAppCompanyPassword",
		"authorities": 			"trustLevel:untrustedClient,apiGroup:signer,
								 apiGroup:lister,tenantName:tenantA",
		"authorizedGrantTypes": "client_credentials",
		"accessTokenValidity": 	10
	}
]

Alison Server Configuration

Alison Server docker image includes an ACME tenant inside. You must overwrite that definition to include your own company or project tenants.

Environment Variables

Configure the following variables to customize your tenants and platforms.

KeyDescriptionValue exampleENABLED_TENANTSList of enabled tenants separated by a comma.acme, verisurWIZARD_SECRET_KEY_BASE

Internal encryption key. It's a random 128 hexadecimal characters long key.

Invent your own key and replace it.

95820b3cea66376d0...95820BASE_INSTALLERS_PATHURL where Alison Desktop installers for Windows, Mac, and Linux are published. Depending on your configuration, this URL can be internal or external.https://installersDEBBIE_BASE_URLURL and port where Debbie service will be listening. Debbie is used to test and validate certificates.https://debbie.certisur.com:4443ENABLED_BROWSERSList of enabled browsers supported by the wizard.ie>=8,chrome,firefox,opera, edge,safariENABLED_PLATFORMSList of enabled platforms supported by the wizard.windows, mac, Linux

Volumes

The following volumes must be mounted on the Docker image to overwrite the variables of each defined tenant.

Source (host)Path (container)Description/home/opera/docker/wizard/tenants/opt/jboss/config/tenantstenant configuration folder/home/opera/docker/wizard/logs/opt/jboss/logslogs folder

Running Custom Tenant

After configuring your own tenant, launch a new docker image with the new configuration.

Code Block

language	bash
theme	DJango
title	Run Alison Wizard

# docker run -d \
-it \
-p 8080:8080 \
--name wizard \
--mount type=bind,source="$(pwd)"/config/tenants, target=/opt/jboss/config/tenants \
-e ENABLED_TENANTS=acme \
-e BASE_INSTALLERS_PATH=https://<wizard_url>/installers \
-e DEBBIE_BASE_URL=https://<debbie_url:port>/ \
-e WIZARD_SECRET_KEY_BASE=a95820b3cea66376d06bf3...9a86f5c4b741e6e187cb7085aaee \
certisursa/wizard:latest

License

Alison Wizard comes preinstalled with a universal license valid for up to 1 year.

To obtain a full license, contact CertiSur team (support@certisur.com) and inform the domain list (from all environments: development, staging, production) where the container will be published.

CertiSur will return a definitive license covering all the domains informed with a 3 years validity.

The license file must be included in each tenant configuration folder.

Plugins

These optional components may be installed on some browsers (Firefox, Chrome, Internet Explorer) to allow a different communication between the browser and Alison Desktop.

Plugins must be enabled by domain, similar to license.

Warning

title	Internet Explorer 11

In the particular case of Internet Explorer, you will download an ActiveX component, that will require administrator privileges to be installed.

Errors

When an error occurs a specific response is sent to the client that made the request. The structure of all error responses is the following:

Code Block
{ "error": <error>, "error_description": "<error_description>" }

General errors

errorerror_descriptioncauseinvalid_requestPayload is requiredThe service expects a payload in the request but none was sent

OAuth2Client errors

errorerror_descriptioncauseinvalid_requestClientId is null or emptyThe clientId was not sent or is an empty stringinvalid_requestClientSecret is null or emptyThe clientSecret was not sent or is an empty stringinvalid_requestAuthorizedGrantTypes is null or emptyThe authorizedGrantTypes was not sent or is an empty stringinvalid_requestUnsupported grant typeThe specified grant type is not currently supported by the serverinvalid_requestAccessTokenValidity is nullThe access token validity was not sentinvalid_requestThe Access Token Validity must be greater than 0The access token validity is less or equals 0invalid_requestThe client already existsThe value specified in clientId is already taken by another clientnot_foundThe client was not found

There was no client that matches the specified clientId

Authorization errors

errorerror_descriptioncauseinvalid_clientBad client credentialsEither client_id or client_secret or both are invalidunsupported_grant_typeUnsupported grant type: $grant_type_valueThe sent grant type ($grant_type_value) is not supportedinvalid_tokenToken was not recognizedWhen calling check_token with a token that does not existinvalid_tokenToken has expiredThe access token validity time has elapsed

Development & Integration

Alison-Server certificates can be reached using AlisonJS and AlisonGUI libreries.

The latest documentation can be found in this link: https://homo-alisonserver.certisur.com/swagger-ui/index.html

This documentation is also published in the Postman site: service endpoints.

Administration

Image Added

Access https://alisonserver-admin.certisur.net to create a new administrator.

Contact CertiSur Validation to request that your account will be associated with your company tenants.

You have to enter a valid email (it will be validated), and a complex password with:

Lower and uppercase letters
Numbers
Symbols
Minimum of

Your Corporate Contact will be contacted to approve your enrollment and your role.

Administration Console

Access administration console https://alisonserver-admin.certisur.net. Each user is enabled to watch or administer several Tenants, depending of the role defined for each one.

Functionalities found in this console:

Statistics: certificates and signatures quantities.
Last certificate and signature
Log information
Generate API-Keys to share with applications to allow listing certificates (by Tenant) and get Access-Token to share with End-User (certificate owner) to generate a signature.

Image Added

Version	Old Version 11	New Version Current
Changes made by	Julio D'Angelo	Armando Carratala
Saved on	Feb 13, 2020	Feb 18, 2024

Content Comparison

Versions Compared

Key

Description

Alison-Server

Tenant

Seat

Credential

Second Factor Authentication

OAuthClient

Related Product

Alison SDK js

Debbie

OAuth Clients

ClientId

ClientSecret

Authorized Grant Types

Access Token Validity

Authorization

ClientId

ClientSecret

Grant Type

Scope

Generate a certificate

1. Obtain an OAuth2 token.

2. Obtain a Credential.

3. Create a WebCertificate.

4. Update WebCertificate with a public X.509 certificate.

Generate a signature

1. Obtain an OAuth2 token.

2. Select a WebCertificate

3. Use WebCertificate to generate a signature

4. Process the Signature

Installation

Download Docker image

Step 1- Login using a Docker Hub account

Step 2- Pulling an image from Docker

Step 3- Run Alison-Server docker image

Step 4- Test Alison wizard

Installation(on-premise)

Recommended Platform

Download package

DB Creation and configuration

Setup configuration file and packages

Configure Application Server

Initialization of the database

Alison Server Configuration

Environment Variables

Volumes

Running Custom Tenant

License

Plugins

Errors

General errors

OAuth2Client errors

Authorization errors

Development & Integration

Administration

Administration Console

Installation
(on-premise)