Add diagrams

docs/design/auth.md

@@ -14,13 +14,17 @@ Configuration is done with the user being authenticated via a time-limited, GitH
 
 *Your credentials are never used for registering the runner with the service.*
 
+![Self-hosted runner config](../res/self-hosted-config.png)
+
 During configuration, an RSA public/private key pair is created, the private key is stored in file on disk. On Windows, the content is protected with DPAPI (machine level encrypted - runner only valid on that machine) and on Linux/OSX with chmod permissions.
 
 Using your credentials, the runner is registered with the service by sending the public key to the service which adds that runner to the pool and stores the public key, STS will generate clientId associated with the public key.
 
 ## Start and Listen
 
-After configuring the runner, the runner can be started interactively (./run.cmd or ./run.sh) or as a service.
+After configuring the runner, the runner can be started interactively (`./run.cmd` or `./run.sh`) or as a service.
+
+![Self-hosted runner start](../res/self-hosted-start.png)
 
 On start, the runner listener process loads the RSA private key (on windows decrypting with machine key DPAPI), sends a JWT token which signed by the private key to the service.
 The server response with an OAuth token that grants permission to access the message queue (HTTP long poll), allowing the runner to acquire the messages it will eventually run.
@@ -31,6 +35,8 @@ When a workflow is run, its labels are evaluated, it is matched to a runner and
 The runner is listening for jobs via the message queue HTTP long poll.  
 The message is encrypted with the runner's public key, stored during runner configuration.  
 
+![Runner workflow run](../res/workflow-run.png)
+
 A workflow is queued as a result of a triggered [event](https://help.github.com/en/actions/reference/events-that-trigger-workflows). Workflows can be scheduled to [run at specific UTC times](https://help.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events-schedule) using POSIX `cron` syntax.
 A [JWT token](http://self-issued.info/docs/draft-ietf-oauth-json-web-token.html) is generated, granting limited access to the host in Actions Service associated with the github.com repository/organization.
 The lifetime of the JWT token is the lifetime of the run or at most the [job timeout (default: 6 hours)](https://help.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idtimeout-minutes), plus 10 additional minutes.
@@ -45,8 +51,10 @@ Each action is run as a unique subprocess.
 The encrypted access token will be provided as an environment variable in each action subprocess.  
 The token is registered with the runner as a secret and scrubbed from the logs as they are written.
 
-Authentication in a workflow run to github.com can be accomplished by using the [GITHUB_TOKEN](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#about-the-github_token-secret)) secret. This token expires after 60 minutes. Please note that this token is different from the JWT token that the runner uses to talk to the Actions Service.
+Authentication in a workflow run to github.com can be accomplished by using the [`GITHUB_TOKEN`](https://help.github.com/en/actions/configuring-and-managing-workflows/authenticating-with-the-github_token#about-the-github_token-secret)) secret. This token expires after 60 minutes. Please note that this token is different from the JWT token that the runner uses to talk to the Actions Service.
 
 ## Hosted runner authentication
 
-Hosted runner authentication differs from self-hosted authentication in that runners do not undergo a registration process, but instead, they get a 'limited scope token' at runtime to talk back to the Actions Service. The scope is limited for a given workflow job execution, and the token is revoked as soon as the job is finished. This is an implementation detail that workflow authors do not have to worry about when authoring/running workflows.
+Hosted runner authentication differs from self-hosted authentication in that runners do not undergo a registration process, but instead, they get a 'limited scope token' at runtime to talk back to the Actions Service. The scope is limited for a given workflow job execution, and the token is revoked as soon as the job is finished. This is an implementation detail that workflow authors do not have to worry about when authoring/running workflows.
+
+![Hosted runner config and start](../res/hosted-config-start.png)

docs/res/runner-auth-diags.txt

@@ -0,0 +1,49 @@
+# Markup used to generate the runner auth diagrams: https://websequencediagrams.com
+
+title Runner Configuration (self-hosted only)
+
+note left of Runner: Generate RSA key pair
+note left of Runner: Store encrypted RSA private key on disk
+Runner->Actions Service: Register runner (requires GitHub registration token)
+note right of Runner: GitHub repo URL, runner name, RSA public key sent
+note right of Actions Service: Public key stored
+Actions Service->Token Service: Register runner as an application along with the RSA Public Key
+note right of Token Service: Public key stored
+Token Service->Actions Service: Client Id for the runner application
+Actions Service->Runner: Client Id and Token Endpoint URL
+note left of Runner: Store runner configuration info into .runner file
+note left of Runner: Store Token registration info into .credentials file
+
+title Runner Start and Running (self-hosted only)
+
+Runner.Listener->Runner.Listener: Start
+note left of Runner.Listener: Load config info from .runner
+note left of Runner.Listener: Load token registration from .credentials
+Runner.Listener->Token Service: Exchange OAuth token (happens every 50 mins)
+note right of Runner.Listener: Construct JWT token, use Client Id signed by RSA private key
+note left of Actions Service: Find corresponding RSA public key, use Client Id\nVerify JWT token's signature
+Token Service->Runner.Listener: OAuth token with limited permission and valid for 50 mins
+Runner.Listener->Actions Service: Connect to Actions Service with OAuth token
+Actions Service->Runner.Listener: Workflow job
+
+title Running workflow
+
+Runner.Listener->Service (Message Queue): Get message
+note right of Runner.Listener: Authenticate with exchanged OAuth token
+Event->Actions Service: Queue workflow
+Actions Service->Actions Service: Generate JWT token per job
+Actions Service->Actions Service: Build job message with the JWT token
+Actions Service->Actions Service: Encrypt job message with the target runner's public key
+Actions Service->Service (Message Queue): Send encrypted job message to runner
+Service (Message Queue)->Runner.Listener: Send job
+note right of Runner.Listener: Decrypt message with runner's private key
+Runner.Listener->Runner.Worker: Create worker process per job and run the job
+
+title Runner Configuration, Start and Running (hosted only)
+
+Machine Management Service->Runner.Listener: Construct .runner configuration file, store token in .credentials
+Runner.Listener->Runner.Listener: Start
+note left of Runner.Listener: Load config info from .runner
+note left of Runner.Listener: Load token from .credentials
+Runner.Listener->Actions Service: Connect to Actions Service with token in .credentials
+Actions Service->Runner.Listener: Workflow job