OAuth 2.0 and OpenId With Azure Azure Active Directory (AAD)

Overview of OAuth 2.0

The OAuth 2.0 protocol is an open standard for delegated authorization scenarios. The term delegation in here means the user lets an application access its data in it its behalf. The OAuth 2.0 protocol is widely accepted to provide capabilities to Web API to make authorization decisions, without requiring for the clients to pass the credentials to the Web API. To better explain the OAuth 2.0 protocol flow, there are a few concepts that are widely used and accepted, as explained below.

Please note the OAuth 2.0 protocol is designed for authorization purpose only and cannot be used for authentication. There is an extension of the OAuth 2.0 protocol, which merged the concepts of OpenID with OAuth to provide authentication capability. This extension is called as OpenID connect. The document focuses on the implementation of the OAuth 2.0 and OpenID connect framework for Azure Active Directory AuthN and AuthZ flows, with endpoints specific to Azure Active Directory.

Concepts

Roles

The OAuth 2.0 protocol identifies four roles or personas for the delegated access flow:

• Resource Owner: Resource owner is the user which is trying to perform an operation, on a resource. The resource is essential any data owned and generated by the owner, e.g. emails, documents, pictures etc.
• Client: The client is the application who is trying to do the operation, that the resource owner has asked it to do. The client usually has a unique client_id and a password, also known as client_secret. In Azure AAD, this is represented as the AAD Application.
• Resource Server: The resource server stores the resources; the client needs to access to perform the required operation. The client needs to access these resources on behalf of the resource owner to perform the operation.
• Authorization Server: The authorization server will store the identity information of the resource owner and issues token to be used in the flow.

To explain the roles clearly, here is a scenario:

Scenario: Alice wants to use a TODO application to create and store a list of things she needs to do on a daily basis. While doing that, she wants a calendar item created for each of them in her Outlook web calendar, so that she gets a reminder for her tasks when it is due. Here is the diagram depicting the basic authorization flow.

Application Type

oAuth 2.0 categorized the application into three major categories, and the flow differs based on these:

• Secure/Confidential Application: These are the application which runs in a secure environment. A secure environment is an executing environment, which can be considered relatively safe from outside or unknown authorized access. A very common example of these are, a website/web service hosted on a web server.
• Unsecured/Public Application: These are the application which runs in an unsecured environment, and there is a very good chance that some unauthorized person has access to these executing environments. A very common example is a JavaScript-based SPA application (ReactJs, AngularJs, AJAX etc.) running in a user’s web browser.
• Native Application: The native applications are unsecured applications that are installed and runs on the device the resource owner owns. This would be an installed application in the machines, a PowerShell script, or a mobile application.

Authorization Tokens

Tokens are packages that carry authorization decisions, that can be transmitted from one security boundary to another. The tokens contain all the required information, that can be used by the resource server to make an authorization decision. These tokens are created and secured by the Authorization Server and are transmitted over the network by all the roles in the flows. There are three types of tokens that are commonly used:

• Access Token: Access tokens are issued by the Authorization server to the client, which in turn is presented to the resource server. The resource server makes authorization decisions based on the content of the access token. Access tokens can be JWT or SAML tokens (token formats are described below).
• Refresh Token: Refresh tokens doesn’t contain any authorization related information, as a result, cannot be used to make any authorization or authentication decisions. The client uses the refresh tokens, to request a new access token, once the original access token is expired.
• ID Token: ID tokens are special types of tokens, that generally don’t take part in the basic OAuth 2.0 authorization flow. ID tokens are issued for authentication purpose, to be consumed only by the client as per the OpenID Connect standards. ID tokens are always JWT tokens.

Tokens can be presented by a client to the resource server in multiple ways, the most common way is, as Bearer token. Bearer token is access tokens, which are presented as Bearer in the Authorization header of the HTTP request by the client to the resource server to access a resource. The term “bearer token” here means, anyone who has the possession of the token can request access for a resource to the resource server. As the OAuth 2.0 framework doesn’t mandate a specific format of a token, the authorization server may be able to issue additional token types, e.g. MAC based tokens (please see oAuth 2.0 MAC token profiles).

Token Formats

