Register an app in your external tenant

Applies to: White circle with a gray X symbol. Workforce tenants Green circle with a white check mark symbol. External tenants (learn more)

Microsoft Entra External ID enables your organization to manage customers’ identities, and securely control access to your public facing applications and APIs. Applications where your customers can buy your products, subscribe to your services, or access their account and data. Your customers only need to sign in on a device or a web browser once and have access to all your applications you granted them permissions.

To enable your application to sign in with External ID, you need to register your app with External ID. The app registration establishes a trust relationship between the app and External ID. During app registration, you specify the redirect URI. The redirect URI is the endpoint to which users are redirected by External ID after they authenticate. The app registration process generates an application ID, also known as the client ID, that uniquely identifies your app.

External ID supports authentication for various modern application architectures, for example web app or single-page app. The interaction of each application type with the external tenant is different, therefore, you must specify the type of application you want to register.

In this article, you learn how to register an application in your external tenant.

Prerequisites

Choose your app type

Register your Single-page app

External ID supports authentication for Single-page apps (SPAs).

The following steps show you how to register your SPA in the Microsoft Entra admin center:

  1. Sign in to the Microsoft Entra admin center as at least an Application Developer.

  2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to your external tenant from the Directories + subscriptions menu.

  3. Browse to Identity > Applications > App registrations.

  4. Select + New registration.

  5. In the Register an application page that appears, enter your application's registration information:

    1. In the Name section, enter a meaningful application name that is displayed to users of the app, for example ciam-client-app.

    2. Under Supported account types, select Accounts in this organizational directory only.

    3. Under Redirect URI (optional), select Single-page application (SPA) and then, in the URL box, enter http://localhost:3000/.

  6. Select Register.

  7. The application's Overview pane is displayed when registration is complete. Record the Directory (tenant) ID and the Application (client) ID to be used in your application source code.

About redirect URI

The redirect URI is the endpoint where the user is sent to by the authorization server (in this case, Microsoft Entra ID) after completing its interaction with the user, and to which an access token or authorization code is sent to upon successful authorization.

In a production application, it's typically a publicly accessible endpoint where your app is running, like https://contoso.com/auth-response.

During app development, you might add the endpoint where your application listens locally, like http://localhost:3000. You can add and modify redirect URIs in your registered applications at any time.

The following restrictions apply to redirect URIs:

  • The reply URL must begin with the scheme https, unless you use a localhost redirect URL.

  • The reply URL is case-sensitive. Its case must match the case of the URL path of your running application. For example, if your application includes as part of its path .../abc/response-oidc, do not specify .../ABC/response-oidc in the reply URL. Because the web browser treats paths as case-sensitive, cookies associated with .../abc/response-oidc may be excluded if redirected to the case-mismatched .../ABC/response-oidc URL.

  • The reply URL should include or exclude the trailing forward slash as your application expects it. For example, https://contoso.com/auth-response and https://contoso.com/auth-response/ might be treated as non-matching URLs in your application.

Once you register your application, it gets assigned the User.Read permission. However, since the tenant is an external tenant, the customer users themselves can't consent to this permission. You as the admin must consent to this permission on behalf of all the users in the tenant:

  1. From the App registrations page, select the application that you created (such as ciam-client-app) to open its Overview page.

  2. Under Manage, select API permissions.

    1. Select Grant admin consent for <your tenant name>, then select Yes.
    2. Select Refresh, then verify that Granted for <your tenant name> appears under Status for the permission.

Grant API permissions (optional):

If your SPA needs to call an API, you must grant your SPA API permissions so it can call the API. You must also register the web API that you need to call.

To grant your client app (ciam-client-app) API permissions, follow these steps:

  1. From the App registrations page, select the application that you created (such as ciam-client-app) to open its Overview page.

  2. Under Manage, select API permissions.

  3. Under Configured permissions, select Add a permission.

  4. Select the APIs my organization uses tab.

  5. In the list of APIs, select the API such as ciam-ToDoList-api.

  6. Select Delegated permissions option.

  7. From the permissions list, select ToDoList.Read, ToDoList.ReadWrite (use the search box if necessary).

  8. Select the Add permissions button. At this point, you've assigned the permissions correctly. However, since the tenant is a customer's tenant, the consumer users themselves can't consent to these permissions. To address this problem, you as the admin must consent to these permissions on behalf of all the users in the tenant:

    1. Select Grant admin consent for <your tenant name>, then select Yes.

    2. Select Refresh, then verify that Granted for <your tenant name> appears under Status for both scopes.

  9. From the Configured permissions list, select the ToDoList.Read and ToDoList.ReadWrite permissions, one at a time, and then copy the permission's full URI for later use. The full permission URI looks something similar to api://{clientId}/{ToDoList.Read} or api://{clientId}/{ToDoList.ReadWrite}.

If you'd like to learn how to expose the permissions by adding a link, go to the Web API section.

Test the user flow (optional)

To test a user flow with this app registration, enable the implicit grant flow for authentication.

Important

The implicit flow should be used only for testing purposes and not for authenticating users in your production apps. Once you have finished testing, we recommend removing it.

To enable the implicit flow, follow these steps:

  1. Sign in to the Microsoft Entra admin center as at least an Application Developer.
  2. If you have access to multiple tenants, use the Settings icon in the top menu to switch to your external tenant from the Directories + subscriptions menu.
  3. Browse to Identity >Applications > App registrations.
  4. Select the app registration you created.
  5. Under Manage, select Authentication.
  6. Under Implicit grant and hybrid flows, select the ID tokens (used for implicit and hybrid flows) checkbox.
  7. Select Save.

Find the Application (client) ID

After you register a new application, you can find the Application (client) ID from the overview in the Microsoft Entra admin center.

  1. From the App registrations page, select the All applications or the Owned applications tab.

  2. Select the application to open its Overview page.

  3. Under Essentials you find all the app details including the Application (client) ID.

    Screenshot showing the application (client) ID.

Next steps