Feat: Access Token with Multiple Domain Supported for Full Token Exchange

docs/zts_access_token_guide.md

@@ -1,6 +1,6 @@
 Access Tokens are used to authorize access to service provider resources.
 The Access Token contains the set of roles (identified in the token as
-scopes) a client belongs to for a specified domain. So, when a client wants
+scopes) a client belongs to for one or more specified domains. So, when a client wants
 to access a resource, this client
 must obtain the appropriate Access Token from ZTS and use the token in the
 header of the subsequent HTTP client request. If enabled, the service will
@@ -22,13 +22,16 @@ endpoint. The request body must contain the following parameters:
 grant_type : Value MUST be set to "client_credentials"
 scope : list of scopes/roles requested in the access token. The caller
         can either specify to include all roles the principal has access
-        to in a specific domain (e.g. <domain-name>:domain) or ask for
+        to in specific domains (e.g. <domain-name>:domain) or ask for
         specific roles only (e.g. <domain-name>:role.<role1>). Scopes
         are separated by spaces.
         To request an ID token, the scope must include 'openid' and audience
         service name (e.g. <domain-name>:service.<service-name>). The domain
-        name in id token request match the domain name in the access token
-        scope.
+        name in id token request must match the domain name in the access token
+        scope. ID token requests do not support multiple scope domains.
+audience : optional audience domain for the access token. This value is
+           required when the scope includes more than one domain. If specified,
+           it must be one of the domains in the requested scope.
 expires_in : requested expiry time for access token in seconds
 ```
 
@@ -44,16 +47,16 @@ Content-Type: application/x-www-form-urlencoded
 grant_type=client_credentials&scope=demo%3Adomain
 ```
 
-If the principal requests an access token only for accessing
-`demo` domain and wants to include `readers` and `writers` roles it has access
-to in that domain, the request would be:
+If the principal requests an access token for accessing `demo` and `sherpa`
+domains and wants to include `readers` and `writers` roles it has access to,
+the request would be:
 
 ```
 POST /zts/v1/oauth2/token HTTP/1.1
 Host: <zts-address>
 Content-Type: application/x-www-form-urlencoded
 
-grant_type=client_credentials&scope=demo%3Arole.readers+sherpa%3Arole.writers
+grant_type=client_credentials&audience=demo&scope=demo%3Arole.readers+sherpa%3Arole.writers
 ```
 
 If the principal requests an access token along with an id token for accessing
@@ -114,7 +117,10 @@ uid : unique identifier for the principal (same as client Id)
 sub : subject of the access token (same as client Id)
 iat : token issue time in seconds (Unix time)
 exp : token expiry time in seconds (Unix time)
-scp : array of scopes are granted to this access token. This is the list of roles that principal can assume in the audience domain
+scp : array of scopes granted to this access token. Roles in the audience domain
+      are listed by role name, while roles from other domains are listed as
+      <domain-name>:role.<role-name>. A simple role name always belongs to the
+      audience domain and cannot authorize a role with the same name in another domain.
 client_id : client ID (Athenz Principal) of the client that requested the access token
 ```
 

servers/zts/conf/zts.properties

@@ -760,6 +760,10 @@ athenz.zts.cert_signer_factory_class=com.yahoo.athenz.zts.cert.impl.SelfCertSign
 # respective roles or groups the principal is a member of.
 #athenz.zts.id_token_max_domains=10
 
+# When requesting access tokens, this value specifies the maximum number of
+# domains the scope can include. Default value is 1.
+#athenz.zts.access_token_max_domains=1
+
 # When requesting TLS certificates or role certificates on Google Cloud Platform (GCP)
 # services must use one of the values listed in
 # this dns suffix property in their CSRs (comma separated list)

servers/zts/src/main/java/com/yahoo/athenz/zts/ZTSConsts.java

@@ -96,6 +96,7 @@ public final class ZTSConsts {
     public static final String ZTS_PROP_ID_TOKEN_MAX_TIMEOUT       = "athenz.zts.id_token_max_timeout";
     public static final String ZTS_PROP_ID_TOKEN_DEFAULT_TIMEOUT   = "athenz.zts.id_token_default_timeout";
     public static final String ZTS_PROP_ID_TOKEN_MAX_DOMAINS       = "athenz.zts.id_token_max_domains";
+    public static final String ZTS_PROP_ACCESS_TOKEN_MAX_DOMAINS   = "athenz.zts.access_token_max_domains";
     public static final String ZTS_PROD_ID_TOKEN_ALLOWED_ROLES     = "athenz.zts.id_token_allowed_roles";
     public static final String ZTS_PROP_SIGNED_POLICY_TIMEOUT      = "athenz.zts.signed_policy_timeout";
     public static final String ZTS_PROP_AUTHORIZED_PROXY_USERS     = "athenz.zts.authorized_proxy_users";