Set Up App-Registration-Based Access for External Applications

If the Lasernet configuration that is deployed to an environment contains a configured Web Server input, that environment will host web services that external applications can connect to. The authentication that allows external applications to use those web services is based on a “client credentials” authentication flow.

To enable an external application or service (such as another Formpipe application or a third-party application) to connect to a web service, you must create an app registration for it (in the Lasernet Config web app) and then configure the app registration’s permissions to allow the app to connect. The Set Up an App Registration section below describes how to do this.

This page also describes how to reset the external application’s client secret.

Note

You will require an understanding of web services and how to make requests to them.

Set Up an App Registration

This process involves creating an app registration (to represent the external application) and then adding it to appropriate groups and security roles:

1. Sign in to the Lasernet Config web app.

2. In the Tools menu, click App Registrations.

3. In the toolbar, click Add.

4. In the Add App Registration window, enter an appropriate Name that identifies the external application, and (optionally) enter a Description.

5. By default, the Disabled checkbox is cleared. To create the app registration in an inactive state (so that you can make it active later), select the Disabled checkbox.

6. Click OK. The Lasernet Config app displays a Client Secret window that contains a Client Id and Client secret.

7. In the Client Secret window, click the copy buttons (at the end of each box) to copy the client ID and client secret. Store these in a secure place. You will need these when you configure the external application to authenticate with the web service. To unobscure the client secret, click the eye icon.

   Note

   After the Client Secret window closes, it is not possible to display the app registration’s client secret in the Lasernet Config app. So, it is important to copy the client secret and store it securely now.

8. Click OK. You have successfully created an app registration.

9. Add the app registration to an appropriate group:

   1. In the Tools menu, click Users and Groups.

   2. Click the group that you want to add the app registration to, and then click Edit in the toolbar. The Group Properties window opens.

   3. On the App Registrations tab, click Add, select the app registration from the Select application to add list, then click OK.

   4. Click OK to close the Group Properties window.

10. Add that group to the All Rights security role in the Web Server category:

    1. In the Tools menu, click Security Roles.

    2. In the main area of the window, click the All Rights security role in the Web Server category, and then click Edit in the toolbar.

    3. On the Members tab of the WebServer Role Properties window, click Add.

    4. In the Add Role Member window, select the group that you want to add to the role.

    5. Click OK. The group is added to the member list.

    6. Click OK to close the WebServer Role Properties window.

The application is now authorized to connect to Lasernet web services.

Note

The final part of the solution is to appropriately configure the Web Server input in the Lasernet configuration. For more information, see the Lasernet Developer Guide.

External Application Authentication Process

To use the web services hosted by a Lasernet environment, the application must use its client ID and client secret to request a token from the Config Server, and then include that token in the authorization header of its requests to the Lasernet web services. This process is the “client credentials” flow.

Request a Token from the Config Server

Config Server provides a token endpoint at https://<config server hostname>/lasernet/connect/token (appropriately substitute <config server hostname> ; if necessary, include a port number).

Make a POST request to the token endpoint. Ensure that the request:

• Has a content-type of application/x-www-form-urlencoded

• Includes the following URL parameters:

  • grant_type

    • Set to client_credentials.

  • client_id

    • Set to the application’s client ID.

  • client_secret

    • Set to the application’s client secret.

Example cURL command:

curl --request POST \
  --url 'https://localhost/lasernet/connect/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=6ea896d9-73f4-4a2f-adc4-3c813c0fdecf \
  --data client_secret=eWZyZDBBOE4yRWZ6dXZkWlpxajNkMnRDU09VRjd2QVVu

If the request succeeds, the response will include a token. Extract the token so that you can use it in web service requests.

Use the Token in the Authorization Header of Web Service Requests

Use the token in requests to the Lasernet web service by adding an authorization header to your requests in the following format:

Authorization: Bearer <token>

Replace <token> with the application’s token.

Reset the Client Secret

If you lose an app registration’s client secret, you must reset its client secret (to generate a new one). It is not possible to display an app registration’s current client secret. Follow these steps:

1. In the Tools menu, click App Registrations.

2. Click the app registration, then click Edit.

3. Click Reset client secret. The Lasernet Config app will display a Client Secret window that contains the application’s Client Id and a new Client secret.

4. Click OK to close the Edit App Registration window.

Edit the App Registration

To edit an app registration (so that you can enable or disable it or change its Name or Description), follow these steps:

1. In the Tools menu, click App Registrations.

2. Click the app registration, then click Edit.

3. Change the app registration’s properties.

4. Click OK to close the Edit App Registration window.