[Feature Request] It should be possible to use GraphServiceClient to call graph APIs requiring app only permissions

[jmprieur]

Is your feature request related to a problem? Please describe.
When developers want to call graph to call an app only method, the current GraphServiceClient cannot be used as it uses GetTokenForUserAsync. See

microsoft-identity-web/src/Microsoft.Identity.Web.MicrosoftGraph/TokenAcquisitionCredentialProvider.cs

Line 39 in f609eee

await _tokenAcquisition.GetAccessTokenForUserAsync(_initialScopes).ConfigureAwait(false)));

number of customers hitting this issue so far: 2

Describe the solution you'd like
Have a way to call app only methods (corresponding to App-only scopes)

Describe alternatives you've considered

• enable a second GraphServiceClient to be injected (with a different type ?). Maybe a class named AppOnlyGraphServiceClient which would have only one property which would be the GraphServiceClient, or which would inherit from GraphServiceClient.
• have an extension method on GraphServiceClient which would specify that the developer wants to have an app-only and then use it GetTokenForUserAsync. See

  microsoft-identity-web/src/Microsoft.Identity.Web.MicrosoftGraph/TokenAcquisitionCredentialProvider.cs

  Line 39 in f609eee

  await _tokenAcquisition.GetAccessTokenForUserAsync(_initialScopes).ConfigureAwait(false)));

Additional context
See the ASP.NET Core Graph web hooks sample where the GraphServiceClient can only be used for delegated scopes:

[davesmits]

Maybe little bit of topic; but I want to avoid using an app account as they very often (if not always) need Admin consent from the tenant. For client applications it can be helpful is the gateway way api to the graph will do some background work

So imagine:
native client app -> user signs in and goes with token to gateway api

gateway api -> with the token from the native client is able to exchange it to a token for the graph api. If the offline scope is present this new access token will have a refrsh token too. Now want to 'store' it somewhere so a background process is able to get new access tokens to do work in the background for this specific user (in my case it was updating webhook subscription)

Currently the api takes so many concerns out of your hands that you don't see/ have access to this refresh token at all. Making it hard to get a background process alive for a user

[jmprieur]

@davesmits, so I guess Microsoft.identity.Web should enable background processes .... :)

[jmprieur]

Proposed API

Given that we cannot intervene in the GraphServiceClient class, and we want to enable GraphServiceClient properties/methods/queries that return information requesting app-only permissions (client credentials), the idea is to intervene at the authentication provider level (this is what uses ITokenAcquisition).

In order to have a local effect, I propose to have a new class MicrosoftGraphTokenAcquisitionOptions in the Microsoft.Identity.Web.MicrosoftGraph project, and that would implement IDisposable, so that its effect is effectively contained into a method or a block through the using instruction

App-only scopes

To call a method/property (like Applications) that requires app-only-permissions, the developer experience would be something like the following.

 /// <summary>
/// Illustrates how to call MicrosoftGraph using the Graph SDK and request app-only permissions.
/// These permissions must have been pre-consented by the admin.
/// </summary>
/// <returns></returns>
public async Task<IEnumerable<string>> Get100FirstApplications()
{
  using var graphOptions = MicrosoftGraphTokenAcquisitionOptions.UseAppOnlyPermissions(_graphServiceClient);

  var apps = await _graphServiceClient.Applications.Request().GetAsync();
  return apps.Select(a => a.DisplayName);
}

in this method the using instruction applies until the end of the method, but a using() {} block could be used to have more fine grain control.

Additional scopes

As we are solving this problem, we could also enable overriding the default scopes defined in authentication provider, writing something like the following

using (var graphTokenAcquisitionOptions = new MicrosoftGraphTokenAcquisitionOptions(_graphServiceClient, "mail.read"))
{
   var mails = _graphServiceClient.Me.MailFolders.Inbox.Messages.Request().GetAsync();
   // do something with mails
}

Discussion

Why a static method for the app-only permissions?

I had initially thought of exposing a constructor like:

 public MicrosoftGraphTokenAcquisitionOptions(GraphServiceClient graphServiceClient,
            bool appOnlyPermissions = false, params string[] scopes)

