You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
#Customer intent: As developer, I want to know how to register my application with the Microsoft identity platform so that the security token service can issue ID and/or access tokens to client applications that request them.
15
16
---
16
17
17
18
# Quickstart: Register an application with the Microsoft identity platform
18
19
19
-
Get started with the Microsoft identity platform by registering an application in the Azure portal.
20
-
21
-
The Microsoft identity platform performs identity and access management (IAM) only for registered applications. Whether it's a client application like a web or mobile app, or it's a web API that backs a client app, registering it establishes a trust relationship between your application and the identity provider, the Microsoft identity platform.
22
-
23
-
> [!TIP]
24
-
> To register an application for Azure AD B2C, follow the steps in [Tutorial: Register a web application in Azure AD B2C](../../active-directory-b2c/tutorial-register-applications.md).
25
-
26
-
## Prerequisites
27
-
28
-
- An Azure account that has an active subscription. [Create an account for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
29
-
- The Azure account must have permission to manage applications in Azure Active Directory (Azure AD). Any of the following Azure AD roles include the required permissions:
- Completion of the [Set up a tenant](quickstart-create-new-tenant.md) quickstart.
34
-
35
-
## Register an application
36
-
37
-
Registering your application establishes a trust relationship between your app and the Microsoft identity platform. The trust is unidirectional: your app trusts the Microsoft identity platform, and not the other way around.
38
-
39
-
Follow these steps to create the app registration:
40
-
41
-
1. Sign in to the <ahref="https://portal.azure.com/"target="_blank">Azure portal</a>.
42
-
1. If you have access to multiple tenants, use the **Directories + subscriptions** filter :::image type="icon" source="./media/common/portal-directory-subscription-filter.png" border="false"::: in the top menu to switch to the tenant in which you want to register the application.
43
-
1. Search for and select **Azure Active Directory**.
44
-
1. Under **Manage**, select **App registrations** > **New registration**.
45
-
1. Enter a display **Name** for your application. Users of your application might see the display name when they use the app, for example during sign-in.
46
-
You can change the display name at any time and multiple app registrations can share the same name. The app registration's automatically generated Application (client) ID, not its display name, uniquely identifies your app within the identity platform.
47
-
1. Specify who can use the application, sometimes called its _sign-in audience_.
|**Accounts in this organizational directory only**| Select this option if you're building an application for use only by users (or guests) in _your_ tenant.<br><br>Often called a _line-of-business_ (LOB) application, this app is a _single-tenant_ application in the Microsoft identity platform. |
52
-
|**Accounts in any organizational directory**| Select this option if you want users in _any_ Azure Active Directory (Azure AD) tenant to be able to use your application. This option is appropriate if, for example, you're building a software-as-a-service (SaaS) application that you intend to provide to multiple organizations.<br><br>This type of app is known as a _multitenant_ application in the Microsoft identity platform. |
53
-
|**Accounts in any organizational directory and personal Microsoft accounts**| Select this option to target the widest set of customers.<br><br>By selecting this option, you're registering a _multitenant_ application that can also support users who have personal _Microsoft accounts_. |
54
-
|**Personal Microsoft accounts**| Select this option if you're building an application only for users who have personal Microsoft accounts. Personal Microsoft accounts include Skype, Xbox, Live, and Hotmail accounts. |
55
-
56
-
1. Don't enter anything for **Redirect URI (optional)**. You'll configure a redirect URI in the next section.
57
-
1. Select **Register** to complete the initial app registration.
58
-
59
-
:::image type="content" source="media/quickstart-register-app/portal-02-app-reg-01.png" alt-text="Screenshot of the Azure portal in a web browser, showing the Register an application pane.":::
60
-
61
-
When registration finishes, the Azure portal displays the app registration's **Overview** pane. You see the **Application (client) ID**. Also called the _client ID_, this value uniquely identifies your application in the Microsoft identity platform.
62
-
63
-
> [!IMPORTANT]
64
-
> New app registrations are hidden to users by default. When you are ready for users to see the app on their [My Apps page](https://support.microsoft.com/account-billing/sign-in-and-start-apps-from-the-my-apps-portal-2f3b1bae-0e5a-4a86-a33e-876fbd2a4510) you can enable it. To enable the app, in the Azure portal navigate to **Azure Active Directory** > **Enterprise applications** and select the app. Then on the **Properties** page toggle **Visible to users?** to Yes.
65
-
66
-
Your application's code, or more typically an authentication library used in your application, also uses the client ID. The ID is used as part of validating the security tokens it receives from the identity platform.
67
-
68
-
:::image type="content" source="media/quickstart-register-app/portal-03-app-reg-02.png" alt-text="Screenshot of the Azure portal in a web browser, showing an app registration's Overview pane.":::
69
-
70
-
## Add a redirect URI
71
-
72
-
A _redirect URI_ is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication.
73
-
74
-
In a production web application, for example, the redirect URI is often a public endpoint where your app is running, like `https://contoso.com/auth-response`. During development, it's common to also add the endpoint where you run your app locally, like `https://127.0.0.1/auth-response` or `http://localhost/auth-response`.
75
-
76
-
You add and modify redirect URIs for your registered applications by configuring their [platform settings](#configure-platform-settings).
77
-
78
-
### Configure platform settings
79
-
80
-
Settings for each application type, including redirect URIs, are configured in **Platform configurations** in the Azure portal. Some platforms, like **Web** and **Single-page applications**, require you to manually specify a redirect URI. For other platforms, like mobile and desktop, you can select from redirect URIs generated for you when you configure their other settings.
81
-
82
-
To configure application settings based on the platform or device you're targeting, follow these steps:
83
-
84
-
1. In the Azure portal, in **App registrations**, select your application.
85
-
1. Under **Manage**, select **Authentication**.
86
-
1. Under **Platform configurations**, select **Add a platform**.
87
-
1. Under **Configure platforms**, select the tile for your application type (platform) to configure its settings.
88
-
89
-
:::image type="content" source="media/quickstart-register-app/portal-04-app-reg-03-platform-config.png" alt-text="Screenshot of the platform configuration pane in the Azure portal." border="false":::
|**Web**| Enter a **Redirect URI** for your app. This URI is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication.<br/><br/>Select this platform for standard web applications that run on a server. |
94
-
|**Single-page application**| Enter a **Redirect URI** for your app. This URI is the location where the Microsoft identity platform redirects a user's client and sends security tokens after authentication.<br/><br/>Select this platform if you're building a client-side web app by using JavaScript or a framework like Angular, Vue.js, React.js, or Blazor WebAssembly. |
95
-
|**iOS / macOS**| Enter the app **Bundle ID**. Find it in **Build Settings** or in Xcode in _Info.plist_.<br/><br/>A redirect URI is generated for you when you specify a **Bundle ID**. |
96
-
|**Android**| Enter the app **Package name**. Find it in the _AndroidManifest.xml_ file. Also generate and enter the **Signature hash**.<br/><br/>A redirect URI is generated for you when you specify these settings. |
97
-
|**Mobile and desktop applications**| Select one of the **Suggested redirect URIs**. Or specify a **Custom redirect URI**.<br/><br/>For desktop applications using embedded browser, we recommend<br/>`https://login.microsoftonline.com/common/oauth2/nativeclient`<br/><br/>For desktop applications using system browser, we recommend<br/>`http://localhost`<br/><br/>Select this platform for mobile applications that aren't using the latest Microsoft Authentication Library (MSAL) or aren't using a broker. Also select this platform for desktop applications. |
98
-
99
-
1. Select **Configure** to complete the platform configuration.
100
-
101
-
### Redirect URI restrictions
102
-
103
-
There are some restrictions on the format of the redirect URIs you add to an app registration. For details about these restrictions, see [Redirect URI (reply URL) restrictions and limitations](reply-url.md).
104
-
105
-
## Add credentials
106
-
107
-
Credentials are used by [confidential client applications](msal-client-applications.md) that access a web API. Examples of confidential clients are web apps, other web APIs, or service-type and daemon-type applications. Credentials allow your application to authenticate as itself, requiring no interaction from a user at runtime.
108
-
109
-
You can add both certificates and client secrets (a string) as credentials to your confidential client app registration.
110
-
111
-
:::image type="content" source="media/quickstart-register-app/portal-05-app-reg-04-credentials.png" alt-text="Screenshot of the Azure portal, showing the Certificates and secrets pane in an app registration.":::
112
-
113
-
### Add a certificate
114
-
115
-
Sometimes called a _public key_, a certificate is the recommended credential type because they're considered more secure than client secrets. For more information about using a certificate as an authentication method in your application, see [Microsoft identity platform application authentication certificate credentials](active-directory-certificate-credentials.md).
116
-
117
-
1. In the Azure portal, in **App registrations**, select your application.
1. Select the file you want to upload. It must be one of the following file types: _.cer_, _.pem_, _.crt_.
120
-
1. Select **Add**.
121
-
122
-
### Add a client secret
123
-
124
-
Sometimes called an _application password_, a client secret is a string value your app can use in place of a certificate to identity itself.
125
-
126
-
Client secrets are considered less secure than certificate credentials. Application developers sometimes use client secrets during local app development because of their ease of use. However, you should use certificate credentials for any of your applications that are running in production.
127
-
128
-
1. In the Azure portal, in **App registrations**, select your application.
1. Select an expiration for the secret or specify a custom lifetime.
132
-
- Client secret lifetime is limited to two years (24 months) or less. You can't specify a custom lifetime longer than 24 months.
133
-
- Microsoft recommends that you set an expiration value of less than 12 months.
134
-
1. Select **Add**.
135
-
1._Record the secret's value_ for use in your client application code. This secret value is _never displayed again_ after you leave this page.
136
-
137
-
For application security recommendations, see [Microsoft identity platform best practices and recommendations](identity-platform-integration-checklist.md#security).
138
-
139
-
140
-
### Add a federated credential
141
-
142
-
Federated identity credentials are a type of credential that allows workloads, such as GitHub Actions, workloads running on Kubernetes, or workloads running in compute platforms outside of Azure access Azure AD protected resources without needing to manage secrets using [workload identity federation](workload-identity-federation.md).
143
-
144
-
To add a federated credential, follow these steps:
145
-
146
-
1. In the Azure portal, in **App registrations**, select your application.
1. In the **Federated credential scenario** drop-down box, select one of the supported scenarios, and follow the corresponding guidance to complete the configuration.
149
-
150
-
-**Customer managed keys** for encrypt data in your tenant using Azure Key Vault in another tenant.
151
-
-**GitHub actions deploying Azure resources** to [configure a GitHub workflow](workload-identity-federation-create-trust.md#github-actions) to get tokens for your application and deploy assets to Azure.
152
-
-**Kubernetes accessing Azure resources** to configure a [Kubernetes service account](workload-identity-federation-create-trust.md#kubernetes) to get tokens for your application and access Azure resources.
153
-
-**Other issuer** to configure an identity managed by an external [OpenID Connect provider](workload-identity-federation-create-trust.md#other-identity-providers) to get tokens for your application and access Azure resources.
154
-
155
-
156
-
For more information, how to get an access token with a federated credential, check out the [Microsoft identity platform and the OAuth 2.0 client credentials flow](v2-oauth2-client-creds-grant-flow.md#third-case-access-token-request-with-a-federated-credential) article.
0 commit comments