Abacus REST-API

The Abacus REST-API provides access to various REST WebService interfaces. The Abacus REST-API is designed for access using a Service-User that can be configured in the Abacus User Management. Q981, or in in Q910 for Abacus API's for application specific Entity Endpoints. A Service-User can only access Abacus via the available interfaces (access to the Abacus UI is not possible). The Service-Users are identified with a Client-ID and Client-Secret (Clientschlüssel), that can be copied from the Abacus User Management when the user is created.

Note: To create a Service-User for accessing the Abacus API (Rest-API's) for the application specific Entity Endpoints, please refer to the Program Q910. The API authentication process described below is also valid for Service-Users created via Q910.

The following Service User categories of Service Users are available on the Abacus installation.

Q981 Standard Service User (not Abacus-API access)
Q910 Abacus-API Service User for direct access via ClientId and ClientSecret
Q910 Abacus-API User Dependent Service User for access via an Abacus User with Web-Login

Select an option above to show the specific UI images below.

Setup of the Service User in Abacus UI (Q981)

The Abacus REST-API interfaces require a Service User that is configured in the Abacus User Management. The following general information shows how the service user can be created and configured in the Abacus User Management (Q981).

Note: Clicking with the mouse on the right (or left) half of the image will advance (or step back) through the various UI steps for creating a Service User.

>> <<

Setup of the Abacus-API Service User in Abacus UI (Q910)

The Abacus-API REST-API interfaces require a Service User that is configured in the Abacus User Management. The following general information shows how the service user can be created and configured in the Abacus User Management (Q981).

Note: Clicking with the mouse on the right (or left) half of the image will advance (or step back) through the various UI steps for creating a Service User.

>> <<

Setup of the Abacus-API User-Dependent Service User in Abacus UI (Q910)

The Abacus-API REST-API interfaces can be configured with a User-Dependent Service User that is configured in the Abacus User Management. The following general information shows how the User-Dependent service user can be created and configured in the Abacus User Management (Q910).

Note: Clicking with the mouse on the right (or left) half of the image will advance (or step back) through the various UI steps for creating a Service User.

>> <<

It is important to copy the Client-Secret (Clientschlüssel) for the Service User during the creation of the User. The Client-Secret is only shown directly after the generation and will not be displayed again in the User Interface. A new Client-ID can be generated in the User Management with the "Passwort ändern" button. Directly after the new Client-Secret is generated, the value will be displayed. Thereafter the Client-Secret will no longer be displayed in the USer Manangement UI. It is not possible to obtain the current Client-Secret. If the Client-Secret is lost or no longer known, a new Client-Secret must be generated.

User Authentication via REST-API

The Service User can be used using OAuth to register (login) via the REST-API. This technique requires several standard steps, that are common for various OAuth authentications. the Service User Client-ID and Client-Secret are required for the OAuth authenication.

Obtaining the Abacus Token-Endpoint

The Token-Endpoint can be obtained via the Abacus .well-known/openid-configuration URL. This returns a Token-Endpoint where the Access-Token for a specified Service-User can be requested.

Example Request:

GET /.well-known/openid-configuration HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
User-Agent: Java/11.0.6
Host: localhost:40000
Connection: keep-alive

Example Response:

HTTP/1.1 200 OK
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; speaker 'self'; fullscreen *
Server: Jetty(9.4.30.v20200611)
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json
Content-Length: 738

{
  "token_endpoint_auth_signing_alg_values_supported":["RS256"],
  "token_revocation_endpoint":"http://localhost:40000/oauth/oauth2/v1/token/revocation",
  "jwks_uri":"http://localhost:40000/oauth/oauth2/v1/certs",
  "end_session_endpoint":"http://localhost:40000/oauth/oauth2/v1/auth/logout",
  "id_token_signing_alg_values_supported":["RS256"],
  "registration_endpoint":"http://localhost:40000/api/oauth2-clients/v1/registration",
  "scopes_supported":["abacus.pad", "openid", "email", "profile", "offline_access"],
  "issuer":"http://localhost:40000",
  "authorization_endpoint":"http://localhost:40000/oauth/oauth2/v1/auth",
  "token_endpoint":"http://localhost:40000/oauth/oauth2/v1/token",
  "userinfo_endpoint":"http://localhost:40000/oauth/oauth2/v1/user/userinfo"
}

Note: The "token_endpoint" will rarely change, but the webservice client implementation should always obtain the current token_endpoint so that if changes occur, the client program continues to operate correctly.

Obtaining the Abacus User Access-Token

The Service User Access-Token can be obtained via the Token-Endpoint URL from the previous step. There are various ways of passing the Client-ID and Client-Secret in the request to obtain the Access-Token.

The Client-ID and Client-Secret can be hashed in a Basic Authorization HTTP Header key using Base64 (recommended)
The Client-ID and Client-Secret can be included as part of the request payload

Example Request with Authorization Header :

Example : Client-ID:Client-Secret als Base64
Authorization: Basic Base64[<Client-ID>:<Client-Secret>]

POST /oauth/oauth2/v1/token HTTP/1.1
Accept-Charset: UTF-8
Content-Type: application/x-www-form-urlencoded
Authorization: Basic OTAzZDQwMTctZmE5NS1lYTAxLTg2YjQtZjg1OTcxMjllZmJhOjIxYWM0MWVkLTA5OTctODE0OC1jNzM5LTU5Y2RhMDkxZTg3Nw==
User-Agent: Java/11.0.6
Host: localhost:40000
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 29

grant_type=client_credentials

Example Request with Client-ID and Client-Secret in Request payload :

POST /oauth/oauth2/v1/token HTTP/1.1
Accept-Charset: UTF-8
Content-Type: application/x-www-form-urlencoded
User-Agent: Java/11.0.6
Host: localhost:40000
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 127

client_id=<Client-ID>&client_secret=<Client-Secret>&grant_type=client_credentials

Example Response:

HTTP/1.1 200 OK
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; speaker 'self'; fullscreen *
Server: Jetty(9.4.30.v20200611)
Content-Security-Policy: default-src https: 'self'; img-src https: data: 'self'; frame-src 'self'; font-src https: data: 'self';
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json;charset=utf-8
Content-Length: 774

{
  "access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ...[abbreviated for display]...JFLh2RDzq-1aWN9X8waFvLskedjcLS5lOoeD7xIw",
  "token_type":"Bearer",
  "expires_in":600
}

The Access-Token (Type : "Bearer") is returned in the response. The "access_token" is valid for specified period of time (e.g. 600 seconds - 10 Minutes), after which a new Access-Token should be obtained. A access_token should be used for the duration of the valid time (or shortly before). A new Access-Token should not be created for each request. There is no requirement to logout.

If the authorization is related to the Service-User for the Abacus-API's (Q910), then the "scope" will also be returned in the response, to indicate the active scopes available for the Service-User, as shown in the following example.

{
  "access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ...[abbreviated for display]...JFLh2RDzq-1aWN9X8waFvLskedjcLS5lOoeD7xIw",
  "scope":"abacus.entity.customer.readwrite abacus.entity.subject.readwrite",
  "token_type":"Bearer",
  "expires_in":600
}

The available scopes can be used to verify the configured access for the Service-User to a particular API-Endpoint if there are issues accessing particular Endpoints.

Obtaining the Abacus User Access-Token for User-dependent Service-User ("Benutzerabhängig")

When an Abacus-API Service User is configured in Q910 with User-Dependent ("Benutzerabhängig"), then the Authorization is carried out via a normal Abacus-User, which must first be authenticated with a separate Abacus Login via the Abacus Menu. With the User-Dependent ("Benutzerunabhängig") configuration the Service-User only has a Client-ID, and no Client-Secret. This method of login also required a Login redirect-URL (callback), which must be accessible from the Abacus Server (i.e. "localhost" is generally not possible).

Call Abacus Login URL in the Browser with the Client-ID and the configured Login Redirect-Url. This displays the Abacus Login window
Log-in to Abacus with desired Abacus User-name and password
After the user successfully logs in, the redirect URL is called (GET) by Abacus with a "code" and "session_state" URL parameter
The Access-Token can be obtained via the Token-Endpoint URL, similarly to the normal Authorization, using a "grant_type"="authorization_code" together with the "client_id", "code" and "redirect_uri"

The first URL call to display the Abacus Login window in the Browser contains the "Client_ID", the "scope" and the "redirect-uri". The URL Parameter "response_type=code" is also included.

     https://{abacus-server}/oauth/oauth2/v1/auth?response_type=code&client_id={ClientId}&scope=abacus.entity.subject.readwrite abacus.entity.customer.readwrite&redirect_uri=https://my-callback-url.org/abacus_user_dependent/

The following parameters are required in the URL.

client_id - is the Client-ID of the Service-User configured in Q910
scope - is the scopes of the Abacus-API that will be accessed for the user (multiple scopes separated with a space). Both the Service-User and the Abacus User must have these scopes assigned in Q910 and Q981 for a successful authentication. A maximum of 25 scopes can be defined.
redirect-uri - is the Redirect-URL for the callback to retrieve the "code". The Redirect-URL must be configured for the Service-User in Abacus Q910, otherwise it will not be permitted

Note: Be sure to URL-Encode the Redirect URL and the scope values for the call as show in the example below :

     https://{abacus-server}/oauth/oauth2/v1/auth?response_type=code&client_id={ClientId}&scope=abacus.entity.subject.readwrite%20abacus.entity.customer.readwrite&redirect_uri=https%3A%2F%2Fmy-callback-url.org%2Fabacus_user_dependent%2F

The User will be required to Login via the Abacus Login window. Ensure that another user is not already logged in, otherwise the user session may be adopted from the currently valid user-session.

A Login window similar to the following will be displayed in the browser by calling the URL, where the user can enter the user-dependent authentication credentials.

If the following message is returned in the redirect-URI :

    RequestUri : ...?error_description=The+user+has+no+access+to+any+scope+requested.&error=invalid_scope&session_state=jZy%2F1B4vODxoZbnT1umNhBSeUd1ly1axq2nRP%2Bvck8k%3D.gRxiBZvgxLhq
    error_description=The user has no access to any scope requested.
    error=invalid_scope

then the user has not been allocated the required Scopes in Abacus program Q981 User management.

If the following message is returned :

    Redirect-URI ...?error_description=Too+many+scopes+requested.+Request+less+scopes.&error=invalid_scope&session_state=m9R0c3ZzkqaQA3oPjWu0JUYdQNP8DUaehlKrT9DvtjM%3D.P8BGGRUee8uc
    error_description=Too many scopes requested. Request less scopes.
    error=invalid_scope

then the specified user scopes is too long, and the scope list must be shortened. A maximum of 25 scopes can be defined.

After successful authentication of the Abacus user via the Abacus Login window, the redirect URL will be called (GET) from the Abacus Server with the following parameters :

     https://my-callback-url.org/abacus_user_dependent/?code=RUFOQUL024PJXIIL3HHLPCV5TH&session_state=OFA5UMoSTbuHlZJ6QDA2Hl8VZ0bUr192lozeV4v%2BEiM%3D.2Sf1lfrv1npQ

code - this value is required for the authorization step to retrieve the Access-Token. Value shown below as <Code> in request payload
session_state - this parameter can be optionally used to identify the current session

Depending on how the URL call and redirect_uri is implemented, the "code" for the authentication can be obtained directly via the callback, or by polling a further URL where the callback data would be saved.

The remaining step is to call the token endpoint to obtain the Access-Token

Example Request with Client-ID and Code in Request payload :

POST /oauth/oauth2/v1/token HTTP/1.1
Accept-Charset: UTF-8
Content-Type: application/x-www-form-urlencoded
User-Agent: Java/11.0.6
Host: localhost:40000
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 181

grant_type=authorization_code&client_id=<Client-ID>&code=<Code>&redirect_uri==https%3A%2F%2Fmy-callback-url.org%2Fabacus_user_dependent%2F

Note: The optional Client-Secret is also only required if the Service User was configured with "Trusted Client" / "Vertrauliche Client" in Q910 (additional payload parameter : &client_secret=<Client-Secret>)

Example Response:

HTTP/1.1 200 OK
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Feature-Policy: camera 'none'; microphone 'none'; geolocation 'none'; speaker 'self'; fullscreen *
Server: Jetty(9.4.30.v20200611)
Content-Security-Policy: default-src https: 'self'; img-src https: data: 'self'; frame-src 'self'; font-src https: data: 'self';
Cache-Control: no-store
Access-Control-Allow-Origin: *
Content-Type: application/json;charset=utf-8
Content-Length: 774

{
  "access_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJhdCtqd3Q...[abbreviated for display]...SbJZkuOm3D4UFMArFmbNzViGesFBb75kyqbaJmg",
  "refresh_token":"eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ...[abbreviated for display]...0oktFBgvm1HQOwHLXh4GYDpN50rZpHXxF2AhZdg",
  "scope":"abacus.entity.customer.readwrite abacus.entity.subject.readwrite",
  "token_type":"Bearer",
  "expires_in":600
}

For User-dependent authorizations, the refresh_token can be used to obtain a new access_token for the API session, without the user having to manually re-authenticate. The refresh_token will only be returned for the first User-dependent authorization. Subsequent authorizations using the refresh_token to refresh the access_token will not return a new refresh_token. The refresh_token returned by the first authentication can be re-used multiple times when obtaining a new access_token.

The validation period of the refresh_token is dependent on several factors. Generally, it is dependent on the Offline access configuration :

"Offline access" setting	Duration
Active	60 days
Disabled	10 hours.

The refresh_token is renewed every time the initial User-dependent access_token is obtained via the redirect_uri. If different API implementation use the same user on the Abacus server, the refresh_token maybe regenerated and then become invalid for the previous authentications. If the refresh_token is invalid, the User-dependent authorization must be started again with the Abacus User login.

Example Request with Client-ID and Refesh-Token in Request payload :

POST /oauth/oauth2/v1/token HTTP/1.1
Accept-Charset: UTF-8
Content-Type: application/x-www-form-urlencoded
User-Agent: Java/11.0.6
Host: localhost:40000
Accept: text/html, image/gif, image/jpeg, *; q=.2, */*; q=.2
Connection: keep-alive
Content-Length: 181

grant_type=refresh_token&client_id=<Client-ID>&refresh_token=<refresh_token>

Note: When using the "refresh_token" grant type it is not necessary to send the "redirect_uri" parameter.

Using the Abacus REST-API's

After obtaining the access-token via the OAuth-Endpoint, the REST-API interfaces can be accessed by including the Authorization header with other various API requests. Further information regarding general Abacus REST-API's can be located directly in the Abacus Server with the Swagger URL http://localhost:40000/swagger-ui/index.html or the Abacus API-HUB for application specific API's.

The Bearer access_token is used to authenticate the service user with other API request.

Example Request for various other API Endpoints using the Bearer access token:

GET /api/{various-endpoint-connections} HTTP/1.1
Accept-Charset: UTF-8
Accept: application/json
Authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IjEiLCJ0eXAiOiJKV1QifQ...[abbreviated for display]...JFLh2RDzq-1aWN9X8waFvLskedjcLS5lOoeD7xIw
User-Agent: Java/11.0.14.1
Host: localhost:40000
Connection: keep-alive