There are two common token format standards:

• JWT (JSON Web Token): This is now one of the most common token format, which is lightweight, based on the JSON (JavaScript Object Notation) specification.
• SAML (Security Assertion markup language): This is the format of the token, where the token information is encoded with XML specification. This is a lot bulkier compared to JWT tokens, and are currently mostly used for backward compatibility.

Grant Type

oAuth 2.0 defined four basic authorization flows (also known as Grant types) based on the above-mentioned application types:

• Authorization Code: This flow uses an intermediate “authorization code” to request an access token by the client to access resources. The “authentication code” is a form of a token, which is very short-lived and issued for the client only. The flow is very commonly used for secure, web-server hosted browser-based applications or application which can be invoked through a browser. This flow heavily relies on the browser redirect capabilities.
• Implicit: This flow is like the authorization code flow mentioned above, but are meant to be used by JavaScript-based applications running on the resource owner machines, e.g. SPA using AngularJS, ReactJS, AJAX etc.
• Resource Owner Password Credentials: This flow is used by an application running on a device who is owned by the resource owner, and the application and the client has a special trust relation.
• Client Credentials: This flow is a non-delegated flow, used by clients to make direct calls to the resource server, without the resource owner initializing the flow. In this flow, the client behaves as a resource owner, instead of impersonation an external resource owner.

The OAuth2.0 framework can be extended to add additional grant types to handle additional scenarios. One of the most common grant types is –

• Assertions: This flow is used to handle federated authorization scenarios (i.e. which required authorization across multiple security boundaries), and scenarios where the client doesn’t want to share the client_secret over the network.

Each of these flows is explained in more details below.

Endpoints

The authorization server hosts few standard endpoints that take part in the authorization flow:

• Authorization endpoint: The authorization endpoint is used by the “authorization code” flow to obtain authorization grant. During the “implicit” flow, it can also issue access tokens. This endpoint can support both GET and POST methods. The Azure AD endpoint is – https://login.microsoftonline.com/common/oauth2/authorize or https://login.microsoftonline.com/{tenant_id}/oauth2/authorize.
• Token endpoints: This endpoints issues access token by presenting the authorization grant, resource owner credentials, client credentials or the refresh token, and usually support POST method. The Azure AD endpoint is – https://login.microsoftonline.com/common/oauth2/token or https://login.microsoftonline.com/{tenant_id}/oauth2/token.

There are usually additional endpoints supported by the authorization server, which serves the purpose for few other scenarios, such as:

