Add cloud instances string constants

Reduce duplicated magic strings

Add test cases

Writing docs

Author: rayluo

msal/application.py

@@ -231,8 +231,23 @@ def __init__(
 
         :param str authority:
             A URL that identifies a token authority. It should be of the format
-            https://login.microsoftonline.com/your_tenant
-            By default, we will use https://login.microsoftonline.com/common
+            ``https://login.microsoftonline.com/your_tenant``
+            By default, we will use ``https://login.microsoftonline.com/common``
+
+            *Changed in version 1.17*: you can also use predefined constant
+            and a builder like this::
+
+                from msal.authority import (
+                    AuthorityBuilder,
+                    AZURE_US_GOVERNMENT, AZURE_CHINA, AZURE_PUBLIC)
+                my_authority = AuthorityBuilder(AZURE_PUBLIC, "contoso.onmicrosoft.com")
+                # Now you get an equivalent of
+                # "https://login.microsoftonline.com/contoso.onmicrosoft.com"
+
+                # You can feed such an authority to msal's ClientApplication
+                from msal import PublicClientApplication
+                app = PublicClientApplication("my_client_id", authority=my_authority, ...)
+
         :param bool validate_authority: (optional) Turns authority validation
             on or off. This parameter default to true.
         :param TokenCache cache:

msal/authority.py

@@ -14,12 +14,19 @@
 
 
 logger = logging.getLogger(__name__)
+
+# Endpoints were copied from here
+# https://docs.microsoft.com/en-us/azure/active-directory/develop/authentication-national-cloud#azure-ad-authentication-endpoints
+AZURE_US_GOVERNMENT = "login.microsoftonline.us"
+AZURE_CHINA = "login.chinacloudapi.cn"
+AZURE_PUBLIC = "login.microsoftonline.com"
+
 WORLD_WIDE = 'login.microsoftonline.com'  # There was an alias login.windows.net
 WELL_KNOWN_AUTHORITY_HOSTS = set([
     WORLD_WIDE,
-    'login.chinacloudapi.cn',
+    AZURE_CHINA,
     'login-us.microsoftonline.com',
-    'login.microsoftonline.us',
+    AZURE_US_GOVERNMENT,
     'login.microsoftonline.de',
     ])
 WELL_KNOWN_B2C_HOSTS = [
@@ -30,6 +37,19 @@
     ]
 
 
+class AuthorityBuilder(object):
+    def __init__(self, instance, tenant):
+        """A helper to save caller from doing string concatenation.
+
+        Usage is documented in :func:`application.ClientApplication.__init__`.
+        """
+        self._instance = instance.rstrip("/")
+        self._tenant = tenant.strip("/")
+
+    def __str__(self):
+        return "https://{}/{}".format(self._instance, self._tenant)
+
+
 class Authority(object):
     """This class represents an (already-validated) authority.
 
@@ -53,6 +73,8 @@ def __init__(self, authority_url, http_client, validate_authority=True):
             performed.
         """
         self._http_client = http_client
+        if isinstance(authority_url, AuthorityBuilder):
+            authority_url = str(authority_url)
         authority, self.instance, tenant = canonicalize(authority_url)
         parts = authority.path.split('/')
         is_b2c = any(self.instance.endswith("." + d) for d in WELL_KNOWN_B2C_HOSTS) or (

tests/http_client.py

@@ -20,6 +20,9 @@ def get(self, url, params=None, headers=None, **kwargs):
         return MinimalResponse(requests_resp=self.session.get(
             url, params=params, headers=headers, timeout=self.timeout))
 
+    def close(self):  # Not required, but we use it to avoid a warning in unit test
+        self.session.close()
+
 
 class MinimalResponse(object):  # Not for production use
     def __init__(self, requests_resp=None, status_code=None, text=None):

tests/test_authority.py

@@ -8,16 +8,37 @@
 @unittest.skipIf(os.getenv("TRAVIS_TAG"), "Skip network io during tagged release")
 class TestAuthority(unittest.TestCase):
 
+    def _test_given_host_and_tenant(self, host, tenant):
+        c = MinimalHttpClient()
+        a = Authority('https://{}/{}'.format(host, tenant), c)
+        self.assertEqual(
+            a.authorization_endpoint,
+            'https://{}/{}/oauth2/v2.0/authorize'.format(host, tenant))
+        self.assertEqual(
+            a.token_endpoint,
+            'https://{}/{}/oauth2/v2.0/token'.format(host, tenant))
+        c.close()
+
+    def _test_authority_builder(self, host, tenant):
+        c = MinimalHttpClient()
+        a = Authority(AuthorityBuilder(host, tenant), c)
+        self.assertEqual(
+            a.authorization_endpoint,
+            'https://{}/{}/oauth2/v2.0/authorize'.format(host, tenant))
+        self.assertEqual(
+            a.token_endpoint,
+            'https://{}/{}/oauth2/v2.0/token'.format(host, tenant))
+        c.close()
+
     def test_wellknown_host_and_tenant(self):
         # Assert all well known authority hosts are using their own "common" tenant
         for host in WELL_KNOWN_AUTHORITY_HOSTS:
-            a = Authority(
-                'https://{}/common'.format(host), MinimalHttpClient())
-            self.assertEqual(
-                a.authorization_endpoint,
-                'https://%s/common/oauth2/v2.0/authorize' % host)
-            self.assertEqual(
-                a.token_endpoint, 'https://%s/common/oauth2/v2.0/token' % host)
+            self._test_given_host_and_tenant(host, "common")
+
+    def test_wellknown_host_and_tenant_using_new_authority_builder(self):
+        self._test_authority_builder(AZURE_PUBLIC, "consumers")
+        self._test_authority_builder(AZURE_CHINA, "organizations")
+        self._test_authority_builder(AZURE_US_GOVERNMENT, "common")
 
     @unittest.skip("As of Jan 2017, the server no longer returns V1 endpoint")
     def test_lessknown_host_will_return_a_set_of_v1_endpoints(self):