however, in the case where appOnlyPermissions is true, no need to pass-in the scopes as they should be https://graph.microsoft.com/.default (client creds), so a static method MicrosoftGraphTokenAcquisitionOptions.GetAppOnlyPermissions(_graphServiceClient)) is better.

We could expose more:

Not requested by anybody yet, but we might want to also expose a constructor with the tenantId (for multi-tenant applications), and the TokenAcquisitionOptions.

It would actually be useful in the scenario show cased in this test app:

microsoft-identity-web/tests/WebAppCallsWebApiCallsGraph/TodoListService/Controllers/TodoListController.cs

Line 51 in 3411f8a

// string token1 = await _tokenAcquisition.GetAccessTokenForUserAsync(new string[] { "user.read" }, "7f58f645-c190-4ce5-9de4-e2b7acd2a6ab").ConfigureAwait(false);

Question

Would it be better to pass-in a delegate? probably not, as this is a different mechanism than with IDownstreamWebApi (where the options passed-in are local to the call. In the case of GraphService client this is for the lifetime of the MicrosoftGraphTokenAcquisitionOptions instance (until it's disposed), that is a block.

Proposed design:

MicrosoftGraphTokenAcquisitionOptions class

Something like the following?

using System;
using Microsoft.Graph;

namespace Microsoft.Identity.Web.MicrosoftGraph
{
    /// <summary>
    /// Token acquisition options to apply to the Microsoft Graph SDK's GraphServiceClient
    /// </summary>
    public class MicrosoftGraphTokenAcquisitionOptions
        : IDisposable
    {
        /// <summary>
        /// Builds a MicrosoftGraphTokenAcquisitionOptions instance allowing for app only permissions
        /// </summary>
        /// <param name="graphServiceClient">Graph service client, injected by dependency injection
        /// for which we want to use app only permissions in the scope of the lifetime of the created
        /// `MicrosoftGraphTokenAcquisitionOptions`</param>
        /// <returns></returns>
        public static MicrosoftGraphTokenAcquisitionOptions UseAppOnlyPermissions(GraphServiceClient graphServiceClient)
        {
            return new MicrosoftGraphTokenAcquisitionOptions(graphServiceClient, true, "https://graph.microsoft.com/.default");
        }

        /// <summary>
        /// Builds a MicrosoftGraphTokenAcquisitionOptions instance allowing to override delegated permission scopes
        /// </summary>
        /// <param name="graphServiceClient"></param>
        /// <param name="scopes"></param>
        public MicrosoftGraphTokenAcquisitionOptions(GraphServiceClient graphServiceClient,
           params string[] scopes) : this(graphServiceClient, false, scopes)
        {
        }

        private MicrosoftGraphTokenAcquisitionOptions(GraphServiceClient graphServiceClient,
            bool appOnlyPermissions = false, params string[] scopes)
        {
#pragma warning disable CS8601 // Possible null reference assignment.
            tokenAcquisitionCredentialProvider = graphServiceClient.AuthenticationProvider as TokenAcquisitionCredentialProvider;
#pragma warning restore CS8601 // Possible null reference assignment.
            if (tokenAcquisitionCredentialProvider == null)
            {
                throw new ArgumentException("graphServiceClient should be injected with dependency injection after you use .AddMicrosoftGraph in the Startup.cs");
            }

            // Keeps the previous values of tokenAcquisitionCredentialProvider and sets the new value
            PreviousAppOnlyPermissions = tokenAcquisitionCredentialProvider.RequiresAppPermissions;
            PreviousScopes = tokenAcquisitionCredentialProvider.Scopes;

            tokenAcquisitionCredentialProvider.RequiresAppPermissions = appOnlyPermissions;
            tokenAcquisitionCredentialProvider.Scopes = scopes;

            // We could also have:
            // - TenantId
            // - TokenAcquisitionOptions
        }


        private bool PreviousAppOnlyPermissions { get; set; }

        private string[] PreviousScopes { get; set; }

        private TokenAcquisitionCredentialProvider tokenAcquisitionCredentialProvider;

        /// <summary>
        /// Restores the previous value of the token acquisition properties in the tokenAcquisitionCredentialProvider
        /// </summary>
        public void Dispose()
        {
            tokenAcquisitionCredentialProvider.Scopes = PreviousScopes;
            tokenAcquisitionCredentialProvider.RequiresAppPermissions = PreviousAppOnlyPermissions;
        }
    }
}

Update TokenAcquisitionCredentialProvider

Add internal properties

for instance:

        internal string[] Scopes { get; set; }

        internal bool RequiresAppPermissions { get; set; }

Modify AuthenticateRequestAsync()

Something like the following?

• compute the scopes (with a default being the initiali scopes)
• get the access token based on whether this is an app only or a delegated permission.

       public async Task AuthenticateRequestAsync(HttpRequestMessage request)
        {
            IEnumerable<string> effectiveScopes = (Scopes != null && Scopes.Any()) ? Scopes : _initialScopes;

            string accessToken = RequiresAppPermissions
                ? await _tokenAcquisition.GetAccessTokenForAppAsync("https://graph.microsoft.com/.default").ConfigureAwait(false)
                : await _tokenAcquisition.GetAccessTokenForUserAsync(effectiveScopes).ConfigureAwait(false);

            request.Headers.Add(
                Constants.Authorization,
                string.Format(
                    CultureInfo.InvariantCulture,
                    "{0} {1}",
                    Constants.Bearer,
                    accessToken
                    ));
        }

Tests

We could add a controller in the WebAppCallsGraph test to get the list of all applications (or all users). this would require an admin consent.

[jmprieur]

@baywet and @darrelmiller: what do you think of the design?

[jmprieur]

@1iveowl, what do you think of the design:

/// <summary>
/// Illustrates how to call MicrosoftGraph using the Graph SDK and request app-only permissions.
/// These permissions must have been pre-consented by the admin.
/// </summary>
/// <returns></returns>
public async Task<IEnumerable<string>> Get100FirstApplications()
{
  using var graphOptions = MicrosoftGraphTokenAcquisitionOptions.UseAppOnlyPermissions(_graphServiceClient);

  var apps = await _graphServiceClient.Applications.Request().GetAsync();
  return apps.Select(a => a.DisplayName);
}

[1iveowl]

Thank you @jmprieur. This design makes good sense to me.

How/where are the app credentials specified?

[jmprieur]

They don't need to be, @1iveowl: applications that require tokens on behalf of themselves (not on behalf of the user), that is which use the Client Credentials flow, need to use a scope which is of the form "{resource}/.default", and for Microsoft.Graph the resource is "https://graph.microsoft.com", and therefore it's not even needed to pass-in scopes. The permissions need to be granted by the tenant admin, of course.

[1iveowl]

Of course. Thank you 👍

[baywet]

@jmprieur thanks for taking a stab at that. It feels a bit complex to use and "dangerous" (in the case the consumer forgets the using statement, it derails the whole application after the use of app only context)

MS.ID.Web depends on the asp.net infrastructure, what about injecting a second graphserviceclient (wrapped) and providing a fluent API to add it to the services?

In the startup they'd do something like

services.AddAuthentication(OpenIdConnectDefaults.AuthenticationScheme)
                .AddMicrosoftIdentityWebApp(configuration.GetSection("AzureAd"))
                .EnableTokenAcquisitionToCallDownstreamApi( new string[] { configuration.GetValue<string>("SubscriptionSettings:Scope") })
                .AddMicrosoftGraph(configuration.GetSection("DownstreamApi"))
                .AddAppOnlyContext() // <---- this is new
                .AddInMemoryTokenCaches();

As glue

public interface IAppOnlyGraphServiceClient {
GraphServiceClient Value;
}

In the controller

public NotificationController(ISubscriptionStore subscriptionStore,
                                      IHubContext<NotificationHub> notificationHub,
                                      ILogger<NotificationController> logger,
                                      ITokenAcquisition tokenAcquisition,
                                      IOptions<MicrosoftIdentityOptions> identityOptions,
                                      KeyVaultManager keyVaultManager,
                                      IOptions<DownstreamApiSettings> appSettings,
                                      IOptions<SubscriptionOptions> subscriptionOptions,
                                      GraphServiceClient graphServiceClient,
                                      IAppOnlyGraphServiceClient<GraphServiceClient> appOnlyClient)
//... do something

[jmprieur]

Thanks @baywet

This would solve the issue of the app-only permission, but not the scopes.
@darrelmiller: when can we benefit from .WithScopes()?