Generate Sequence Diagrams for Azure B2C User Journeys with ChatGPT

Working with Azure B2C is an XML battle, especially when it comes to customizing user journeys using custom policies. A starter pack you can get from GitHub helps you set up your own policy.

Azure-Samples/active-directory-b2c-custom-policy-starterpack at dariuszparys.com (github.com)

The readme is comprehensive and has all the necessary information, but sometimes, it helps to have a flow sequence diagram. Sequence diagrams can be created using Mermaid, given a syntax that can be included in your Markdown documentation. The renderer will then visualize the sequences for you.

Generative AI can help here

There is an excellent way to do this with Generative AI. In my case, I use ChatGPT. The steps are as follows.

First, upload the XML policy files you want to analyze. In my example, I’m interested in the sign-in and sign-up user journey, so I’m only uploading TrustFrameworkBase.xml, TrustFrameworkExtensions.xml, and SignUpOrSignIn.xml.

Next, prompt ChatGPT to generate the sequence diagram based on the uploaded files. In the case I provide here, I used the following prompt:

Create a sequence diagram for the <User Journey Name> user journey in Azure AD B2C. The diagram should integrate the flow of claims directly into the main sequence and use notes and background colors to distinguish between different flows. 

### Sequence Diagram Details:
1. The initial request where the user opens the page and requests the policy.
2. The user decision point where they choose between different options (e.g., Sign Up or Sign In).
3. The detailed flow for each option, including:
    - Collecting claims
    - Validating and transforming claims
    - Interactions with Azure AD for validation and user data retrieval
    - Displaying success messages to the user
4. The token refresh flow if applicable.
5. Use notes to highlight claims collection and validation.
6. Use different background colors to distinguish between different options (e.g., Sign Up and Sign In).

Replace <User Journey Name> with the user journey I uploaded, in the example Sign In or Sign Up. The chatbot will start to analyze the files, and as a result, I get back this Mermaid sequence diagram.

sequenceDiagram
    participant User
    participant Browser
    participant AzureAD_B2C as Azure AD B2C
    participant IDP as Identity Provider
    participant App as Relying Party Application

    Note over User, Browser: Step 1: Access Sign Up or Sign In page
    User->>Browser: Access Sign Up/Sign In Page
    Browser->>AzureAD_B2C: Request Sign Up/Sign In Page
    AzureAD_B2C->>Browser: Return Sign Up/Sign In Page

    Note over User, Browser: Step 2: Enter credentials or select IDP
    User->>Browser: Enter credentials/select IDP
    Browser->>AzureAD_B2C: Submit credentials/IDP selection

    alt Local Account
        AzureAD_B2C->>AzureAD_B2C: Validate credentials
        AzureAD_B2C->>Browser: Prompt for additional claims (if needed)
        Browser->>User: Display additional claims form
        User->>Browser: Submit additional claims
        Browser->>AzureAD_B2C: Submit additional claims
    else Social IDP
        AzureAD_B2C->>IDP: Redirect to IDP
        IDP->>User: Display IDP login page
        User->>IDP: Enter credentials
        IDP->>AzureAD_B2C: Return user claims
    end

    Note over AzureAD_B2C: Step 4: Process user claims
    AzureAD_B2C->>AzureAD_B2C: Validate and transform claims
    AzureAD_B2C->>App: Send claims to relying party application

    Note over App, User: Step 5: User is authenticated
    App->>User: Welcome Page or Application Landing Page

You can look at the result in GitHub, which supports rendering Mermaid diagrams.

Rendered sequence diagram for Sign In or Sign Up user journey

https://gist.github.com/dariuszparys/904d64978f9448f23bfb7698fee0cf6a

As with all generative models, the output may vary depending on how you prompt it and what model you use. It is more about the basic idea that we can transform one format to another, which helps us create documentation we don’t have out of the box. Give it a try.

Originally published at https://www.dariuszparys.com on July 31, 2024.