| Table of Contents | ||||
|---|---|---|---|---|
|
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 |
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
Any client application can create a credential following these steps:
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.
| Info |
|---|
Currently only explicit authorization is supported. |
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.