Image Removed

Table of Contents

maxLevel	1
indent	circle

Page Tree

Image Added

Description

Alison-Server is a

product that allows the generation, installation and use of X.509 certificates to generate signatures in multiple

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, 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

certificate

credential, and it may require the participation of the holder for some tasks, such as the renewal or re-issue of it

.Each certificate can be protected by a security mechanism

.

Among the available mechanisms is:

Password: entered by the user and required to enable action on the private key,

2FA: mechanism of multiple authentication factors, such as OTP or PUSH message, managed by AlisonID-Server,

OpenID: identity providers, such as Facebook or twitter, that have been associated with the certificate at the time of its generation and installation.

Alison-Server has a modular

and robust

architecture, which allows

to define

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

Alison-Server is designed

to be shared

so the same instance can be shared between different organizations. It is also possible

, for a organization

to separate different users of the same organization into isolated groups.

Below are some fundamental terms that are useful to understand

their

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

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

Tenant

A Tenant defines the minimum control unit of Alison-Server

.Each certificate is issued

, 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

contains

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 certificate

credential.

Each Seat belongs to a particular Tenant.

A Seat

Each seat can contain several credentials.

WebCertificate

This structure represents a X.509 Certificate resident within Alison-Server.

Its structure is returned in the service that allows to list all the certificates of which an individual owns.

Its identification (uuid) is subsequently used to perform signature operations.

Credential

A credential represents a mechanism of protection or access to the WebCertificate.

Since there may be various protection mechanisms, such as password or 2FA, the representation of the protection mechanism within Alison-Server is performed by means of a Credential.

Although not usual, a Credential can be shared to protect different WebCertificates

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 (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 developer to integrate Alison Desktop in its pages in a 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 vlues greate 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 neccessary 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

Generate a certificate

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

1. Obtain a 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 create a specific type of credential (facebook, mobileDID, AlisonID-Gateway, etc).
The Credential doesn't need be validated during the process of creation of the WebCertificate.
This duty had to be done by Alison-Client before of 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 que 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 external data of the client, so can't be used as a prove 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 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 a OAuth2 token.

Alison-Client must obtain a 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 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 protect 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 into 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, 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 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

El template del archivo de configuración debe ser adaptado para que indique la base de dato, usuario y contraseña del mismo.Cuando Alison-Server es iniciado verifica si la base de datos es la correcta y realiza las adaptaciones correspondientes.En el ejemplo que aparece a continuación se debe modificar el __nombre de los servidores__, __nombre de la base de datos__, __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
}

Copiar el archivo de configuracion a un directorio del servidor.
Es posible administrar un flexible mecanismo de versiones donde en un mismo servidor puedan estar ejecutando distintas versiones para distintas company. Y tambien permitir la migración controlada entre versiones.
En el ejemplo que se muestra a continuación, dos compañias tienen instalada la version 0.1.4, y una de ellas ha dedicido migrar a la version 0.1.5. En este caso, una estructura posible puede ser:

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

donde los arhcivos .war son copias de cada version renombrados con el nombre de la company. El archivo .json es el que le corresponde a cada company en su configuracion y el archivo application.properties contiene simplemente la siguiente lineas:

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

donde se hace referencia a donde se encuentra el archivo de configuración.

Configure Application Server

En el application server utilizado configurar la siguente valiable de sistema (tiene que existir cada una de ellas por cada version distinta de Alison-Server ejecutandose):

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

Inicializacion de la base de datos

Cuando Alison-Server ejecuta detecta si la base de datos verifica si debe realizar alguna actualización sobre la misma. Realiza una migración correspondiente.También inicializa aquellos registros que corresponden al cliente de autenticación, tales como (el proceso agrega los nuevos elementos encontrados):

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 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 of 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 browser supported by the wizard.ie>=8,chrome,firefox,opera, edge,safariENABLED_PLATFORMSList of enabled platforms supported by the wizard.windows,mac,linux

Volumes

Following volumes must be mounted on the Docker image to overwrite 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 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, stagging, production) where the container will be published.

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

License file must be included in each tenant configuration folder.

Plugins

This 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 occures, and error is sent as response. The structure of all error 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 non 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 specfied 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 recognisedWhen calling check_token with a token that does not exist

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 7	New Version Current
Changes made by	Former user	Armando Carratala
Saved on	Feb 12, 2020	Feb 18, 2024

Content Comparison

Versions Compared

Key

Description

Among the available mechanisms is:

Password: entered by the user and required to enable action on the private key,

OpenID: identity providers, such as Facebook or twitter, that have been associated with the certificate at the time of its generation and installation.

Alison-Server

Tenant

Seat

WebCertificate

Credential

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 a OAuth2 token.

2. Obtain a Credential.

3. Create a WebCertificate.

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

Generate a signature

1. Obtain a OAuth2 token.

2. Select a WebCertificate

3. Use WebCertificate to generate signature

4. Process the Signature

Installation

Download Docker image

Step 1- Login using a Docker Hub account

Step 2- Pulling 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

Inicializacion de la base de datos

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)