User authentication samples (#11343)

sdk/identity/azure-identity/MANIFEST.in

@@ -1,3 +1,4 @@
+recursive-include samples *.py
 recursive-include tests *.py
 include *.md
-include azure/__init__.py
+include azure/__init__.py

sdk/identity/azure-identity/samples/README.md

@@ -0,0 +1,37 @@
+---
+page_type: sample
+languages:
+  - python
+products:
+  - azure
+  - azure-identity
+urlFragment: identity-samples
+---
+
+# Azure Identity Library Python Samples
+
+## Prerequisites
+
+You must have an [Azure subscription](https://azure.microsoft.com/free) and an
+[Azure Key Vault](https://azure.microsoft.com/en-us/services/key-vault/) to run
+these samples. You can create a Key Vault in the
+[Azure Portal](https://portal.azure.com/#create/Microsoft.KeyVault) or with the
+[Azure CLI](https://docs.microsoft.com/en-us/azure/key-vault/secrets/quick-create-cli).
+
+Azure Key Vault is used only to demonstrate authentication. Azure Identity has
+the same API for all compatible client libraries.
+
+## Setup
+
+To run these samples, first install the Azure Identity and Key Vault Secrets
+client libraries:
+
+```commandline
+pip install azure-identity azure-keyvault-secrets
+```
+
+## Contents
+| File | Description |
+|-------------|-------------|
+| control_interactive_prompts.py | demonstrates controlling when interactive credentials prompt for user interaction |
+| user_authentication.py | demonstrates user authentication API for applications |

sdk/identity/azure-identity/samples/control_interactive_prompts.py

@@ -0,0 +1,38 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+"""Demonstrates controlling the timing of interactive authentication using InteractiveBrowserCredential.
+
+DeviceCodeCredential supports the same API.
+"""
+
+import os
+import sys
+from azure.identity import AuthenticationRequiredError, InteractiveBrowserCredential
+from azure.keyvault.secrets import SecretClient
+
+
+# This sample uses Key Vault only for demonstration. Any client accepting azure-identity credentials will work the same.
+VAULT_URL = os.environ.get("VAULT_URL")
+if not VAULT_URL:
+    print("This sample expects environment variable 'VAULT_URL' to be set with the URL of a Key Vault.")
+    sys.exit(1)
+
+
+# If it's important for your application to prompt for authentication only at certain times,
+# create the credential with disable_automatic_authentication=True. This configures the credential to raise
+# when interactive authentication is required, instead of immediately beginning that authentication.
+credential = InteractiveBrowserCredential(disable_automatic_authentication=True)
+client = SecretClient(VAULT_URL, credential)
+
+try:
+    secret_names = [s.name for s in client.list_properties_of_secrets()]
+except AuthenticationRequiredError as ex:
+    # Interactive authentication is necessary to authorize the client's request. The exception carries the
+    # requested authentication scopes. If you pass these to 'authenticate', it will cache an access token
+    # for those scopes.
+    credential.authenticate(scopes=ex.scopes)
+
+# the client operation should now succeed
+secret_names = [s.name for s in client.list_properties_of_secrets()]

sdk/identity/azure-identity/samples/user_authentication.py

@@ -0,0 +1,43 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+"""Demonstrates user authentication using InteractiveBrowserCredential. DeviceCodeCredential supports the same API."""
+
+import os
+import sys
+from azure.identity import AuthenticationRecord, InteractiveBrowserCredential
+from azure.keyvault.secrets import SecretClient
+
+
+# This sample uses Key Vault only for demonstration. Any client accepting azure-identity credentials will work the same.
+VAULT_URL = os.environ.get("VAULT_URL")
+if not VAULT_URL:
+    print("This sample expects environment variable 'VAULT_URL' to be set with the URL of a Key Vault.")
+    sys.exit(1)
+
+
+# Persistent caching is optional. By default, interactive credentials cache in memory only.
+credential = InteractiveBrowserCredential(enable_persistent_cache=True)
+
+# The 'authenticate' method begins interactive authentication. Call it whenever it's convenient
+# for your application to authenticate a user. It returns a record of the authentication.
+record = credential.authenticate()
+
+# The record contains no authentication secrets. You can serialize it to JSON for storage.
+record_json = record.serialize()
+
+# An authenticated credential is ready for use with a client. This request should succeed
+# without prompting for authentication again.
+client = SecretClient(VAULT_URL, credential)
+secret_names = [s.name for s in client.list_properties_of_secrets()]
+
+# With persistent caching enabled, an authentication record stored by your application enables
+# credentials to access data from past authentications. If the cache contains sufficient data,
+# this eliminates the need for your application to prompt for authentication every time it runs.
+deserialized_record = AuthenticationRecord.deserialize(record_json)
+new_credential = InteractiveBrowserCredential(enable_persistent_cache=True, authentication_record=deserialized_record)
+
+# This request should also succeed without prompting for authentication.
+client = SecretClient(VAULT_URL, new_credential)
+secret_names = [s.name for s in client.list_properties_of_secrets()]