docs(jans-auth) : Case study - Stepped up authentication

[maduvena]

When a user is challenged to produce an additional authentication when a certain API is accessed by the client does not have the needed scope.

sequenceDiagram

title Stepped-up Authentication

actor Person
participant Browser
participant Website
participant Auth Server
participant API

autonumber

Website->>API: request some endpoint
API->>API:  Enforce<br> presence of <br> 'otp' scope<br> in  access_token
API->>Website: 3. 401 Unauthorized<br>WWW-Authenticate: Bearer error="insufficient_user_authentication" 
Website->>Browser: Enforce additional challenge on the user<br> (Enter OTP) 
Person->>Browser:Enter OTP
Browser->>Auth Server: /authorize endpoint
Auth Server->>Auth Server:Validate OTP (Person authentication script)
Auth Server->>Auth Server: Modify scope of AT to include OTP (Update token script)
Auth Server->> Website: Return Access Token with scope containing OTP