🔐 OAuth 2.0 User Guide
Complete setup and usage instructions
v26.2.0
walter75 Consulting
BC Cloud
Introduction
The walter75 - OAuth 2.0 extension provides a comprehensive OAuth 2.0 authentication framework for integrating Microsoft Dynamics 365 Business Central with external APIs and services.
🔐 Secure Authentication
Industry-standard OAuth 2.0 protocol
🔄 Automatic Token Refresh
Handles token expiration automatically
📊 Token Management
Track and manage access tokens centrally
🔗 Multi-Service Support
Configure multiple API connections
🛡️ Credential Security
Encrypted storage of sensitive data
Setup
📋 Prerequisites
Before using OAuth 2.0 authentication, you need:
API credentials from the external service (Client ID, Client Secret)
OAuth endpoints (Authorization URL, Token URL)
Required scopes/permissions
Creating an OAuth Application
1
Open OAuth Applications
Search for "OAuth Applications" in Business Central and click + New to create a new application
2
Configure Basic Settings
General Information:
Code : Unique identifier (e.g., "SENDCLOUD", "PRINTNODE")Description : Descriptive name (e.g., "SendCloud Shipping API")Active : Enable to activate the application
3
Configure OAuth Endpoints
Authentication Settings:
Authorization URL : OAuth authorization endpointhttps://api.example.com/oauth/authorizeToken URL : Token exchange endpointhttps://api.example.com/oauth/tokenScope : Required permissions (space-separated)read write shipping
4
Enter Credentials
Client Credentials:
Client ID : Application client identifierClient Secret : Secret key (stored encrypted)
⚠️ Security Note: The Client Secret is stored encrypted. Never share these credentials publicly.
5
Configure Grant Type
Select OAuth 2.0 flow:
Authorization Code : User-based authenticationClient Credentials : Service-to-service (recommended)Password : Username/password flowRefresh Token : Automatic refresh
6
Save and Test
Click OK to save the configuration
Use the "Request Token" action to test
If successful, an access token will be generated
Managing Access Tokens
🔑 Viewing Active Tokens
Open your OAuth Application Card
Navigate to Related → Access Tokens
View all generated tokens with their expiration times
Token Information Displayed:
Token ID : Unique identifierCreated At : When the token was issuedExpires At : Token expiration timestampStatus : Active, Expired, RevokedScopes : Granted permissions
Automatic Token Refresh
The system automatically refreshes tokens before they expire if:
✅ Refresh tokens are available
✅ The OAuth application is configured with "Refresh Token" grant type
✅ The API supports token refresh
Manual Token Refresh
1
Open OAuth Application
Navigate to the OAuth Application Card
2
Refresh Token
Click Actions → Refresh Token
3
Verify Success
The system will request a new token using the refresh token
Revoking Tokens
🚫 To invalidate a token:
Navigate to Related → Access Tokens
Select the token to revoke
Click Revoke Token
Confirm the action
Troubleshooting
❌ Invalid Client Credentials
Cause: Client ID or Secret is incorrect
Solution:
Verify credentials in API dashboard
Update OAuth Application
Check for extra spaces
⏰ Token Expired
Cause: Access token reached expiration
Solution:
System auto-refreshes normally
Manually refresh if needed
Verify refresh tokens enabled
🔒 Invalid Scope
Cause: Requested scopes not allowed
Solution:
Check API documentation
Request additional scopes
Update Scope field
🚫 Authorization Failed
Cause: Multiple possible issues
Solution:
Check OAuth Log
Verify URLs are correct
Test API externally
Checking OAuth Logs
📊 Detailed Troubleshooting
Search for "OAuth Log Entries"
Filter by your OAuth Application code
Review error messages and response codes
Use timestamps to correlate with failed requests
Best Practices
✅ Do
Use descriptive codes
Review unused tokens
Test after API updates
Keep secrets secure
Monitor expiration
❌ Don't
Share Client Secrets
Reuse applications
Ignore refresh failures
Disable error logging