Merge pull request #102465 from navyasric/auth-doc-updates

Add Java and Python OBO scenario docs

Author: GitHubber17

articles/active-directory/develop/index.yml

@@ -3,14 +3,14 @@
 title: Microsoft identity platform (formerly Azure Active Directory for developers)
 summary: Microsoft identity platform is an evolution of the Azure Active Directory (Azure AD) developer platform. It allows developers to build applications that sign in all Microsoft identities and get tokens to call Microsoft APIs such as Microsoft Graph or APIs that developers have built. It’s a full-featured platform that consists of an OAuth 2.0 and OpenID Connect standard-compliant authentication service, open-source libraries, application registration and configuration, robust conceptual and reference documentation, quickstart samples, code samples, tutorials, and how-to guides.
 
-metadata: 
+metadata:
    ms.topic: landing-page
    ms.date: 06/22/2019
    author: CelesteDG
    ms.author: celested
    ms.service: active-directory
    ms.subservice: develop
-   ms.workload: identity   
+   ms.workload: identity
 
 landingContent:
   - title: About Microsoft identity platform
@@ -46,7 +46,7 @@ landingContent:
           - text: JavaScript
             url: quickstart-v2-javascript.md
       - linkListType: tutorial
-        links: 
+        links:
           - text: JavaScript
             url: tutorial-v2-javascript-spa.md
       - linkListType: download
@@ -67,27 +67,37 @@ landingContent:
             url: quickstart-v2-aspnet-core-webapp.md
           - text: ASP.NET
             url: quickstart-v2-aspnet-webapp.md
+          - text: Java
+            url: quickstart-v2-java-webapp.md
+          - text: Python
+            url: quickstart-v2-python-webapp.md
       - linkListType: tutorial
-        links: 
+        links:
           - text: ASP.NET Core
             url: https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2
       - linkListType: download
         links:
-          - text: Samples - ASP.NET Core, ASP.NET
+          - text: Samples - ASP.NET Core, ASP.NET, Java, Python
             url: sample-v2-code.md#web-applications
   - title: Build a web app that calls web APIs
     linkLists:
       - linkListType: get-started
         links:
           - text: Scenario overview
             url: scenario-web-app-call-api-overview.md
+      - linkListType: quickstart
+        links:
+          - text: Java
+            url: quickstart-v2-java-webapp.md
+          - text: Python
+            url: quickstart-v2-python-webapp.md
       - linkListType: tutorial
-        links: 
+        links:
           - text: ASP.NET Core
             url: https://github.com/Azure-Samples/active-directory-aspnetcore-webapp-openidconnect-v2#scope-of-this-tutorial
       - linkListType: download
         links:
-          - text: Samples - ASP.NET Core, ASP.NET, Node.js, Ruby
+          - text: Samples - ASP.NET Core, ASP.NET, Node.js, Ruby, Java, Python
             url: sample-v2-code.md#web-applications
   - title: Build a protected web API
     linkLists:
@@ -96,7 +106,7 @@ landingContent:
           - text: Scenario overview
             url: scenario-protected-web-api-overview.md
       - linkListType: tutorial
-        links: 
+        links:
           - text: ASP.NET Core web API
             url: https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2
       - linkListType: download
@@ -110,30 +120,32 @@ landingContent:
           - text: Scenario overview
             url: scenario-web-api-call-api-overview.md
       - linkListType: tutorial
-        links: 
+        links:
           - text: ASP.NET Core web API that calls Microsoft Graph
             url: https://github.com/Azure-Samples/active-directory-dotnet-native-aspnetcore-v2/tree/master/2.%20Web%20API%20now%20calls%20Microsoft%20Graph
+          - text: Java web API that calls Microsoft Graph
+            url: https://github.com/Azure-Samples/ms-identity-java-webapi
   - title: Build a desktop app that calls web APIs
     linkLists:
       - linkListType: get-started
         links:
           - text: Scenario overview
             url: scenario-desktop-overview.md
       - linkListType: quickstart
-        links: 
+        links:
           - text: Acquire a token & call Microsoft Graph API (Windows desktop)
             url: quickstart-v2-windows-desktop.md
           - text: Acquire a token & call Microsoft Graph API (UWP)
             url: quickstart-v2-uwp.md
       - linkListType: tutorial
