Agent Authorization Flow
This document describes the complete Agent Operation Authorization (AOA) protocol flow, including all six phases from user authentication to tool execution.
Source: Extracted from
Agent.javainterface Javadoc to keep the interface concise while preserving the detailed protocol documentation.
Phase 1: User Authentication
┌─────────────────────────────────────────────────────────────────────────────┐
│ Phase 1: User Authentication │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐
│ User │ │ User's Agent │ │ Agent Actor │ │ Agent User IDP │
└────┬─────┘ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘
│ │ │ │
│ 1. User Input │ │ │
│────────────────────>│ │ │
│ ("Buy winter clothing advice") │ │
│ │ │ │
│ │ 2. initiateAuthorization (redirectUri, state) │
│ │────────────────────>│ │
│ │ │ │
│ │ 3. Return Auth URL │ │
│ │<────────────────────│ │
│ │ (Agent Actor builds auth URL locally) │
│ │ │ │
│ 4. Redirect to │ │ │
│<────────────────────│ │ │
│ Agent User IDP │ │ │
│ [USER ACTION] │ │ │
│ │ │ │
│ 5. User Login │ │ │
│────────────────────────────────────────────────────────────────────>│
│ (credentials) │ │ │
│ [USER ACTION] │ │ │
│ │ │ │
│ 6a. Redirect User Agent (with Auth Code) │ │
│<────────────────────────────────────────────────────────────────────│
│ [HTTP 302] │ │ │
│ 6b. Callback URL │ │ │
│────────────────────>│ │ │
│ (User Agent auto-access) │ │
│ │ │ │
│ │ 7. exchangeCodeForToken (code, state) │
│ │────────────────────>│ │
│ │ │ │
│ │ │ 7a. Exchange Code for Token
│ │ │────────────────────────>│
│ │ │ 7b. Return ID Token │
│ │ │<────────────────────────│
│ │ 8. Return ID Token │ │
│ │<────────────────────│ │
│ │ (to User's Agent backend) │
│ │ │ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
System Interactions
- User inputs prompt to User's Agent (e.g., "Buy winter clothing advice")
- User's Agent calls Agent Actor
initiateAuthorization()to get authorization URL - Agent Actor returns authorization URL to User's Agent
- User's Agent redirects user to Agent User IDP
- User logs in at Agent User IDP with credentials
- Agent User IDP returns authorization code via callback
- User's Agent calls Agent Actor
exchangeCodeForToken()with authorization code - Agent Actor exchanges code for ID Token and returns AuthenticationResponse
Phase 2: Workload Creation
┌─────────────────────────────────────────────────────────────────────────────┐
│ Phase 2: Workload Creation │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌─────────────┐
│ User's Agent │ │ Agent Actor │ │ Agent IDP │
└──────┬───────┘ └──────┬───────┘ └────────┬────┘
│ │ │
│ 1. createWorkload │ │
│────────────────────>│ │
│ │ │
│ │ 2. Create Workload │
│ │──────────────────────>│
│ │ (with user ID) │
│ │ │
│ │ 3. Return WIT │
│ │<──────────────────────│
│ │ (with agent_id) │
│ │ │
│ 4. Return │ │
│ WorkloadContext │ │
│<────────────────────│ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
System Interactions
- User's Agent calls Agent Actor
issueWorkloadIdentityToken() - Agent Actor creates workload via Agent IDP / WIMSE IDP
- Agent IDP returns WIT (with agent_id)
- Agent Actor returns WorkloadContext to User's Agent
Phase 3: OAuth Client Registration (DCR)
┌─────────────────────────────────────────────────────────────────────────────┐
│ Phase 3: OAuth Client Registration (DCR) │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ User's Agent │ │ Agent Actor │ │ Authorization Server │
└──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘
│ │ │
│ 1. registerOAuthClient │ │
│───────────────────────>│ │
│ │ │
│ │ 2. Register Client │
│ │────────────────────────>│
│ │ (with WIT as client_assertion)
│ │ │
│ │ 3. Validate WIT & Return client_id
│ │<────────────────────────│
│ │ │
│ │ │
│ 4. Return DcrResponse │ │
│<───────────────────────│ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
System Interactions
- User's Agent calls Agent Actor
registerOAuthClient() - Agent Actor registers OAuth client with Authorization Server using WIT as client_assertion
- Authorization Server validates WIT and returns DcrResponse with client_id (WIT.sub)
- Agent Actor returns DcrResponse to User's Agent
Phase 4: Authorization Request
┌─────────────────────────────────────────────────────────────────────────────┐
│ Phase 4: Authorization Request (PAR Flow) │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ User's Agent │ │ Agent Actor │ │ Authorization Server │
└──────┬───────┘ └──────┬───────┘ └──────────┬───────────┘
│ │ │
│ 1. submitParRequest │ │
│──────────────────────>│ │
│ │ │
│ │ 2. Submit PAR-JWT │
│ │─────────────────────────>│
│ │ (with WIT + Prompt VC) │
│ │ │
│ │ 3. Validate & Return │
│ │<─────────────────────────│
│ │ request_uri │
│ │ │
│ 4. Return ParResponse │ │
│<──────────────────────│ │
│ │ │
│ 5. generateAuthUrl │ │
│──────────────────────>│ │
│ │ │
│ 6. Return Auth URL │ │
│<──────────────────────│ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
System Interactions
- User's Agent calls Agent Actor
submitParRequest() - Agent Actor submits PAR-JWT to Authorization Server (with WIT + Prompt VC)
- Authorization Server validates and returns request_uri
- Agent Actor returns ParResponse to User's Agent
- User's Agent calls Agent Actor
generateAuthorizationUrl() - Agent Actor returns authorization URL
Phase 5: User Authorization
┌─────────────────────────────────────────────────────────────────────────────┐
│ Phase 5: User Authorization (OAuth 2.0 Flow) │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────────┐ ┌──────────────────────┐ ┌──────────────┐
│ User │ │ User's Agent │ │ Authorization Server │ │ AS User IDP │
└────┬─────┘ └──────┬───────┘ └────────┬─────────────┘ └────────┬─────┘
│ │ │ │
│ 1. Redirect │ │ │
│<───────────────────│ │ │
│ (to Auth URL) │ │ │
│ [USER ACTION] │ │ │
│ │ │ │
│ 2. User Visits │ │ │
│─────────────────────────────────────────>│ │
│ Authz Server │ │ │
│ [USER ACTION] │ │ │
│ │ │ │
│ │ │ 3. Authenticate User │
│ │ │─────────────────────────>│
│ │ │ │
│ │ │ 4. Return ID Token │
│ │ │<─────────────────────────│
│ │ │ │
│ 5. User Grants │ │ │
│─────────────────────────────────────────>│ │
│ Authorization │ │ │
│ [USER ACTION] │ │ │
│ │ │ │
│ │ │ 6. Callback to Agent │
│ │<────────────────────│ │
│ │ (with auth code) │ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
System Interactions
- User's Agent redirects user to authorization URL
- User visits Authorization Server
- Authorization Server authenticates user via AS User IDP
- AS User IDP returns ID Token
- User grants authorization at Authorization Server
- Authorization Server sends callback with authorization code to User's Agent
Phase 6: Token Exchange & Tool Execution
┌─────────────────────────────────────────────────────────────────────────────┐
│ Phase 6: Token Exchange & Tool Execution │
└─────────────────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────┐ ┌──────────────────────┐
│ User's Agent │ │ Agent Actor │ │ Authorization Server │
└──────┬───────┘ └──────┬───────┘ └────────┬─────────────┘
│ │ │
│ 1. handleCallback │ │
│────────────────────>│ │
│ │ │
│ │ 2. Exchange Code for AOAT │
│ │──────────────────────────>│
│ │ │
│ │ │
│ │ 3. Return AOAT │
│ │<──────────────────────────│
│ │ │
│ 4. executeTool │ │
│────────────────────>│ │
│ │ │
│ 5. Return Result │ │
│<────────────────────│ │
│ │ │
│ 6. clearContext │ │
│────────────────────>│ │1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
System Interactions
- User's Agent calls Agent Actor
handleAuthorizationCallback() - Agent Actor exchanges authorization code for AOAT with Authorization Server
- Authorization Server returns AOAT
- User's Agent calls Agent Actor
prepareAuthorizationContext() - User's Agent uses authorization context to execute tools via protocol adapters
- User's Agent calls Agent Actor
clearAuthorizationContext()