Breadcrumbs

Securing Designer Services via API Management

xUML services that have been deployed from the Designer as a container are secured by default. However, these services are only usable internally and are not exposed to users outside the company. If you want to make them available to others, you can secure and publish them by creating a new API in API Management.

The following explanations apply to xUML services without user context (forms or role check).

Managing the Designer Service

support_manager_example.png

In the Designer, you have created a REST service that contains neither forms nor a process. 

Example:

We use a REST service named SupportAPI that handles support cases which are stored to a MongoDB.
container_running_open_admin.png

Choose the deployment target Container.

From the Service details page, open the service in the PAS Administration.

In the Administration, you can access the service details, which also contain the information about the service endpoints that you need to create a new API. Use icon admin_expand.png to expand the details of your endpoint:

service_details_endpoints.png

Creating the API

new_api.png

Open the API Management and select menu APIs > New API.
create_api.png

Enter a name and a description for the new API and create it.
rest_api_url.png

Now you need the information from the service details in the PAS Administration.

To access the internal URL of your REST API, in our example SupportAPI in the Endpoints tab, you need to expand the entry (see above). Click on the (internal) URL to copy it to the clipboard.
api_implementation.png

Switch back to API Management and open tab Implementation of your new API.

Paste the copied URL in field API Endpoint and click Save.
copy_descriptor.png

Open the Administration again and use icon admin_copy.png to copy the URL of the private descriptor.
api_definition.png

In API Management, open tab Definition of your API.

Do the following:

  1. Select the API Definition source YAML.

  2. Paste the copied URL of the private descriptor in field API Definition URL.

  3. Click Load Definition and verify that the definition is loaded to the text field.

  4. Click Save.

Securing the API

You created a new API, because you want to secure your service. Therefore, you need to create some plans for your API now.

Example: Our example service handles support cases. The API should be usable by two groups of users:

  • Users with limited permissions who can only create support tickets.

  • Support administrators who can create and manage support tickets.

go_to_organization.png

To create corresponding plans, open your organization. You can use the breadcrumb navigation on top of the API details page.
plan_tab.png

Open tab Plans and use button New Plan.
create_plan.png

Enter a name for your plan and a useful description before you create it.

Example:

We create a plan for our first use case (users with limited permissions).
policy_tab.png

If you want to create plans for users with limited access, you have to assign appropriate policies.

Expert Advice

Go to page (23.1.1) Policy Configuration for an overview on all policies supported by Scheer PAS API Management.

Open tab Policies and click the Add Policy button.
ignored_resources_policy.png

Select the Policy Type you want to assign and configure the policy according to your requirements.

Example:

We choose the (23.1.1) Ignored Resources and configure it so that support case creators cannot receive or delete support requests.
lock_plan.png

The policy is added to the plan, you are now able to lock it.

Only locked plans can be used by APIs in the organization. Refer to (23.1.1) Locking a Plan for more information.
lock_second_plan.png

In the same way, we create a second plan for support case administrators.

Administrators don't have any restrictions because they should be able to access all support tickets. Therefore, their plan has no policies assigned.
finish_api.png

Go to the API details page again and open tab Plans.

You have to do the following here:

  1. Attach the plans you want to use.

  2. Set Require Approval for the plans that are not to be available to everyone.

  3. Choose the visibility of the plans.

Expert Advice

Read more about the visibility concept on page The Concepts of API Management.

Example:

  1. Attach: We want to use both created plans, so both are attached to the API.

  2. Require Approval: Everyone should be able to use the API for support ticket creation, but we want to approve the users with admin permission. Therefore, the usage of plan Support Case Admin needs approval.

  3. Visibility: Both plans should be visible to all visitors of the API Developer Portal.
publish_api.png

You have completed the necessary steps to secure the service and can now publish your API.
api_in_portal.png

The API is available in the API Developer Portal. Users can now sign up for it.
Related Pages:
Related Documentation: