Services Administration

Estimated Reading Time:  9 minutes

Overview

The Services Administration page enables users to create, view, edit, and delete external API (application programming interface) or authentication services. Examples of external services include Google Places API, Twilio API, OAuth2 Authentication Grants, and GPG Encryption/Decryption.

TIP  To learn how to set up external APIs in detail, visit our How to: Setup External APIs article.

NOTE  WSRBAC (workspace role-based access control) controls access to functions of Services Administration page. For more information on what roles can access and edit Services Administration data, view the Creator Role Administration article.

To access the Services Administration page:

1. At the top right of the top right of the Unqork Designer Platform, click Settings.
2. Click Administration.
3. Under Integration, select Services Administration.

A static image displaying the Services Administration page.

What You'll Learn

In this article, you'll learn how to:

Adding a Service

To set up an external API service in Unqork, you need access to the API. Companies and organizations usually make their APIs available on their website. You need to sign up and get all the necessary API information. Then, you can add the external API service to the Services Administration.

Once added, you can:

  • Reference services (external APIs) in logic components, like the Plug-In component.

  • Edit service details.

  • Delete services.

  • Check service status.

TIP  To learn how to set up external APIs in detail, visit our How to: Setup External APIs article.

To add a service in Services Administration:

1. Click + Add a Service. The Create New Service modal appears.
2. Enter a Service Title. This title is used to select the API in a Plug-In component.
3. Enter a Service Name. This name is permanent and should match the name given by the API provider.

NOTE  Service Names are case-sensitive. For example, an API treats the Service Names sendGrid and SendGrid differently.

4. Enable Allow Service Execution From Within Server Side Execution Only. The checkbox controls whether a browser or server-side execution starts the service.

NOTE  The service and the module using the service must have the same execution method set.

A static image displaying the Create New Service modal, the Service Title, Service Name, and Allow service execution features are highlighted.

5. Click Create. The service page loads for the new service. The service can now be configured.

Request & Response Setup

Request and response headers are sent with each request. Headers allow the client (browser) and the server to understand each other. They also let you add fields not explicitly defined in the Plug-In component. This is useful when passing fields that contain sensitive information. For example, if you want to access an OIDC ID token on the server, enter {{ _id_token }} in the Request Header field.

TIP  To learn more about OIDC, visit our OpenID Connect (OIDC) article.

1. Enter a Header Name.
2. Enter the Header Value.
3. To add more headers, click + Add Request Header.

Request Body Setup

Request Bodies are sent with each request. Unlike headers, body data doesn't typically store metadata or security credentials that are used across an application.

1. Enter a Body Name.
2. Enter the Body Value.
3. To add more bodies, click + Add Body Header.

Allowed Response Header Setup

Allowed Response Headers attach to the response sent back from the service (external API). Headers allow the client (browser) and the server to understand each other. They allow the client and server to pass information that isn't in the request or response.

1. Enter a Header Name to attach to the response sent back from the service.
2. To add more headers, click + Add Response Header.

Logging Setup

To store request and response bodies, use the Logging feature of Services Administration.

WARNING  Use caution when enabling this feature and storing sensitive information.

1. To capture information transmitted in the body of both requests and responses, select the Capture Request & Response Bodies toggle.

NOTE  The request body contains the information requested from the service. The response body contains information sent from the service.

A static image displaying a service's Loggin setting, the Capture request and response bodies setting is highlighted.

2. In the Retention Days field, set the number of days to store the retention and request bodies.

NOTE  If left blank, Retention Days default to 30 days.

3. Enter your Pagerduty Service Key if using this service.
4. Click Save Changes.

A static image displaying the a service's page, the Save Changes button is highlighted.

Your new service is now ready for integration in your applications.

Enabling SOAP Digital Signatures

Some SOAP (Simple Object Access Protocol) APIs require that you attach a SOAP digital signature to a service. A digital signature is a value computed with a cryptographic algorithm. When that value sends as part of a request, it lets the recipient verify the security and integrity of the incoming data. The Enable SOAP Digital Signature checkbox lets you attach a digital signature to any service that might use SOAP. For example, services using the WSSE Username Token Profile or SOAP Custom Header authentication types. When a service request comes in, the authentication processes. Then, the digital signature is added to the XML of the request body object.

