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.

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

client_id		acme
client_secret	acme_password
grant_type		client_credentials
scope			seat:jdoe@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 Credential

1. Obtain an OAuth2 Token.

Client must obtain an OAuth2 token from Alison-Server to access any service. In this case a scope is not required.

2. Create a Credential.

When creating a credential it is mandatory to indicate an Authorization Configuration. A parameter indicating the number of Multi Signatures can be sent too.

Authorization Configuration

This configuration specifies the type of authorization (explicit, implicit and oauth2) and any extra configuration associated with the chosen type. For example, in explicit authorization you have to configure either OTP or PIN or both are required. The configuration is indicated passing the ID of the configuration.

Multi Signature

This value specifies the maximum number of signatures that can be created in one request. Default is 1.

3. Add Second Factors.

Once the credential is created, it is necessary to add the required second factors according to the chosen configuration.

Credentials can be protected with PIN, OTP or both, but al least one of the second factors is required, otherwise the credential would be left unprotected. If more than one second factor is required, two calls to the service must be done indicating in each case the type of second factor that is being added.

PIN

When adding a PIN, a secret value must be specified. This value is the raw password that will be required when trying to access the credential.

OTP

When adding an OTP, no secret value must be specified because it is generated by the service. In the response the generated secret will be returned as well as any other information associated with the generated OTP, such as the issuer and the user.

After generating the secret it is necessary to confirm that the OTP has successfully been retrieved. When confirming the OTP an OTP Value must be sent.

4. Generate Key Pair.

After all required Second Factors has been added a Key Pair can be generated. In this case the key algorithm and length must be sent, as well as the CSR signature algorithm. When generating the Key Pair, a CSR is returned. This CSR must be signed by a CA, in order to get a Certificate.

5. Add a Certificate.

Once the CSR has been signed by a CA and a Certificate is obtained, it must be asociated with the credential. The Certificate must be sent with the complete Certificate Chain (root, intermediate and end certificates). It has to be sent in PKCS7 format. If the end Certificate Public Key does not match the stored public key an error will be returned.

Create a Signature

1. Obtain an OAuth2 Token.

Client must obtain an OAuth2 Token from Alison-Server to access any service. When requesting this token a scope must be specified. This scopes indicates the Seat that must be used in the following requests. The scope has the following format:

seat:jdoe@acme

2. List Credentials and Credential Info.

List

All stored credentials can be listed. The result of the list service is a list of IDs. Only the credentials of the Seat that appears in the scope of the OAuth2 Token are listed.

CredentialInfo

In order to retrieve the information of a credential the Credential Info service must be used, passing the Credential ID. Other parameters can be specified too, such as:

Certificates

Indicates if the certificate in Base64 must be returned. Values are: "none" (no certificate is returned), "single" (only end entity certificate is returned), "chain" (the whole certificate chain is returned). The default value is "single".

CertInfo

Requests to retrieve the information of the certificate in different attributes. If set to true, the Certificate will be parsed and all the information will be retrieved in different attributes. Default is "false".

AuthInfo

Request to return various parameters containing information on the authorization mechanisms supported by this credential (PIN and OTP groups). The default value is “false”.

3. Authorize Credential

When signing a hash, a SAD is required. A SAD is a token that allows access to the signature service. The token is attached to the information to be signed to increase the security. To obtain a SAD the Authorize Credential service must be used. This service requires, besides the Credential ID:

• numSignature: The number of signatures that will done with the SAD. This value must be less or equals to the number of multi signatures that the credential allows.
• hash: An array containing all the hashes to be signed. The number of hashes must be equals to numSignature.
• PIN: If the credential is protected with PIN, the PIN Value must be sent.
• OTP: If the credential is protected with OTP, the OTP Value must be sent.

If the PIN and OTP values are correct, a SAD is generated and returned. This SAD is associated with the hashes sent in the request, so trying to sign a different hash with this SAD will throw an error.

4. Create Signature

When creating a signature the following parameters are required:

• credentialId: The ID of the credential that will sign the hashes.
• SAD: The Signature Activation Data generated with the service Authorize Credential.
• hash: An array with all the hashes to be signed. All the hashes must be associated with the given SAD.
• hashAlgo: The algorithm used to hash the sent data. If not specified then the signAlgo must have the name of the hash algorithm.
• signAlgo: The algorithm that will be used to sign the data. It can have the name of the hash algorithm, for example SHA256WITHRSA. In this case the hashAlgo must NOT be specified. If only the signature algorithm is specified in this parameter, for example, RSA, then the hashAlgo must be specified.

If the sign process is successful, an array with all the signatures will be returned. The signatures will be returned in the same order as the hashes were sent.

Installation

Follow this /wiki/spaces/ASP/pages/503414829.

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:

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

General errors

OAuth2Client errors

There was no client that matches the specified clientId

Authorization errors