How-tos

Connecting and Configuring Services in Cloudentity

This article guides you through the process of connecting a service that you want to protect in Cloudentity.

About Services in Cloudentity

In Cloudentity, Application is defined as a Client and Service. Client can be understood as the OAuth 2.0 Client. but when it comes to services, essentially, the whole set of services in a Cloudentity Workspace constitutes the OAuth 2.0 Resource Server. Cloudentity recognizes that these days resources servers are composed of multiple services that collectively may have associated many access scopes and very often expose a large number of APIs. To reflect the the application architecture, make management easier and make it more intuitive for client application developers Cloudentity associates scopes, APIs to services.

Cloudentity also reflects microservices as services within a Workspace. These services have their own identity that is used to perform access control within distributed application. The internal microserivces may not be part of the resource server as while communicating between each other they don’t use access tokens issued by the Workspace authorization server.

This document explains how to add a Service in Cloudentity and assign scopes to it.

Add and Configure a Service

  1. Go to Applications > Services.

  2. Select Create Service.

  3. In the pop-up window, give your service a name and description and select Create. The service is added to the list.

  4. Configure the service. Follow the information below for details on each configuration form.

Configure Basic Settings

In the Overview page you can see the Service details and Service Capabilities panels.

  • Service details

    Parameter Description
    Name Name identifying this service
    Description Description identifying this service
    Access Token Audience Default Access Token audience present in Access Tokens issued by Cloudentity.
    Custom Access Token Audience Custom Access Token audience, overriding the default one.
  • Service capabilities

    Parameter Description
    OAuth Resource Server Controls if this service is an OAuth 2.0 Resource Server, where authorization is governed by scopes.
    API Server Allows for API-level service control. When enabled, you can define access control for individual APIs, including GraphQL APIs or APIs behind a gateway.

Configure Scopes

In simple terms, Scopes govern what the application can ask for in relation to this service. The service must be part of an OAuth 2.0 Resource Server. When the user grants their consent, requested scopes are included in the Access Token, meaning that the Client is now authorized to access the requested data.

This is a key access control component in Cloudentity, allowing you to perform more fine-grained authorization than that for an entire Resource Server (keep in mind that all OAuth 2.0 services in your Workspace essentially constitute an OAuth 2.0 Resource Server). Scopes should reflect specific service areas (service features, functions, APIs) to which access must be controlled and user consent given explicitly.

  1. Open the Scopes page from your service.

  2. Select Create Scope and fill in the form.

    Parameter Description
    Scope name Scope name. This is the name that OAuth clients will need to send with their authorization call. You can define a dynamic scope in a wildcard (dynamic) form by appending .* to the scope name. For example account.*.
    Display name Scope name shown to the user
    Description Scope description
  3. Select Govern Scopes to configure global settings related to authorization flows available for this service. These settings impact all scopes within this service.

    Parameter Description
    Human Users Controls whether or not the Authorization Code flow can be used with this service. If enabled, you can configure the policy for such flow.
    Machine Users Controls whether or not the Client Credentials flow can be used with this service. If enabled, you can configure the policy for such flow.
    3rd Party Developers Controls whether or not third party developers can subscribe to this service . If enabled, you can configure the policy for such flow.
    Dynamic Client Registration Controls whether or not dynamically registered clients can subscribe to this service. Define conditions dynamically registered clients need to meet to subscribe to a protected scope using a policy.
  4. Select the newly created scope and finish its configuration.

    Tab Description
    Details Edit basic scope information
    Governance Assign policies for each flow enabled via Govern Scopes
    Advanced Configure advanced settings
    Metadata Assign metadata to a scope in JSON format
  5. Check the preview panel. It shows the end user’s point of view with the current service configuration.

Configure APIs

Under APIs, you can specify the APIs exposed by the service, if your service is defined as an API server. If the APIs are behind a gateway, you can connect the gateway with all the APIs directly. Finally, you can import any Open API-compliant specification.

  • To add individual APIs:

    1. Select + API

    2. Define the API type (REST or GraphQL), method, and path.

    3. Optionally, assign an API Policy to your API.

    4. Select Add API to finish.

  • To add API Gateway:

    1. Select + Gateway API.

    2. Select any API Gateway connected to Cloudentity. If none are available, add an API Gateway first.

    3. Select Connect to finish.

  • To import an API specification:

    1. Select Import.

    2. Provide the specification in the form.

      Source Description
      URL URL pointing to an Open API-compliant specification
      File JSON or YAML file with your Open API specification
      JSON or YAML Paste the Open API specification directly as a JSON or YAML
    3. Select Import to finish.

Subscribe Clients to Scopes

Having added and configured your Services, you must subscribe Client Applications to the correct scopes.

  1. Go to Applications > Clients.

  2. Select a Client and open the Scopes page.

  3. Enable the necessary scopes on particular services for the Client. This Client will now request these scopes to be part of the Access Token and receive them if consent is granted.