• OpenId Configuration (https://login.microsoftonline.com/common/.well-known/openid-configuration)
• UserInfo endpoint (https://login.microsoftonline.com/common/openid/userinfo)
• Token Signing Keys (https://login.microsoftonline.com/common/discovery/keys)
• Introspection Endpoint (Token metadata)
• Token Revocation endpoint

Grant Types

Authorization Code

This flow is used by secure web applications hosted on private web servers. This flow can also be used by native applications (installed in the resource owner machines), in which case the native application would need to invoke an external browser or use an embedded-browser to interact with the authorization endpoint.

There are three main properties that decide the use of the flow:

• The application is secure and hosted on a private web server. Which means, the authorization code issued by the authorization server cannot be viewed by anyone, not even the resource owner. The client would request an access token based on the short-lived authorization grant.
• The flow depends on browser redirection capabilities and works best for a browser-based application.
• If the client requires a “long-term” or “offline” access to the resources, by using a refresh token to renew an access token when it expires, without going through the full flow.
• The application is a native application and can rely on an external browser or embedded browser invocation for redirection. Please note, special considerations for securing the authorization code, access token and the refresh token need to be taken.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Obtain authorization grant	GET /oauth2/authorize? HTTP/1.1 response_type=code &client_id=e7044267ae3e4c7d-b2b1b87dabe7d0a3 &redirect_uri=http://todoapp.myapp.com &state=123456	HTTP/1.1 302 Found Location: http://todoapp.myapp.com? Code= dGVzdCBhdXRoIGNvZGU= &state=123456
Obtain access token	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=authorization_code &code= dGVzdCBhdXRoIGNvZGU= &redirect_uri= http://todoapp.myapp.com	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” “dGVzdCRva2Vu“, “token_type”:”bearer“, “expires_in”:3600, “refresh_token”:” “dGVzCB0b2tslbg=” }
Use access token to consume resources	GET /resource/1 HTTP/1.1 Host: calander.outlook.com Authorization: Bearer dGVzdCRva2Vu	Specific API Response

Note: the client can use the state to validate against Cross-site Request Forgery (XSRF) attacks.

Implicit

This flow is meant to be used by an application running in the browser only, such as JavaScript-based SPA applications (AngularJS, ReactJS, AJAX etc.). Since the application is executing at the browser of the resource owner, the use of authorization grant is not permitted. The grant issued by the authorization server passes through the browser and could be intercepted at the computer, and so it is almost impossible to reasonably secure it. Since there are no server components involved in this flow, the authorization server sends the access token to the SPA application through a URI hash fragment, and usually, the SPA application will parse the token from the URI:

• The application is un-secure and runs on the browser of the resource owner.
• The flow does not depend on browser redirection, and the token is passed as URI hash fragments.
• The client requires a “short-term” or “online” access to the resources, and so no refresh token is issued.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Obtain access token	GET /oauth2/authorize? HTTP/1.1 response_type=token &client_id= e7044267ae3e4c7d-b2b1b87dabe7d0a3 &redirect_uri= https://todoapp.myapp.com &state=123456	>HTTP/1.1 302 Found Location:https:// http://todoapp.myapp.com #access_token= dGVzdCRva2Vu &token_type=Bearer &expires_in=3600
Use access token to consume resources	GET /resource/1 HTTP/1.1 Host: calander.outlook.com Authorization: Bearer dGVzdCRva2Vu	Specific API Response

Resource Owner password credentials

This flow is suitable when the resource owner has a trust relationship with the client, such as a device OS or a privileged application. It is not recommended to use this flow unless the other flows cannot meet the requirement. This flow involves passing the username and the password of the resource owner to access the resource. The concept is like using traditional username-password based authorization, which has a number of shortcomings. But the advantage of using this over a username-password is – an access token is issued against the username-password, and an access request to resources can be performed using the token. The username-password is not required to be sent to the resource server. If the token is leaked, the token can be revoked to remove access, without the need to reset the original password.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Obtain access token	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=password &username=resourceowner_username &password=resourceowner_password	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” dGVzdCRva2Vu“, “token_type”:”bearer“, “expires_in”:3600, “refresh_token”:” dGVzCB0b2tslbg=” }
Use access token to consume resources	GET /resource/1 HTTP/1.1 Host: calander.outlook.com Authorization: Bearer dGVzdCRva2Vu	Specific API Response

Client Credential

The client credential grant is the ONLY grant used for non-delegated access. The grant is used, if the client needs to access the resources from the resource server as itself. A common use case is when the application needs to access the back-end database (resource server) to perform a scheduled background job. In this scenario, the flow is not initiated by an external resource owner, and the client itself behaves as a resource owner. A refresh token is NOT issued in this flow.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Obtain access token	>POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=client_credentials &client_id=e7044267-ae3e-4c7d-b2b1-b87dabe7d0a3 &client_password=dGhpcyBpcyaWVudF9zZWNyZXQ=	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” dGVzdCRva2Vu“, “token_type”:”bearer”, “expires_in”:3600 }
Use access token to consume resources	GET /resource/1 HTTP/1.1 Host: calander.outlook.com Authorization: Bearer dGVzdCRva2Vu	Specific API Response

Note: Client can also authenticate with the authorization server to request a token using an assertion, instead of passing the client_id and the client_secret. Please see below for more information regarding this.

Refresh Token

The access token is always issued with an expiry time, to mitigate the risk of leakage of the token, and to control the access window. If the client intends to use the access token beyond its permitted time, they would need to request a new token with a new expiry time. In that scenario, the client uses the refresh token flow to get a new access token. The client makes a call to the authorization server, and provide the refresh token, and the authorization server issues the client a new access token with the same scope and a new expiry time, and optionally a new refresh token. If a new refresh token is issued, the old refresh token is revoked, and the client would need to use the new token to make additional access token renew request. If the access token and the refresh token both expires, then the client would have to start the whole authorization flow from the start.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Renew access token	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=refresh_token &refresh_token= dGVzCB0b2tslbg=	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” “bmV3gdG9rZW4=“, “token_type”:”bearer”, “refresh_token”:” “bmV3ZdG9rZW4=” “expires_in”:3600 }

