Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Editorial


Excerpt
The REST-based administration web service makes it possible to configure parts of Digital Access component without using the graphical user interface. This is very useful if parts of the configuration needs to be done automated or when using Nexus PRIME as main frontend. 

You find a list of all supported configuration items, as well as a detailed documentation of the endpoints, within the Digital Access component appliance itself.

Use the URL https://<hag admin service dns name>:8443/swagger to find the documentation, as well as an editor to test the interface directly.

When integrating the web service endpoints in your client, you need to authorize your client first. This is done using OAuth 2.0 that is integrated in Digital Access component itself. To learn more about Digital Access component and OAuth 2.0, read the following article: Configure OAuth 2.0 in Digital Access

This article describes how to enable OAuth 2.0 authorization for the administration web service.


Expandall

Prerequisites

Expand
titlePrerequisites

-

Step-by-step instruction

Expand
titleLog in to Digital Access Admin
  1. Log in to Digital Access Admin with an administrator account.


Expand
titleEnable OAuth 2.0

Excerpt Include
Configure OAuth 2.0 in Digital Access
Configure OAuth 2.0 in Digital Access
nopaneltrue


Expand
titleAdd scope
  1. In Digital Access Admin, go to Manage System.
  2. Click OAuth2 Configuration > Add scope.
  3. Enter Name, for example WS.
  4. Enter Key and Value and click Add description.
  5. Click Save.


Expand
titleAdd client

In order to use the web service you need to specify an OAuth 2.0 client that can authorize against the service. 

  1. In Digital Access Admin, go to Manage System.
  2. Click OAuth2 Configuration > Add client.
  3. In the General Settings tab, enter a Display Name.
  4. Enter a Client ID and define a Client Secret. Both of these values will be used to authenticate against the web service.
  5. In Redirect URI add a random value. The redirect URI is not needed, but the field is mandatory. Click Add.
  6. In the Privileges tab, select Client Credentials as Grant Type.
  7. Add the scope that was created in the previous step (see Add scope) to Selected Scopes.

    Warning

    Make sure the scope is not used somewhere else to reduce the risk of unauthorised access.


  8. Click Save.


Expand
titleCreate web resource

In order to use the web service you need to specify a web resource that can authorize against the service.

  1. In Digital Access Admin, go to Manage Resource Access.
  2. Click Web Resources > Add Web Resource Host...
  3. Enter a Display Name.
  4. For Host enter the ip address of the Administration Service. This can be 127.0.0.1 if the Administration Service is on the same appliance as the Access Point.
  5. Remove HTTP Port value and add value for HTTPS Port, e.g. 443.
  6. Disable the resource to be available in the portal within the Portal Settings.
  7. Click Next.
  8. On the next page, click Add Access Rule... and add an Access Rule of type OAuth2 Bearer Token. To do this, select the client that was created in one of the previous steps. Once the client is selected, add the corresponding scope to the list of Selected Scopes
  9. Click Next and confirm the access rule by clicking Next again.
  10. In the Access Rules tab, remove Any Authentication from the list of Selected Access Rules.
  11. Click Next.
  12. Click Next on the page for Link Translation.
  13. Click Advanced Settings...
  14. Select Reserved DNS Mapping from the list of Link Translation Type.
  15. Select a dns name for Mapped DNS Name for HTTPS. If you have not configured a dns name yet, refer to Global resource settings in Digital Access. This can also be done later after the new web resource was saved.
  16. As Internal cookies enter value WA_INTERNAL_ID
  17. Click Next.
  18. Click Finish Wizard.


Expand
titleConnect to web service

To connect to the web service, use a web service client tool of your choice. Before accessing the web service endpoints, request an access token with grant type Client Credentials from the access token URL https://<hag access <access point dns name>/https/api/rest/v3.0/oauth/token.

You can now use the API using https://<admin service dns name>:<admin service port>/rest/v2, for example: https://administration-service.nexustest.com:8443/rest/v2, passing the HTTP header as Authorization: Bearer <token>. 


This article is valid for Smart ID 20.11 and later.

Related information