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. |
What You'll Learn
In this
- Add services.
- Enable SOAP digital signatures.
- Link services to an mTLS certificate.
- Edit a service.
- Changing workspace access.
- Delete a service.
- Check the status of a service.
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.
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.
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. |
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/.
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.
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. |
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. |
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. |
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