Clarify documentation on impersonated token generation with service accounts

[sh41]

Thanks for your work on this, it is much appreciated. It took me quite a while to figure out how to do impersonation with a service account, so I've added a note to the documentation which will hopefully clarify things.

There are potential QoL changes that could be made to the code, but adding to the docs felt like the path of least resistance. If it's something you'd be interested in accepting a PR for, my pain points and suggested fixes would be:

• Confusion between top level option scopes and claims key scope. Suggested fixes:
  • (breaking change) rename top level option to scope
  • Accept both scopes and scope and deprecate scopes
  • Validate all options and claims keys and raise an error if an invalid key is passed.
• Confusion between top level scopes accepting a list of scopes, and claims/scope requiring a space separated string. Suggested fixes:
  • Gracefully handle passing of a list in claims/scope by performing Enum.join(scope, " ") for the user.
  • Raise an Error if claims/scope is not a string
• Confusion around config element actor_email which is still in the code, but was removed from the README.md. Suggested fixes:
  • Document usage
  • Deprecate usage
  • I couldn't find the term actor in Google's Documentation for this, the concept seems to variously be referred to as impersonation or subject depending on which documentation I read. actor_email could be renamed to be closer to the official docs.
• While trying to understand the interactions between top level options and claims I found it frustrating that I needed to switch from keyword list to map with string keys for claims each time. Suggested fixes:
  • Better docs should mostly negate this, so maybe no fix required.
  • Could Stringify the claims keys rather than reject them if they're not strings.
  • Could also handle a keyword list and raise if there are duplicate keys.