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.

Related Topics

• SharePoint – App‑Only OAuth Flow
• SharePoint – Add‑in Registration
• OAuth 2.0 – Concepts & Terminology
• JWT – Structure & Validation

References

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