Extension Grant Type: Assertion

The above-described grant types usually assume the flow of tokens in the same security boundary, and essentially there is one authorization server in the landscape issuing tokens. But for a scenario where there are multiple authorization servers within the same or a different security boundary, the above model is not ideal. In such a case, the client would request an assertion from an authorization server (aka security token service (STS) in this case) and present the assertion to the second authorization server (aka Relying party in this case) to get an access token to access the resources in the resource server. So, assertions are an ideal framework for federated authorization flows.

An assertion is a package that contains information about the subject (the intended role the token is issued for), the issuer, and the conditions under which this assertion can be used, for example, the expiry date.

To use the assertion as grant-types to request a bearer access token, the client would need to use the below grant format Uri in its HTTP call to the /oauth2/authorize endpoint. The client may choose to request an assertion, which is not of type bearer. In this case, the assertion must demonstrate possession of additional cryptographic material and is called as Holder-of-key assertions.

• For SAML 1.1 based assertion grant type: urn:ietf:params:oauth:grant-type:saml1_1-bearer
• For SAML 2.0 based assertion grant type: urn:ietf:params:oauth:grant-type:saml2-bearer
• For JWT based assertion grant type: urn:ietf:params:oauth:grant-type:jwt-bearer

There are two models that are supported by this framework:

• Assertion Created by Third-party: In this model, the client can request for an assertion from a third-party endpoint, a.k.a. secure token service (STS), and the STS would issue an assertion which can be presented to the authorization server (relying party) to receive an access token.

• Self-issued Assertion:  In this model, the client can self-create an assertion using cryptographic information’s, pre-agreed with the authorization server (relying party). The client can request an access token from the authorization server using the self-created assertion as:

For clients trying to request an access token using an assertion instead of an authorization grant, in the “authorization code” flow, the HTTP Requests are:

Step	HTTP Request	HTTP Response
Request access token using an assertion	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=authorization_code& code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer& client_assertion=PHNhbWZTxxy65hzHqWa	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” “bmVp3vaVu“, “token_type”:”bearer”, “expires_in”:3600, “refresh_token”:” “b3Jlc2drZ4=” }

Using Assertion for Client Authentication

As mentioned above, clients can also authenticate and request tokens from the authorization server using assertions.

Token endpoints can differentiate between assertion-based credentials and other client credential types by looking for the presence of the “client_assertion” and “client_assertion_type” parameters, which will only be present when using assertions for client authentication.

Client Acting on Behalf of Itself

The client can use assertions for authentications, if they don’t want to pass the client_secret to the authorization server. As mentioned above, the client_assertion is cryptographic information pre-agreed with the authorization server. For Azure active directly, in this case, this is the base64 of a public X509 certificate, which was pre-associated with the AAD Application. Please see below for more details on AAD Application.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Request access token using an assertion	POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencodedgrant_type=client_credentials& client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Asaml2-bearer& client_assertion=PHNhbWgas46hhZT	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” “bmVp3vaVu“, “token_type”:”bearer”, “expires_in”:3600 }

Client Acting On-Behalf-Of a user (Resource Owner)

The client can use the assertion it received for the resource owner, along with the client_id and the client_secret to request for a token. The assertion the client received could be of the resource owner or another client, in which case it can be used for service-to-service authorization.

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Request access token using an assertion	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer &client_id=625391af-c675-43e5-8e44-edd3e30ceb15 &client_secret=0Y1W%2BY3yYaAaHbHHcGbcgG%2BoI%3D &assertion=eyJ0eXAiOiJKV1QiLCJhbufYKh2wm_Ti3Q &resource=https%3A%2F%2Fgraph.windows.net &requested_token_use=on_behalf_of	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” “bmVp3vaVu“, “token_type”:”bearer”, “refresh_token”:” “cmVb2tlbg=“, “expires_in”:3600 }

