docs: use mermaid diagram in introduction (#869)

Azure · Apr 27, 2023 · 7460246 · 7460246
1 parent c8f7c69
commit 7460246
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 9 deletions.
diff --git a/docs/book/src/images/how-it-works-diagram.png b/docs/book/src/images/how-it-works-diagram.png
diff --git a/docs/book/src/images/oidc-issuer-sequence-diagram.png b/docs/book/src/images/oidc-issuer-sequence-diagram.png
diff --git a/docs/book/src/images/oidc-issuer-sequence-diagram.txt b/docs/book/src/images/oidc-issuer-sequence-diagram.txt
diff --git a/docs/book/src/installation/self-managed-clusters/oidc-issuer.md b/docs/book/src/installation/self-managed-clusters/oidc-issuer.md
@@ -11,6 +11,24 @@ In the case of self-managed clusters, administrator will have to manually publis
 
 ## Sequence Diagram
 
+<!-- source
+```mermaid
+sequenceDiagram
+    participant Kubernetes Workload
+    participant Azure Active Directory
+    participant OpenID Connect Issuer
+    Kubernetes Workload->>Azure Active Directory:Projected, signed service account token
+    Azure Active Directory->>Azure Active Directory:Extract the issuer URL from the token request
+    Azure Active Directory->>OpenID Connect Issuer:{IssuerURL}/.well-known/openid-configuration
+    OpenID Connect Issuer->>Azure Active Directory:Return the discovery document
+    Azure Active Directory->>Azure Active Directory:Extract the JWKS URL from the discovery document
+    Azure Active Directory->>OpenID Connect Issuer:{IssuerURL}/openid/v1/jwks
+    OpenID Connect Issuer->>Azure Active Directory:Return the JWKS document
+    Azure Active Directory->>Azure Active Directory:Validate the authenticity of the service account token
+    Kubernetes Workload->>Azure Active Directory:Return an AAD token
+```
+--->
+
 ![Sequence Diagram][3]
 
 [1]: ./oidc-issuer/discovery-document.md

diff --git a/docs/book/src/introduction.md b/docs/book/src/introduction.md
@@ -23,6 +23,22 @@ Azure AD Workload Identity for Kubernetes integrates with the capabilities nativ
 
 In this model, the Kubernetes cluster becomes a token issuer, issuing tokens to Kubernetes Service Accounts. These service account tokens can be configured to be trusted on Azure AD applications or user-assigned managed identities. Workload can exchange a service account token projected to its volume for an Azure AD access token using the Azure Identity SDKs or the Microsoft Authentication Library (MSAL).
 
+<!-- source
+```mermaid
+sequenceDiagram
+    participant Kubelet
+    participant Workload
+    participant Azure Active Directory
+    participant OpenID Discovery Document
+    participant Azure Resources
+    Kubelet->>Workload: Projects service account token <br> to the workload at a configurable <br> file path
+    Workload->>Azure Active Directory: Sends projected, signed <br> service account token and requests <br> Azure AD access token
+    Azure Active Directory->>OpenID Discovery Document: Checks trust on the identity <br> and validates incoming token
+    Azure Active Directory->>Workload: Issues Azure AD access token
+    Workload->>Azure Resources: Access resources using Azure AD access token
+```
+--->
+
 ![How it works][9]
 
 [1]: https://github.com/Azure/aad-pod-identity