Creating Inbound Apps

There are two main methods for creating Inbound Apps in Descope:

1. Manual Creation - Create and configure inbound apps manually through the Descope console
2. Dynamic Client Registration (DCR) - Allow OAuth clients to register themselves automatically

Method 1: Manual Inbound App Creation

To manually create an Inbound App in Descope, follow these steps:

1. Navigate to the Inbound Apps page of the Descope console.
2. Click + Add Inbound App to create a new Inbound Application.
3. Define the App Name and Description (both can be edited later).

Once the application is created, you can configure its settings, including:

• App Details
• Scopes (Permissions & User Data)
• Connection Information
• Consent Management

Inbound App Details

This section allows you to configure key information about the inbound app.

• Logo (Optional): Upload a logo for the application. This will be displayed during user consent flows.
• Inbound App Name (Required): The name of the third-party application.
• Description (Optional): A short description of the app.
• App ID (System Generated): A unique identifier for the application (cannot be changed).

Scopes

Scopes define what permissions and user data the third-party application can access.

Permission Scopes

Permission scopes allow the inbound app to perform specific actions on behalf of the user or tenant. If using Descope's RBAC model, these scopes are mapped to roles, ensuring that access is granted only to authorized users.

• Name (Required): The unique identifier for the permission scope.
• Description (Required): A brief summary of the permission.
• Roles (Optional): Assign roles if RBAC is enabled, restricting scope access to users with the appropriate role.

User Information Scopes

These scopes define what user data is shared with the third-party application. The data can include built-in Descope attributes (e.g., email, name) or custom attributes that your organization defines.

• Name (Required): The unique identifier for the user data scope.
• Description (Required): A summary of the data being shared with the third-party application.
• User Attribute (Required): The specific user attribute mapped to this scope. Access to this data follows Descope's role-based authorization (RBAC) model, ensuring proper permissions are enforced.

User Consent and Role-Based Restrictions

This means:

• If a scope requires a role that the user does not have, they will not be able to grant consent for it.
• Only users with the correct RBAC roles will have the ability to approve or manage consent for those specific scopes.

By enforcing role-based user consent, Descope ensures that only authorized users can share sensitive data or grant permissions, maintaining strong access control and compliance.

Connection Information

This section contains configuration details needed to integrate the inbound app with Descope.

• Flow Hosting URL (Required): The URL where the consent flow is hosted. It can be:
  • api.descope.com
  • Your custom domain
  • A self-hosted instance of the consent flow.