Or the client can use its own assertion, along with the resource owner assertion to request for a token:

The HTTP Requests performed are:

Step	HTTP Request	HTTP Response
Request access token using an assertion	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer &client_id=625391af-c675-43e5-8e44-edd3e30ceb15 &client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer &client_assertion=eyJhbGciOiJSUzI1NM8U3bSUKKJDEg &resource=https%3A%2F%2Fgraph.windows.net &assertion=eyJ0eXAiOiJKV1QiLCJhbG57ufYKh2wm_Ti3Q &requested_token_use=on_behalf_of &scope=openid	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” “bmVp3vaVu“, “token_type”:”bearer”, “refresh_token”:” “cmVb2tlbg=“, “expires_in”:3600 }

Open ID Connect

As mentioned earlier, the oAuth 2.0 is an authorization framework, and Open ID Connect is a standard which extends the oAuth 2.0 framework to provide authentication capabilities. A common use case could be, a resource owner invokes the client and logs in to prove its identity. The client used OpenId connect to get an id_token to verifies its identity, and uses the access token to access the resource in behalf of the resource owner.

The traditional oAuth access token (SAML or JWT), doesn’t have enough information to identify the resource owner, rather it has the necessary information for the resource server to determine if the client can be given access to the requested resource. The Open ID connect uses the standard oAuth 2.0 grant type flows to obtains an additional JWT token, which would have the necessary information for the client to verify the identity of the resource owner. This token is called as id_token. Please note, the id_token is issued for the client to consume, whereas the access_token is issued for the resource server to consume, and so it is supposed to be totally opaque for the client. The difference between two tokens is shown below. Please note:

• The audience (“aud” field) for an access token is the resource server, whereas the id token is the client (represented by client_id). So, to authenticate an id token, the client checks if the token is issued for itself, and then can authenticate the user principal (“upn” field).
• The access token has scope information (“scp” field), which can be used by resource server to make authorization decisions.
• The access token also has the client information (“appid” field), for the resource server to verify, if the token is sent by the expected client.

ID Token

Access Token