-        links: 
+        links:
           - text: Call Microsoft Graph API (Windows desktop)
             url: tutorial-v2-windows-desktop.md
           - text: Call Microsoft Graph API (UWP)
             url: tutorial-v2-windows-uwp.md
       - linkListType: download
         links:
-          - text: Sample - .NET, .NET Core
+          - text: Sample - .NET, .NET Core, Java, Python
             url: sample-v2-code.md#desktop-and-mobile-public-client-apps
   - title: Build a daemon app that calls web APIs
     linkLists:
@@ -142,14 +154,14 @@ landingContent:
           - text: Scenario overview
             url: scenario-daemon-overview.md
       - linkListType: quickstart
-        links: 
+        links:
           - text: Acquire a token & call Microsoft Graph API (.NET Core console)
             url: quickstart-v2-netcore-daemon.md
           - text: Acquire a token & call Microsoft Graph API (ASP.NET web app)
             url: https://github.com/Azure-Samples/ms-identity-aspnet-daemon-webapp
       - linkListType: download
         links:
-          - text: Samples - ASP.NET console, ASP.NET web
+          - text: Samples - ASP.NET console, ASP.NET web, Java, Python
             url: sample-v2-code.md#daemon-applications
   - title: Build a mobile app that calls web APIs
     linkLists:
@@ -158,15 +170,15 @@ landingContent:
           - text: Scenario overview
             url: scenario-mobile-overview.md
       - linkListType: quickstart
-        links: 
+        links:
           - text: Acquire a token & call Microsoft Graph API (Android)
             url: quickstart-v2-android.md
           - text: Acquire a token & call Microsoft Graph API (iOS)
             url: quickstart-v2-ios.md
           - text: Acquire a token & call Microsoft Graph API (Xamarin iOS & Android)
             url: https://github.com/Azure-Samples/active-directory-xamarin-native-v2
       - linkListType: tutorial
-        links: 
+        links:
           - text: Sign in users & call Microsoft Graph API (Android)
             url: tutorial-v2-android.md
           - text: Sign in users & call Microsoft Graph API (iOS)
@@ -182,7 +194,7 @@ landingContent:
           - text: About Microsoft Graph
             url: https://docs.microsoft.com/graph/overview
       - linkListType: quickstart
-        links: 
+        links:
           - text: Get up and running in 3 minutes
             url: https://developer.microsoft.com/graph/get-started
       - linkListType: learn
@@ -192,9 +204,9 @@ landingContent:
           - text: Microsoft Graph REST API v1.0
             url: https://docs.microsoft.com/graph/api/overview?toc=.%2Fref%2Ftoc.json&view=graph-rest-1.0
           - text: Microsoft Graph REST API Beta
-            url: https://docs.microsoft.com/graph/api/overview?toc=.%2Fref%2Ftoc.json&view=graph-rest-beta          
+            url: https://docs.microsoft.com/graph/api/overview?toc=.%2Fref%2Ftoc.json&view=graph-rest-beta
       - linkListType: deploy
-        links: 
+        links:
           - text: Graph Explorer
             url: https://developer.microsoft.com/graph/graph-explorer/
   - title: Build a customer-facing app that signs in social & local identities

articles/active-directory/develop/sample-v2-code.md