• Approved Callback URLs (Optional): The URLs Descope is allowed to redirect users to after authentication.
• Client ID (System Generated): The unique identifier for the application.
• Client Secret (System Generated): The shared secret used for authentication.
• Discovery URL (System Generated): Provides OpenID Connect configuration details, including supported scopes, public keys, and endpoints.
• Issuer (System Generated): The issuer URL used for verifying identity tokens.
• Authorization URL (System Generated): The endpoint for initiating authentication (https://api.descope.com/oauth2/v1/apps/authorize).
• Access Token URL (System Generated): The endpoint for retrieving access tokens (https://api.descope.com/oauth2/v1/apps/token).

Method 2: Dynamic Client Registration (DCR)

Dynamic Client Registration allows OAuth clients to register themselves with your OAuth server automatically, which is particularly useful for protecting MCP (Model Context Protocol) servers.

This feature enables seamless integration with MCP clients like Cursor and Claude Desktop that need to dynamically register as OAuth clients.

Enabling Dynamic Client Registration

To enable DCR for your project:

1. Navigate to the Inbound Apps page of the Descope console.
2. In the top right, click on the Inbound App Settings icon.

3. Toggle Enable dynamic client registration for your project.

Once enabled, you can configure the following DCR settings:

Approved Scopes List

Configure the list of scopes that are approved for granting as part of the DCR process:

• Name: The name of the scope. This is what will be included in the scope parameter of the OAuth request, and in the OAuth tokens
• Description: A brief description of what the scope allows
• Roles: Map the scope to specific Descope roles for RBAC enforcement
• Mandatory: Toggle whether this scope is required for all DCR registrations

Empty Scope Handling

By default, DCR handles empty scope requests automatically. This is useful when your OAuth client doesn't request any scopes automatically. You can toggle this behavior on or off based on your security requirements.

When your OAuth client authorizes with an inbound app created with DCR, without any scopes, the end user will simply be able to register the app, but the token will not include any scopes, and thus will not have access to any protected APIs that have scope validation. The consent screen will simply ask the user to "authorize" the app, without any additional information.

Flow Hosting URL

Set the Flow Hosting URL to the URL of the consent flow you wish to run for DCR registrations.

• Flow Hosting URL (Required): The URL where the consent flow is hosted. It can be:
  • api.descope.com
  • Your custom domain
  • A self-hosted instance of the consent flow.

Approved Redirect URLs

To restrict registration to specific applications, you can configure approved redirect URLs.

This ensures that only applications with matching redirect URLs can register through the DCR process, providing an additional layer of security.

For example, if you want to allow only certain OAuth clients to connect, you can use a pattern like:

cursor://anysphere.cursor-retrieval/oauth/*/callback

In this example, the * acts as a wildcard for the client-specific portion of the redirect URL.

If you are using Cursor MCP, the * would match the mcpServer name defined in your Cursor mcp.json file.

The /register Endpoint

When DCR is enabled, clients can register themselves using the /register endpoint. This endpoint accepts a POST request with the following parameters:

Required Parameters

• client_name (string): The name of the client application
• redirect_uris (array of strings): Array of redirect URIs that the client will use. Must contain at least one valid URL.

Optional Parameters

• client_uri (string): URL of the client's home page
• logo_uri (string): URL of the client's logo
• logo_content (string): Base64-encoded logo content
• scope (string): Space-separated list of requested scopes
• description (string): Description of the client application
• token_endpoint_auth_method (string): Authentication method for the token endpoint
• grant_types (array of strings): Array of grant types the client will use
• response_types (array of strings): Array of response types the client will use
• consent_flow_id (string): ID of the consent flow to use for this application
• login_page_url (string): Custom login page URL for the application

Example Registration Request

{
  "client_name": "My MCP Client",
  "redirect_uris": ["cursor://anysphere.cursor-retrieval/oauth/myserver/callback"],
  "scope": "read:user write:user",
  "client_uri": "https://myclient.com",
  "logo_uri": "https://myclient.com/logo.png",
  "description": "A client application for MCP server integration",
  "token_endpoint_auth_method": "client_secret_basic",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "permissions_scopes": [
    {
      "name": "read:user",
      "description": "Read user information",
      "roles": ["user"]
    }
  ],
  "attributes_scopes": [
    {
      "name": "profile",
      "description": "Access to user profile information",
      "user_attribute": "email"
    }
  ]
}

Registration Response

Upon successful registration, the endpoint returns:

{
  "client_id": "generated_client_id",
  "client_secret": "generated_client_secret",
  "client_id_issued_at": 1640995200,
  "client_secret_expires_at": 0,
  "redirect_uris": ["cursor://anysphere.cursor-retrieval/oauth/myserver/callback"],
  "scope": "read:user write:user",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic"
}

Registration Validation

The /register endpoint validates requests against your DCR configuration:

• redirect_uris: Must contain at least one valid URL and match patterns in your approved redirect URLs
• scope: Must be from your approved scopes list
• client_name: Must be provided and non-empty

If validation fails, the endpoint returns an appropriate error response with details about what needs to be corrected.

Building a Consent Flow

Inbound Apps include additional flow components to allow your end users to easily provide consent to your OAuth server.

Inbound App Flow Components

There are two components in Descope flows created specifically for Inbound Apps:

• Inbound App Logo - Displays the app's configured logo and connection arrows.
• Inbound App Scopes - Automatically shows the scopes configured for the app, ensuring users can review permissions before proceeding.

Implementing a Consent Flow

To integrate a consent screen into your flow:

1. Use a subflow to keep your authentication flow consistent.
2. After authentication, check if the user has already granted consent using thirdPartyApp.user.consented.
   • If consent is given, proceed to the next step.
   • If not, display the consent screen.

3. Use the Update User Consent action to save the user's response. Here you can also pass in the amount of time that the user's consent is valid for, by either specifying a number or a dynamic value that you ask the user to provide in the consent screen.

4. If the user denies consent, prompt them to review or return.
5. Customize the flow as needed for your app's logic and design.

Example Consent Flow

This setup ensures a smooth user experience while enforcing consent-based access control.

Managing User Consent

The Consent tab provides visibility into which users have authorized the inbound app and what permissions they granted.

• Consent ID: A unique identifier for the user's consent.
• Scopes: The granted permissions.
• Associated User: The ID of the user who granted consent.
• Associated Tenant: The tenant ID, if applicable.
• Granting User: The user who authorized the app (e.g., an admin granting consent for a team).
• Expiration Time: The time that the user's consent expires.
• Creation Time: Timestamp when consent was given.

Next Steps

Once your Inbound App is configured, integrate it into your external applications by using Descope's OAuth authentication flows.

• Using Inbound Apps - Learn how to authenticate users with Descope as an IdP.
• Developing APIs to Support OAuth Scopes & Permissions - Secure your APIs with OAuth and manage user consent.