{ “typ”: “JWT”, “alg”: “none” } {   “aud”: “3ed522fb-7676-40a1-8759-c0059986af1d”, “iss”: “https://sts.windows.net/daf40e0b-5483-40b5-9c64-2a54fda3f965/”, “iat”: 1515002094, “nbf”: 1515002094, “exp”: 1515005994, “amr”: [ “pwd” ], “ipaddr”: “127.0.0.1”, “name”: “TestUser01”, “oid”: “6ff05aad-28c2-4c5e-84be-4b7b66f7be25”, “sub”: “AKKd_rvC4F4RjDFaWORs9CB8Ot3KyDD2rmPXJiVBNsY”, “tid”: “daf40e0b-5483-40b5-9c64-2a54fda3f965”, “unique_name”: “TestUser01@bhaskarorg.onmicrosoft.com”,   “upn”: “TestUser01@bhaskarorg.onmicrosoft.com”, “ver”: “1.0” }

{ “typ”: “JWT”, “alg”: “RS256”, “x5t”: “x478xyOplsM1H7NXk7Sx17x1upc”, “kid”: “x478xyOplsM1H7NXk7Sx17x1upc” } {   “aud”: “https://graph.windows.net”, “iss”: “https://sts.windows.net/daf40e0b-5483-40b5-9c64-2a54fda3f965/”, “iat”: 1515002094, “nbf”: 1515002094, “exp”: 1515005994, “acr”: “1”, “aio”: “ASQA2/8GAAAA6WKOu/V7Mm2fkBtNq+ePoYTu/VYXrbXmB76kNC8EHTI=”, “amr”: [ “pwd” ],   “appid”: “3ed522fb-7676-40a1-8759-c0059986af1d”, “appidacr”: “0”, “e_exp”: 262800, “ipaddr”: “127.0.0.1”, “name”: “TestUser01”, “oid”: “6ff05aad-28c2-4c5e-84be-4b7b66f7be25”, “puid”: “10033FFFA76A1BD9”,   “scp”: “Calendars.Read Contacts.ReadWriteDeviceManagementApps.ReadWrite.All MailboxSettings.ReadWrite Sites.ReadWrite.All”, “sub”: “xe3l259fONYCow8SYOJNBjhMptAN-Fnud-OyAiuU5us”, “tenant_region_scope”: “NA”, “tid”: “daf40e0b-5483-40b5-9c64-2a54fda3f965”, “unique_name”: “TestUser01@bhaskarorg.onmicrosoft.com”,   “upn”: “TestUser01@bhaskarorg.onmicrosoft.com”, “uti”: “jdspgwKZ00qRcVwKt7oIAA”, “ver”: “1.0” }

The client can send a HTTP request to the authorization server with the openid scope to request for an id_token. The scope can be in combination of other scopes, separated by spaces, in which case the authorization server would issue both the access_token (for other requested scopes) as well as the id_token (for openid scope).

The HTTP Request for a sign-in token (i.e. id_token) ONLY is:

Step	HTTP Request	HTTP Response
Request id token only	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type= authorization_code &client_id=625391af-c675-43e5-8e44-edd3e30ceb15 &scope=openid	HTTP/1.1 200 OK Content-Type: application/json { “token_type”:”bearer”, “refresh_token”:” “cmVmcmVzaC=“, “expires_in”:3600, “id_token”:” “aWR0b2tlbg==” }

The HTTP Request for a sign-in token (i.e. id_token) and an authorization token (access_token) is:

Step	HTTP Request	HTTP Response
Request access token and id token	POST /oauth2/token HTTP/1.1 Host: login.microsoftonline.com Content-Type: application/x-www-form-urlencodedgrant_type=authorization_code &client_id=625391af-c675-43e5-8e44-edd3e30ceb15 &scope=openid%20email.read	HTTP/1.1 200 OK Content-Type: application/json { “access_token”:” bmVp3vaVu” “token_type”:”bearer”, “refresh_token”:” “cmVmcmVzaC=“, “expires_in”:3600, “id_token”:” “aWR0b2tlbg==” }

Azure Active Directory Implementations of oAuth 2.0

In Azure Active Directory, the client is represented as an AAD Application, and the client credential is represented as a service principal. The instance of the directory for a specific organization, where all the components are parented is called as “tenant”. The AAD Application and the credentials are by default parented to a tenant, but AAD supports authorization and authentication flows against multiple tenants, during federations.

AAD Application

The AAD Application is the representation of the “client” in the above oAuth 2.0 concept. There are two types of application:

• Native Application: The native applications are used for an authorization_code, implicit or resource owner password grant type flow for installed applications, e.g. PowerShell, installed windows application or mobile application. The native application cannot have a credential, as credential secrecy cannot be trusted for native applications. For native & mobile apps, the client should use the default value of urn:ietf:wg:oauth:2.0:oob for the redirect_uri parameter to the authorization server.
• Web Applications: The web application can be used for all the grant types, except resource owner password grant. They are designed to be used with web applications or client-side browser-based applications. The web application can store credentials (aka client_secret). The web applications can be used without any credential (authorization_code and implicit grant types) or with a credentials (client_credential grant types or for client authentication during the other flows). The web application can also accept an assertion (in the form of a certificate instead of a client_secret) to request for tokens. Please see the client assertion section above.

Service Principals

Service principals represent a credential for a web application, scoped to a specific tenant. So, for a web-application, there can be only one service principal scoped to a specific tenant but can have multiple service principals scoped to different tenants under the same application. Multiple service principals can be used to perform oAuth 2.0 flows against multiple tenants. Like any AAD credentials, it can have a client_secret or an assertion (in the form of a certificate). Please note, an Web application can have no service principal at all, in which case in can perform authorization requests against its own parent tenant ONLY, using the application credentials.

Active Directory Authentication Library (ADAL)

The Azure Active Directory team has a library which lets developer’s use all the above flow easily in their applications. The ADAL abstract out the multi-step HTTP calls to provide easy implementation of the flow. The ADAL can used in multiple languages. It also has code samples on how to use it for each application. The ADAL can be downloaded at – https://docs.microsoft.com/en-us/azure/active-directory/develop/active-directory-authentication-libraries.