@@ -69,6 +69,7 @@ The following samples show public client applications (desktop or mobile applica
 | ------------------ | -------- |  ----------| ---------- | ------------------------- |
 | Desktop (WPF)      | ![This image shows the .NET/C# logo](media/sample-v2-code/logo_NET.png) | [interactive](msal-authentication-flows.md#interactive)| [dotnet-desktop-msgraph-v2](https://github.com/azure-samples/active-directory-dotnet-desktop-msgraph-v2) | [dotnet-native-aspnetcore-v2](https://aka.ms/msidentity-aspnetcore-webapi) |
 | Desktop (Console)   | ![This image shows the .NET/C# (Desktop) logo](media/sample-v2-code/logo_NET.png) | [Integrated Windows Authentication](msal-authentication-flows.md#integrated-windows-authentication) | [dotnet-iwa-v2](https://github.com/azure-samples/active-directory-dotnet-iwa-v2) |  |
+| Desktop (Console)   | ![This image shows the Java logo](media/sample-v2-code/logo_java.png) | [Integrated Windows Authentication](msal-authentication-flows.md#integrated-windows-authentication) |[ms-identity-java-desktop](https://github.com/Azure-Samples/ms-identity-java-desktop/) |  |
 | Desktop (Console)   | ![This image shows the .NET/C# (Desktop) logo](media/sample-v2-code/logo_NETcore.png) | [Username/Password](msal-authentication-flows.md#usernamepassword) |[dotnetcore-up-v2](https://github.com/azure-samples/active-directory-dotnetcore-console-up-v2) |  |
 | Desktop (Console)   | ![This image shows the Java logo](media/sample-v2-code/logo_java.png) | [Username/Password](msal-authentication-flows.md#usernamepassword) |[ms-identity-java-desktop](https://github.com/Azure-Samples/ms-identity-java-desktop/) |  |
 | Desktop (Console)   | ![This image shows the Python logo](media/sample-v2-code/logo_python.png) | [Username/Password](msal-authentication-flows.md#usernamepassword) |[ms-identity-python-desktop](https://github.com/Azure-Samples/ms-identity-python-desktop) |  |

articles/active-directory/develop/scenario-web-api-call-api-acquire-token.md

@@ -15,7 +15,7 @@ ms.tgt_pltfrm: na
 ms.workload: identity
 ms.date: 05/07/2019
 ms.author: jmprieur
-ms.custom: aaddev 
+ms.custom: aaddev
 #Customer intent: As an application developer, I want to know how to write a web API that calls web APIs by using the Microsoft identity platform for developers.
 ---
 
@@ -25,6 +25,8 @@ After you've built a client application object, use it to acquire a token that y
 
 ## Code in the controller
 
+# [ASP.NET Core](#tab/aspnetcore)
+
 Here's an example of code that's called in the actions of the API controllers. It calls a downstream API named *todolist*.
 
 ```csharp
@@ -66,6 +68,33 @@ public static string GetMsalAccountId(this ClaimsPrincipal claimsPrincipal)
 }
 ```
 
+# [Java](#tab/java)
+Here's an example of code that's called in the actions of the API controllers. It calls the downstream API - Microsoft Graph.
+
+```java
+@RestController
+public class ApiController {
+
+    @Autowired
+    MsalAuthHelper msalAuthHelper;
+
+    @RequestMapping("/graphMeApi")
+    public String graphMeApi() throws MalformedURLException {
+
+        String oboAccessToken = msalAuthHelper.getOboToken("https://graph.microsoft.com/.default");
+
+        return callMicrosoftGraphMeEndpoint(oboAccessToken);
+    }
+
+}
+```
+
+# [Python](#tab/python)
+
+A Python web API will need to use some middleware to validate the bearer token received from the client. The web API can then obtain the access token for downstream API using MSAL Python library by calling the [`acquire_token_on_behalf_of`](https://msal-python.readthedocs.io/en/latest/?badge=latest#msal.ConfidentialClientApplication.acquire_token_on_behalf_of) method. A sample demonstrating this flow with MSAL Python is not yet available.
+
+---
+
 ## Next steps
 
 > [!div class="nextstepaction"]

articles/active-directory/develop/scenario-web-api-call-api-app-configuration.md

@@ -15,7 +15,7 @@ ms.tgt_pltfrm: na
 ms.workload: identity
 ms.date: 07/16/2019
 ms.author: jmprieur
-ms.custom: aaddev 
+ms.custom: aaddev
 #Customer intent: As an application developer, I want to know how to write a web API that calls web APIs by using the Microsoft identity platform for developers.
 ---
 
@@ -25,6 +25,8 @@ After you've registered your web API, you can configure the code for the applica
 
 The code that you use to configure your web API so that it calls downstream web APIs builds on top of the code that's used to protect a web API. For more information, see [Protected web API: App configuration](scenario-protected-web-api-app-configuration.md).
 
+# [ASP.NET Core](#tab/aspnetcore)
+
 ## Code subscribed to OnTokenValidated
 
 On top of the code configuration for any protected web APIs, you need to subscribe to the validation of the bearer token that you receive when your API is called:
@@ -44,15 +46,15 @@ public static IServiceCollection AddProtectedApiCallsWebApis(this IServiceCollec
     services.AddTokenAcquisition();
     services.Configure<JwtBearerOptions>(AzureADDefaults.JwtBearerAuthenticationScheme, options =>
     {
-        // When an access token for our own web API is validated, we add it 
+        // When an access token for our own web API is validated, we add it
         // to the MSAL.NET cache so that it can be used from the controllers.
         options.Events = new JwtBearerEvents();
 
         options.Events.OnTokenValidated = async context =>
         {
             context.Success();
 
-            // Adds the token to the cache and handles the incremental consent 
+            // Adds the token to the cache and handles the incremental consent
             // and claim challenges
             AddAccountToCacheFromJwt(context, scopes);
             await Task.FromResult(0);
@@ -139,6 +141,82 @@ private void AddAccountToCacheFromJwt(IEnumerable<string> scopes, JwtSecurityTok
      }
 }
 ```
+# [Java](#tab/java)
+
+The On-behalf-of (OBO) flow is used to obtain a token to call the downstream web API. In this flow, your web API receives a bearer token with user delegated permissions from the client application and then exchanges this token for another access token to call the downstream web API.
+
+The code below uses Spring Security framework's `SecurityContextHolder` in the web API to get the validated bearer token. It then uses the MSAL Java library to obtain a token for downstream API using the `acquireToken` call with `OnBehalfOfParameters`. MSAL caches the token so that subsequent calls to the API can use `acquireTokenSilently` to get the cached token.
+
+```Java
+@Component
+class MsalAuthHelper {
+
+    @Value("${security.oauth2.client.authority}")
+    private String authority;
+
+    @Value("${security.oauth2.client.client-id}")
+    private String clientId;
+
+    @Value("${security.oauth2.client.client-secret}")
+    private String secret;
+
+    @Autowired
+    CacheManager cacheManager;
+
+    private String getAuthToken(){
+        String res = null;
+        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
+
+        if(authentication != null){
+            res = ((OAuth2AuthenticationDetails) authentication.getDetails()).getTokenValue();
+        }
+        return res;
+    }
+
+    String getOboToken(String scope) throws MalformedURLException {
+        String authToken = getAuthToken();
+
+        ConfidentialClientApplication application =
+                ConfidentialClientApplication.builder(clientId, ClientCredentialFactory.create(secret))
+                        .authority(authority).build();
+
+        String cacheKey = Hashing.sha256()
+                .hashString(authToken, StandardCharsets.UTF_8).toString();
+
+        String cachedTokens = cacheManager.getCache("tokens").get(cacheKey, String.class);
+        if(cachedTokens != null){
+            application.tokenCache().deserialize(cachedTokens);
+        }
+
+        IAuthenticationResult auth;
+        SilentParameters silentParameters =
+                SilentParameters.builder(Collections.singleton(scope))
+                        .build();
+        auth = application.acquireTokenSilently(silentParameters).join();
+
+        if (auth == null){
+            OnBehalfOfParameters parameters =
+                    OnBehalfOfParameters.builder(Collections.singleton(scope),
+                            new UserAssertion(authToken))
+                            .build();
+
+            auth = application.acquireToken(parameters).join();
+        }
+
+        cacheManager.getCache("tokens").put(cacheKey, application.tokenCache().serialize());
+
+        return auth.accessToken();
+    }
+}
+```
+
+# [Python](#tab/python)
+
+The On-behalf-of (OBO) flow is used to obtain a token to call the downstream web API. In this flow, your web API receives a bearer token with user delegated permissions from the client application and then exchanges this token for another access token to call the downstream web API.
+
+A Python web API will need to use some middleware to validate the bearer token received from the client. The web API can then obtain the access token for downstream API using MSAL Python library by calling the [`acquire_token_on_behalf_of`](https://msal-python.readthedocs.io/en/latest/?badge=latest#msal.ConfidentialClientApplication.acquire_token_on_behalf_of) method. A sample demonstrating this flow with MSAL Python is not yet available.
+
+---
 
 You can also see an example of OBO flow implementation in [Node.js and Azure Functions](https://github.com/Azure-Samples/ms-identity-nodejs-webapi-onbehalfof-azurefunctions/blob/master/MiddleTierAPI/MyHttpTrigger/index.js#L61).