🔐 OAuth 2.0 Overview: Introduction to Standards Protocol Flows and Integration with Keycloak

OAuth 2.0 is the gold standard for delegated authorization. It provides multiple flows to suit different application types and trust levels. This guide dives deep into:

• Recap the AuthN and AuthZ

• OAuth 2.0 Flows: Client Credentials, Authorization Code, and Authorization Code with PKCE

• Client types: Confidential and Public

• Sequence diagrams for each flow (compatible with https://www.websequencediagram.com)

• Keycloak configuration examples for each flow

• curl commands to request tokens from Keycloak

• Security concerns, best practices, and when to use what

🔐 What is Authentication and Authorization?

Concept	Meaning	Example
Authentication	Verifying who you are.	Logging in with username/password, or Google login to prove your identity.
Authorization	Verifying what you can do or access after authentication.	Can this user access /admin page or update a record after logging in?

---

🧭 Purpose and Use

Aspect	Authentication	Authorization
Goal	Prove identity	Control access to resources
Happens when?	First step	After authentication
Protocol Examples	OpenID Connect (on top of OAuth 2)	OAuth 2.0 (Authorization Framework)
Who uses the data?	Login system (e.g., Keycloak)	Backend/API/gateway with access policies
Typical Data	Username, password, biometrics	Roles, permissions, scopes

---

🛠️ Which Protocol Does What?

Flow or Protocol	Used For	Handles Authentication?	Handles Authorization?
OAuth 2.0	Delegated access	❌ No	✅ Yes
OpenID Connect (OIDC)	Identity layer on OAuth	✅ Yes (who the user is)	✅ Sometimes (via scopes/claims)
SAML	Enterprise SSO	✅ Yes	✅ Yes
Basic Auth / Form Login	Simple login systems	✅ Yes	❌ No

---

🔑 In OAuth 2.0 Context

• Authentication: Usually handled by OIDC or a login form in the Identity Provider (IdP) like Keycloak.

• Authorization: Managed through OAuth 2.0 scopes, roles, or resource server policies.

📘 1. What is an OAuth Client?

An OAuth client is an application requesting access to protected resources on a user's behalf or on its own behalf.

---

🛠️ 2. Client Types: Confidential vs Public

Type	Can Store Secrets?	Typical Examples
Confidential	Yes	Server-side apps, CLIs
Public	No	Mobile apps, SPAs

---

✅ 3. Client Credentials Flow (Confidential Client)

Use Case: Service-to-service or machine-to-machine communication (no end-user).

🧾 Sequence Diagram

title Client Credentials Flow (Confidential Client)

Client->Auth Server: POST /token\nclient_id + client_secret\ngrant_type=client_credentials
Auth Server->Client: 200 OK\naccess_token
Client->Resource Server: GET /protected-resource\nAuthorization: Bearer access_token
Resource Server->Client: 200 OK\nprotected data

🔧 Keycloak Setup

1. Go to Clients → Create a new client

2. Client ID: my-service-client

3. Client Type: Confidential

4. Enable Service Accounts Enabled

5. Set credentials and copy client_id & client_secret

6. Assign appropriate client roles under Service Account Roles

7. Token Endpoint: https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token

curl -X POST \

  https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "grant_type=client_credentials" \

  -d "client_id=my-service-client" \

  -d "client_secret=YOUR_CLIENT_SECRET"

---

🙋‍♂️ 4. Authorization Code Flow (Confidential Client)

Use Case: Web applications with backend able to keep secrets. Requires user login.

🧾 Sequence Diagram

title Authorization Code Flow (Confidential Client)

Client->User: Redirect to Auth Server login

User->Auth Server: Logs in, grants consent
Auth Server->Client: Redirect with code
Client->Auth Server: POST /token\ncode + client_id + client_secret
Auth Server->Client: 200 OK\naccess_token + refresh_token
Client->Resource Server: GET /protected-resource\nAuthorization: Bearer access_token
Resource Server->Client: 200 OK\nprotected data

🔧 Keycloak Setup

1. Go to Clients → Create a new client

2. Client ID: my-web-client

3. Client Type: Confidential

4. Root URL: https://your-app.com

5. Valid Redirect URIs: https://your-app.com/callback

6. Enable Standard Flow Enabled

7. Note the token endpoint: https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token

curl -X POST \

  https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "grant_type=authorization_code" \

  -d "client_id=my-web-client" \

  -d "client_secret=YOUR_CLIENT_SECRET" \

  -d "code=AUTH_CODE_FROM_CALLBACK" \

  -d "redirect_uri=https://your-app.com/callback"

---

📱 5. Authorization Code Flow with PKCE (Public Client)

Use Case: Mobile apps or SPAs where secrets cannot be stored securely.

🧾 Sequence Diagram

title Authorization Code Flow with PKCE (Public Client)

Client->Auth Server: Redirect with\ncode_challenge (PKCE)
User->Auth Server: Logs in, grants consent
Auth Server->Client: Redirect with code
Client->Auth Server: POST /token\ncode + code_verifier (PKCE)
Auth Server->Client: 200 OK\naccess_token
Client->Resource Server: GET /protected-resource\nAuthorization: Bearer access_token
Resource Server->Client: 200 OK\nprotected data

🔧 Keycloak Setup

1. Go to Clients → Create a new client

2. Client ID: my-spa-client

3. Client Type: Public

4. Enable Standard Flow Enabled

5. Set Valid Redirect URIs (e.g. http://localhost:3000/*)

6. Enable PKCE (enabled by default from Keycloak 18+)

7. Do not set client secret (public clients should not use one)

curl -X POST \

  https://<keycloak-host>/realms/<realm>/protocol/openid-connect/token \

  -H "Content-Type: application/x-www-form-urlencoded" \

  -d "grant_type=authorization_code" \

  -d "client_id=my-spa-client" \

  -d "code=AUTH_CODE_FROM_CALLBACK" \

  -d "code_verifier=YOUR_CODE_VERIFIER" \

  -d "redirect_uri=http://localhost:3000/callback"

---

🛡️ 6. Security Considerations

Risk	Applies To	Mitigation
Token theft	All flows	Use HTTPS, secure storage
Secret leakage	Confidential	Store secrets in vaults, env vars
Replay attacks	Public clients	Use PKCE with code_verifier
Authorization code leakage	All code flows	Use state param + PKCE
Refresh token misuse	All code flows	Issue only to confidential clients

---

🏆 7. Which Flow to Use When?

Flow	Client Type	User Involved	Use Case
Client Credentials	Confidential	No	M2M, background jobs, microservices
Authorization Code	Confidential	Yes	Web apps with secure backend
Auth Code + PKCE	Public	Yes	SPAs, mobile apps

---

📄 8. Summary Table

Flow	Requires Secret	Safe for Public	Refresh Token	PKCE Required
Client Credentials	Yes	No	No	No
Authorization Code	Yes	No	Yes	No
Auth Code + PKCE	No	Yes	Sometimes	Yes

---

🌟 9. Best Practices

• Always use PKCE for mobile/web public clients

• Use short-lived access tokens and rotating refresh tokens

• Validate state and nonce to prevent CSRF and replay

• Use scopes to enforce least privilege

---

🚀 10. Tools to Visualize Sequence Diagrams

All diagrams here are compatible with https://www.websequencediagram.com. Paste any of them to view and customize.

---

📍 Final Thoughts

Choosing the right OAuth flow depends on:

• Whether you're authenticating a user or a service

• Whether the client is trusted to hold secrets

• Whether the platform supports secure storage

Use this guide as a blueprint to implement secure OAuth 2.0 integrations confidently using Keycloak as your Identity Provider.