Microsoft identity platform developer glossary
This article contains definitions for some of the core developer concepts and terminology, which are helpful when learning about application development using Microsoft identity platform.
A type of security token issued by an authorization server, and used by a client application in order to access a protected resource server. Typically in the form of a JSON Web Token (JWT), the token embodies the authorization granted to the client by the resource owner, for a requested level of access. The token contains all applicable claims about the subject, enabling the client application to use it as a form of credential when accessing a given resource. This also eliminates the need for the resource owner to expose credentials to the client.
Access tokens are only valid for a short period of time and cannot be revoked. An authorization server may also issue a refresh token when the access token is issued. Refresh tokens are typically provided only to confidential client applications.
Access tokens are sometimes referred to as "User+App" or "App-Only", depending on the credentials being represented. For example, when a client application uses the:
- "Authorization code" authorization grant, the end user authenticates first as the resource owner, delegating authorization to the client to access the resource. The client authenticates afterward when obtaining the access token. The token can sometimes be referred to more specifically as a "User+App" token, as it represents both the user that authorized the client application, and the application.
- "Client credentials" authorization grant, the client provides the sole authentication, functioning without the resource-owner's authentication/authorization, so the token can sometimes be referred to as an "App-Only" token.
See Microsoft identity platform Token Reference for more details.
application ID (client ID)
The unique identifier Azure AD issues to an application registration that identifies a specific application and the associated configurations. This application ID (client ID) is used when performing authentication requests and is provided to the authentication libraries in development time. The application ID (client ID) is not a secret.
A feature provided by the Azure portal, which produces a JSON representation of the application's identity configuration, used as a mechanism for updating its associated Application and ServicePrincipal entities. See Understanding the Azure Active Directory application manifest for more details.
When you register/update an application in the Azure portal, the portal creates/updates both an application object and a corresponding service principal object for that tenant. The application object defines the application's identity configuration globally (across all tenants where it has access), providing a template from which its corresponding service principal object(s) are derived for use locally at run-time (in a specific tenant).
For more information, see Application and Service Principal Objects.
In order to allow an application to integrate with and delegate Identity and Access Management functions to Azure AD, it must be registered with an Azure AD tenant. When you register your application with Azure AD, you are providing an identity configuration for your application, allowing it to integrate with Azure AD and use features such as:
- Robust management of Single Sign-On using Azure AD Identity Management and OpenID Connect protocol implementation
- Brokered access to protected resources by client applications, via OAuth 2.0 authorization server
- Consent framework for managing client access to protected resources, based on resource owner authorization.
See Integrating applications with Azure Active Directory for more details.
The act of challenging a party for legitimate credentials, providing the basis for creation of a security principal to be used for identity and access control. During an OAuth2 authorization grant for example, the party authenticating is filling the role of either resource owner or client application, depending on the grant used.
The act of granting an authenticated security principal permission to do something. There are two primary use cases in the Azure AD programming model:
- During an OAuth2 authorization grant flow: when the resource owner grants authorization to the client application, allowing the client to access the resource owner's resources.
- During resource access by the client: as implemented by the resource server, using the claim values present in the access token to make access control decisions based upon them.
A short lived "token" provided to a client application by the authorization endpoint, as part of the "authorization code" flow, one of the four OAuth2 authorization grants. The code is returned to the client application in response to authentication of a resource owner, indicating the resource owner has delegated authorization to access the requested resources. As part of the flow, the code is later redeemed for an access token.
One of the endpoints implemented by the authorization server, used to interact with the resource owner in order to provide an authorization grant during an OAuth2 authorization grant flow. Depending on the authorization grant flow used, the actual grant provided can vary, including an authorization code or security token.
A credential representing the resource owner's authorization to access its protected resources, granted to a client application. A client application can use one of the four grant types defined by the OAuth2 Authorization Framework to obtain a grant, depending on client type/requirements: "authorization code grant", "client credentials grant", "implicit grant", and "resource owner password credentials grant". The credential returned to the client is either an access token, or an authorization code (exchanged later for an access token), depending on the type of authorization grant used.
As defined by the OAuth2 Authorization Framework, the server responsible for issuing access tokens to the client after successfully authenticating the resource owner and obtaining its authorization. A client application interacts with the authorization server at runtime via its authorization and token endpoints, in accordance with the OAuth2 defined authorization grants.
In the case of Microsoft identity platform application integration, Microsoft identity platform implements the authorization server role for Azure AD applications and Microsoft service APIs, for example Microsoft Graph APIs.
A security token contains claims, which provide assertions about one entity (such as a client application or resource owner) to another entity (such as the resource server). Claims are name/value pairs that relay facts about the token subject (for example, the security principal that was authenticated by the authorization server). The claims present in a given token are dependent upon several variables, including the type of token, the type of credential used to authenticate the subject, the application configuration, etc.
See Microsoft identity platform token reference for more details.
As defined by the OAuth2 Authorization Framework, an application that makes protected resource requests on behalf of the resource owner. The term "client" does not imply any particular hardware implementation characteristics (for instance, whether the application executes on a server, a desktop, or other devices).
A client application requests authorization from a resource owner to participate in an OAuth2 authorization grant flow, and may access APIs/data on the resource owner's behalf. The OAuth2 Authorization Framework defines two types of clients, "confidential" and "public", based on the client's ability to maintain the confidentiality of its credentials. Applications can implement a web client (confidential) which runs on a web server, a native client (public) installed on a device, or a user-agent-based client (public) which runs in a device's browser.
The process of a resource owner granting authorization to a client application, to access protected resources under specific permissions, on behalf of the resource owner. Depending on the permissions requested by the client, an administrator or user will be asked for consent to allow access to their organization/individual data respectively. Note, in a multi-tenant scenario, the application's service principal is also recorded in the tenant of the consenting user.
See consent framework for more information.
An OpenID Connect security token provided by an authorization server's authorization endpoint, which contains claims pertaining to the authentication of an end user resource owner. Like an access token, ID tokens are also represented as a digitally signed JSON Web Token (JWT). Unlike an access token though, an ID token's claims are not used for purposes related to resource access and specifically access control.
See Microsoft identity platform token reference for more details.
Microsoft identity platform
Microsoft identity platform is an evolution of the Azure Active Directory (Azure AD) identity service and developer platform. It allows developers to build applications that sign in all Microsoft identities, get tokens to call Microsoft Graph, other Microsoft APIs, or APIs that developers have built. It’s a full-featured platform that consists of an authentication service, libraries, application registration and configuration, full developer documentation, code samples, and other developer content. The Microsoft identity platform supports industry standard protocols such as OAuth 2.0 and OpenID Connect.
A class of application that enables sign in and consent by users provisioned in any Azure AD tenant, including tenants other than the one where the client is registered. Native client applications are multi-tenant by default, whereas web client and web resource/API applications have the ability to select between single or multi-tenant. By contrast, a web application registered as single-tenant, would only allow sign-ins from user accounts provisioned in the same tenant as the one where the application is registered.
See How to sign in any Azure AD user using the multi-tenant application pattern for more details.
A type of client application that is installed natively on a device. Since all code is executed on a device, it is considered a "public" client due to its inability to store credentials privately/confidentially. See OAuth2 client types and profiles for more details.
- "Delegated" permissions, which specify scope-based access using delegated authorization from the signed-in resource owner, are presented to the resource at run-time as "scp" claims in the client's access token.
- "Application" permissions, which specify role-based access using the client application's credentials/identity, are presented to the resource at run-time as "roles" claims in the client's access token.
They also surface during the consent process, giving the administrator or resource owner the opportunity to grant/deny the client access to resources in their tenant.
Permission requests are configured on the API permissions page for an application in the Azure portal, by selecting the desired "Delegated Permissions" and "Application Permissions" (the latter requires membership in the Global Admin role). Because a public client can't securely maintain credentials, it can only request delegated permissions, while a confidential client has the ability to request both delegated and application permissions. The client's application object stores the declared permissions in its requiredResourceAccess property.
A type of security token issued by an authorization server, and used by a client application in order to request a new access token before the access token expires. Typically in the form of a JSON Web Token (JWT).
Unlike access tokens, refresh tokens can be revoked. If a client application attempts to request a new access token using a refresh token that has been revoked, the authorization server will deny the request, and the client application will no longer have permission to access the resource server on behalf of the resource owner.
As defined by the OAuth2 Authorization Framework, an entity capable of granting access to a protected resource. When the resource owner is a person, it is referred to as an end user. For example, when a client application wants to access a user's mailbox through the Microsoft Graph API, it requires permission from the resource owner of the mailbox.
As defined by the OAuth2 Authorization Framework, a server that hosts protected resources, capable of accepting and responding to protected resource requests by client applications that present an access token. Also known as a protected resource server, or resource application.
A resource server exposes APIs and enforces access to its protected resources through scopes and roles, using the OAuth 2.0 Authorization Framework. Examples include the Microsoft Graph API which provides access to Azure AD tenant data, and the Office 365 APIs that provide access to data such as mail and calendar.
Just like a client application, resource application's identity configuration is established via registration in an Azure AD tenant, providing both the application and service principal object. Some Microsoft-provided APIs, such as the Microsoft Graph API, have pre-registered service principals made available in all tenants during provisioning.
Like scopes, roles provide a way for a resource server to govern access to its protected resources. There are two types: a "user" role implements role-based access control for users/groups that require access to the resource, while an "application" role implements the same for client applications that require access.
Roles are resource-defined strings (for example "Expense approver", "Read-only", "Directory.ReadWrite.All"), managed in the Azure portal via the resource's application manifest, and stored in the resource's appRoles property. The Azure portal is also used to assign users to "user" roles, and configure client application permissions to access an "application" role.
For a detailed discussion of the application roles exposed by the Microsoft Graph API, see Graph API Permission Scopes. For a step-by-step implementation example, see Manage access using RBAC and the Azure portal.
Like roles, scopes provide a way for a resource server to govern access to its protected resources. Scopes are used to implement scope-based access control, for a client application that has been given delegated access to the resource by its owner.
Scopes are resource-defined strings (for example "Mail.Read", "Directory.ReadWrite.All"), managed in the Azure portal via the resource's application manifest, and stored in the resource's oauth2Permissions property. The Azure portal is also used to configure client application delegated permissions to access a scope.
A best practice naming convention, is to use a "resource.operation.constraint" format. For a detailed discussion of the scopes exposed by Microsoft Graph API, see Graph API Permission Scopes. For scopes exposed by Office 365 services, see Office 365 API permissions reference.
A signed document containing claims, such as an OAuth2 token or SAML 2.0 assertion. For an OAuth2 authorization grant, an access token (OAuth2), refresh token, and an ID Token are types of security tokens, all of which are implemented as a JSON Web Token (JWT).
service principal object
When you register/update an application in the Azure portal, the portal creates/updates both an application object and a corresponding service principal object for that tenant. The application object defines the application's identity configuration globally (across all tenants where the associated application has been granted access), and is the template from which its corresponding service principal object(s) are derived for use locally at run-time (in a specific tenant).
For more information, see Application and Service Principal Objects.
The process of a client application initiating end-user authentication and capturing related state, for the purpose of acquiring a security token and scoping the application session to that state. State can include artifacts such as user profile information, and information derived from token claims.
The sign-in function of an application is typically used to implement single-sign-on (SSO). It may also be preceded by a "sign-up" function, as the entry point for an end user to gain access to an application (upon first sign-in). The sign-up function is used to gather and persist additional state specific to the user, and may require user consent.
An instance of an Azure AD directory is referred to as an Azure AD tenant. It provides several features, including:
- a registry service for integrated applications
- authentication of user accounts and registered applications
- REST endpoints required to support various protocols including OAuth2 and SAML, including the authorization endpoint, token endpoint and the "common" endpoint used by multi-tenant applications.
Azure AD tenants are created/associated with Azure and Office 365 subscriptions during sign-up, providing Identity & Access Management features for the subscription. Azure subscription administrators can also create additional Azure AD tenants via the Azure portal. See How to get an Azure Active Directory tenant for details on the various ways you can get access to a tenant. See Associate or add an Azure subscription to your Azure Active Directory tenant for details on the relationship between subscriptions and an Azure AD tenant, and for instructions on how to associate or add a subscription to an Azure AD tenant.
One of the endpoints implemented by the authorization server to support OAuth2 authorization grants. Depending on the grant, it can be used to acquire an access token (and related "refresh" token) to a client, or ID token when used with the OpenID Connect protocol.
A type of client application that downloads code from a web server and executes within a user-agent (for instance, a web browser), such as a single-page application (SPA). Since all code is executed on a device, it is considered a "public" client due to its inability to store credentials privately/confidentially. For more information, see OAuth2 client types and profiles.
Similar to the way a service principal object is used to represent an application instance, a user principal object is another type of security principal, which represents a user. The Microsoft Graph User resource type defines the schema for a user object, including user-related properties such as first and last name, user principal name, directory role membership, etc. This provides the user identity configuration for Azure AD to establish a user principal at run-time. The user principal is used to represent an authenticated user for Single Sign-On, recording consent delegation, making access control decisions, etc.
A type of client application that executes all code on a web server, and able to function as a "confidential" client by securely storing its credentials on the server. For more information, see OAuth2 client types and profiles.
The Microsoft identity platform Developer's Guide is the landing page to use for all Microsoft identity platform development-related topics, including an overview of application integration and the basics of Microsoft identity platform authentication and supported authentication scenarios. You can also find code samples & tutorials on how to get up and running quickly on GitHub.
Use the following comments section to provide feedback and help to refine and shape this content, including requests for new definitions or updating existing ones!