SharePoint - Authorization Code Flow

The Authorization Code Flow is the standard OAuth 2.0 pattern used by SharePoint‑hosted and provider‑hosted add‑ins to securely obtain an access token on behalf of a user. It ensures that authentication occurs at SharePoint, while your application receives only short‑lived tokens — never the user’s credentials.

Context

SharePoint uses OAuth 2.0 to allow external applications to call SharePoint APIs securely. The Authorization Code Flow is used when:

A user interacts with the add‑in
The add‑in must act as that user
Permissions must be constrained to a specific Add‑in Registration
The app lives outside SharePoint (provider‑hosted)

This flow is not used for:

Daemon services
Background tasks
App-only access

Why This Flow Exists

The Authorization Code Flow ensures:

Secure user authentication performed by SharePoint
Add‑ins never handle user passwords
Token lifecycles are short, revocable, and auditable
Every request reflects a user's identity, site membership, and permissions
Administrators maintain control through Add‑in Permissions

Core Concepts

Authorization Code

A short-lived, single-use value returned by SharePoint after the user consents. The add‑in exchanges this code for:

access token
refresh token
expiration timestamps

Client ID & Client Secret

Generated via AppRegNew.aspx. These identify the add‑in to SharePoint.

Redirect URI

The address SharePoint sends the authorization code to. Must match exactly, use HTTPS in production.

Scope

SharePoint permissions declared in the add‑in manifest.

Authorization Code Flow Sequence

1. User Launches the Add‑in

User opens external application.

2. App Redirects User to SharePoint Authorization Endpoint

Includes client_id, scope, redirect_uri, state.

3. SharePoint Authenticates the User

Login prompt if not authenticated.

4. SharePoint Returns an Authorization Code

Redirects with code and state.

5. The Add‑in Exchanges the Code for Tokens

Back‑channel request returns access and refresh tokens.

6. Application Calls SharePoint Using the Access Token

Bearer token in Authorization header.

7. Refresh Token Rotation

Refresh token silently renews access tokens.

ASCII Diagram

User Browser -> SharePoint -> Add‑in Server (sequence flow)

Practical Application

Examples and scenarios where this flow applies.

Common Pitfalls

Redirect URI mismatch, code reuse, clock skew, wrong resource principal.

Security Considerations

Protect client secret, enforce HTTPS, rotate secrets.

Troubleshooting

Common errors and causes.

References

Microsoft Docs: Authorization Code OAuth Flow for SharePoint Add‑ins