TIP  You must specify a signing, digest, and canonicalization algorithm to set up the digital signature. To learn about each algorithm, see the W3C XML Signature Syntax and Processing documentation here: https://www.w3.org/TR/xmldsig-core1/#sec-AlgID. To learn more about SOAP digital signatures, see the W3C documentation here: https://www.w3.org/TR/SOAP-dsig/.

A static image displaying a Services's settings page, the Enable SOAP Digital Signature setting is highlighted and enabled.

To add a SOAP digital signature to a service:

NOTE  These instructions assume you already set up a service that requires a SOAP digital signature.

1. Select the Enable SOAP Digital Signature checkbox.
2. In the SOAP Digital Signature --- PFX or PKCS12 Encoded (hex) Private Key and Certificate Chain field, copy and paste the digital signature key.  
3. If required, copy and paste the passphrase into the SOAP Digital Signature --- PFX Passphrase field.
4. In the SOAP Digital Signature --- Signing Algorithm field, enter the signing algorithm.

NOTE  To reference a list of signing algorithms, visit http://santuario.apache.org/Java/api/constant-values.html#org.apache.xml.security.signature.XMLSignature.ALGO_ID_SIGNATURE_RSA_SHA256.

5. In the SOAP Digital Signature --- Digest Algorithm field, enter the digest algorithm .

NOTE  To reference a list of digest algorithms, visit http://santuario.apache.org/Java/api/constant-values.html#org.apache.xml.security.algorithms.MessageDigestAlgorithm.ALGO_ID_DIGEST_SHA256.

6. In the SOAP Digital Signature --- Canonicalization Algorithm field, enter the canonicalization algorithm.

NOTE  To reference a list of canonicalization algorithms, visit http://santuario.apache.org/Java/api/constant-values.html#org.apache.xml.security.transforms.Transforms.TRANSFORM_C14N_EXCL_OMIT_COMMENTS.

7. Click Add Service.
8. At the Success message, click OK.

Linking Services to an mTLS Certificate

mLTS (Mutual Transport Layer Security) certificates add an extra layer of security on top of other integrations. You can link mTLS certificates to most service authentication types available on the Services Administration page. To add certificates to your environment, though, you'll use Certificate Management.

NOTE  Some authentication types don't support using mTLS certificates. These include: Canada Post, Decryption (GPG), Encryption (GPG), FTP, Google Places, HMAC, Plaid, SFTP, and Twilio.

TIP  To learn how to add and manage certificates using Certificate Management, view our Certificate Management article in our In-Product Help.

To link a certificate to a service from Services Administration:

1. At the top right of the Unqork Designer Platform, click Settings.
2. Click Administration.
3. Under Integration, select Services Administration.
4. From the Active Services list, select an existing service. Or, configure a new service following the steps in Basic Service Setup.
5. Select the Enable Mutual TLS checkbox.

NOTE  When enabling mTLS, the  Prevent Redirect checkbox appears. Check this box to prevent the service from redirecting requests in the response.

6. From the Certificates drop-down, select a certificate.

TIP  You can click through to Certificate Management from Services Administration if you need to set up a new certificate. Click the Add a New Certificate link below the Certificates drop-down.

A static image displaying a service's settings page, the Enable Mutual TLS setting is enabled and highlighted.

7. Click Save Changes.

Editing a Service

You can change all settings for an external API service except the Service Name.

To change the setup of an external API service from the Services Administration page:

1. From the Active Services list, click the service title name of the service you want to edit.

An animated GIF displaying the Services Administration page. The animation shows the curson clicking on a Service's name to access the service's settings page.

2. At the top-right corner, click Edit.
3. Once you make your changes, click the Save Changes button.

Deleting a Service

Deleting a service from the Service Administration list requires Administrator access.

To remove an external API service from the Active Services list:

1. Find the service you intend to delete.
2. From the Manage drop-down, click Delete.

A static impage displaying the Services Administration page, the Manage drop-down is exposed for a service and the Delete button is highlighted.

3. Click Yes, Remove.

WARNING  Deleting a service permanently removes it from Services Administration. Any functions using the service become inoperable.

Checking the Status of a Service

The Check Status setting validates whether your external API service is available.

To check the status of an external API service from the Services Administration page:

4. Find the service you intend to check the status of.
5. From the Manage drop-down, click Check Status.

A static image displaying the Services Administration page, a service's Manage drop-down is exposed and the Check Status button is highlighted.

If the service is available, you’ll receive a success message. If the service is unavailable, you’ll receive an error message.

6. To dismiss the status message, click Okay.

Resources