Creating Inbound Apps

To configure an Inbound App in Descope, follow these steps:

1. Navigate to the Inbound Apps section in 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.

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.

• Name (Required): The identifier for the permission scope.
• Description (Required): A summary of the permission.
• Roles (Optional): Assign roles if RBAC is enabled.

User Information Scopes

These scopes define what user data is shared with the third-party application. You can include built-in Descope attributes or custom attributes.

• Name (Required): The identifier for the user data scope.
• Description (Required): A summary of the data being shared.
• User Attribute (Required): The specific user attribute mapped to this scope. This utilizes Descope's role-based authorization (RBAC) model to control access.

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 CNAME
  • 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).

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 new components in Descope flows 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.
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).
• 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.