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).

• 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.

Tenant

A Tenant defines the minimum control unit of Alison-Server.

Each credential is created within a Tenant, which usually represents a complete organization.

A Tenant can contain credentials with certificates that were issued by different issuers (ACs) within the PKI of an organization.

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

Seat

A Seat represents an individual, holder of a credential.

Each Seat belongs to a particular Tenant.

A 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) 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.

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:

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

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:

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.

Any Alison-Client application can generate and install a certificate following 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 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.

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.

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.

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

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

# 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

Step 2- Pulling an image from Docker

# 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

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

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.

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: 

# 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.

# 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__.

{
	"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:

$ 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:

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):

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):

"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 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.

Volumes

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

Running Custom Tenant

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

# 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.

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:

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

General errors

OAuth2Client errors

Authorization errors