Custom client app registration for Agent 365 CLI

The Agent 365 CLI needs a custom client app registration in your Microsoft Entra ID tenant to authenticate and manage Agent Identity Blueprints.

This article breaks down the process into four main steps:

1. Register application
2. Set the Redirect URI
3. Copy Application (client) ID
4. Configure API permissions

If you have problems, see the Troubleshooting section.

Prerequisites

Before you begin, make sure you have access to Microsoft Entra admin center and, if needed, one of the required admin roles to grant consent.

To register the app

By default, any user in the tenant can register applications in the Microsoft Entra admin center. However, tenant administrators can restrict this capability. If you can't register your app, contact your administrator.

To add permissions and grant consent

You need one of these admin roles for 4. Configure API permissions.

• Application Administrator: Recommended - can manage app registrations and grant consent
• Cloud Application Administrator: Can manage app registrations and grant consent
• Global Administrator: Has all permissions, but not required

1. Register application

These instructions summarize the full instructions to create an app registration.

1. Go to Microsoft Entra admin center

2. Select App registrations

3. Select New registration

4. Enter:

   • Name: Enter a meaningful name for your app, such as my-agent-app. App users see this name, and you can change it at any time. You can have multiple app registrations with the same name.
   • Supported account types: Accounts in this organizational directory only (Single tenant)
   • Redirect URI: Select Public client/native (mobile & desktop) and enter http://localhost:8400/

5. Select Register

The CLI requires three redirect URIs in total. The CLI automatically adds any that are missing when you run a365 config init or a365 setup requirements:

See What the CLI auto-configures for details.

2. Set the redirect URI

1. Go to Overview and copy the Application (client) ID value.
2. Go to Authentication (preview) and select Add Redirect URI.
3. Select Mobile and desktop applications and set the value to ms-appx-web://Microsoft.AAD.BrokerPlugin/{client-id}, where {client-id} is the Application (client ID) value you copied.
4. Select Configure to add the value.

3. Copy Application (client) ID

From the app's Overview page, copy the Application (client) ID in GUID format. Enter this value when you use the a365 config init command.

4. Configure API permissions

1. In your app registration, go to API permissions.

2. Select Add a permission > Microsoft Graph > Delegated permissions.

   Important

   You must use Delegated permissions (not Application permissions). The CLI authenticates interactively - you sign in, and it acts on your behalf. To learn more, see Wrong permission type.

3. Add these six permissions one by one:

   Permission	Purpose
   AgentIdentityBlueprint.ReadWrite.All	Manage Agent Blueprint configurations
   AgentIdentityBlueprint.UpdateAuthProperties.All	Update Agent Blueprint inheritable permissions
   Application.ReadWrite.All	Create and manage applications and Agent Blueprints
   DelegatedPermissionGrant.ReadWrite.All	Grant permissions for agent blueprints
   Directory.Read.All	Read directory data for validation
   User.ReadWrite.All	Create agent users, set usage location, and assign licenses

   For each permission:

   • In the search box, type the permission name (for example, AgentIdentityBlueprint.ReadWrite.All).
   • Check the checkbox next to the permission.
   • Select Add permissions.
   • Repeat for all six permissions.

4. Select Grant admin consent for [Your Tenant].

   • Why is this required? Agent Identity Blueprints are tenant-wide resources that multiple users and applications can reference. Without tenant-wide consent, the CLI fails during authentication.
   • What if it fails? You need Application Administrator, Cloud Application Administrator, or Global Administrator role. Ask your tenant admin for help.

5. Verify all permissions show green checkmarks under Status.

Security best practices

Review these guidelines to keep your app registration secure and compliant.

Do:

• Use single-tenant registration.
• Grant only the required delegated permissions.
• Audit permissions regularly.
• Remove the app when no longer needed.

Don't:

• Grant application permissions. Only use delegated.
• Share the client ID publicly.
• Grant other unnecessary permissions.
• Use the app for other purposes.

What the CLI auto-configures

When you run a365 config init or a365 setup requirements, the CLI validates your app registration and might need to make changes. Before applying any changes, the CLI shows you a summary and asks for confirmation:

WARNING: The CLI needs to make the following changes to your app registration (<app-id>):

  - Add redirect URI(s): http://localhost
  - Enable 'Allow public client flows' (isFallbackPublicClient = true)

Do you want to proceed? (y/N):

To skip the confirmation prompt (for example, in a CI environment), use the --yes flag:

a365 config init --yes

The following table describes each change the CLI might make:

If you decline the prompt, the CLI doesn't modify your app registration. If changes are required for the CLI to function, you can configure them manually in Microsoft Entra admin center or re-run with --yes.

Next steps

After registering your custom client app, use it with the Agent 365 CLI in the Agent 365 development lifecycle:

Troubleshooting

This section describes how to troubleshoot errors with custom client app registration.

CLI validation fails during configuration

Symptom: Running a365 config init command or a365 setup fails with validation errors about your custom client app.

Solution: Use this checklist to verify your app registration is correct:

# Run configuration to see validation messages
a365 config init

Expected result: CLI displays Custom client app validation successful.

If you don't get the expected result, verify each of the following checks:

Required Delegated permissions:

• Application.ReadWrite.All
• AgentIdentityBlueprint.ReadWrite.All
• AgentIdentityBlueprint.UpdateAuthProperties.All
• Directory.Read.All
• DelegatedPermissionGrant.ReadWrite.All
• User.ReadWrite.All

Admin consent granted incorrectly

Symptom: Validation fails even though you added permissions.

Root cause: You didn't grant admin consent, or you granted it incorrectly.

Solution: In your app registration in Microsoft Entra admin center, go to API permissions and select Grant admin consent for [Your Tenant]. Verify all permissions show green checkmarks under Status.

Wrong permission type

Symptom: CLI fails with authentication errors or permission denied errors.

Root cause: You added Application permissions instead of Delegated permissions.

This table describes the different types of permissions.

Why Delegated?

• You sign in interactively (browser authentication)
• CLI performs actions as you (audit trails show your identity)
• More secure - limited by your actual permissions
• Ensures accountability and compliance

Solution:

1. Go to Microsoft Entra admin center > App registrations > Your app > API permissions
2. Remove any application permissions. These permissions appear as Application in the Type column.
3. Add the same permissions as Delegated permissions.
4. Grant admin consent again.

App not found during validation

Symptom: CLI reports Application not found or Invalid client ID errors.

Solution:

1. Verify you copied the Application (client) ID in GUID format, not the Object ID:

   • Go to Microsoft Entra admin center > App registrations > Your app > Overview
   • Copy the value under Application (client) ID
   • Format should be: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. Verify the app exists in your tenant:

   # Sign in to the correct tenant
   az login
   
   # List your app registrations
   az ad app list --display-name "<The display name of your app>"
   

Learn how to register an application in Microsoft Entra ID.