Authentication

This document outlines the authentication mechanisms used within the MS Docs Core system. Securely verifying the identity of users and services is paramount to protecting sensitive data and ensuring proper access control.

Supported Authentication Methods

MS Docs Core supports several robust authentication methods to cater to different use cases:

1. API Key Authentication

API keys provide a simple and effective way to authenticate programmatic access to the core services. Each authenticated application or service is issued a unique API key.

• How it works: Include your API key in the X-API-Key header of your requests.
• Example Request Header:

GET /api/v1/resource HTTP/1.1
Host: api.msdocscore.com
X-API-Key: YOUR_SECRET_API_KEY
Content-Type: application/json

You can obtain and manage your API keys through the API Key Management portal.

2. OAuth 2.0 / OpenID Connect (OIDC)

For user-centric authentication and authorization, MS Docs Core integrates with standard OAuth 2.0 and OpenID Connect flows. This is ideal for web applications and single sign-on (SSO) scenarios.

We support the following OAuth 2.0 grant types:

• Authorization Code Grant
• Client Credentials Grant

Detailed guides on integrating OAuth 2.0 and OIDC can be found in the OAuth 2.0 & OIDC Guide.

3. JWT (JSON Web Token) Authentication

For internal service-to-service communication or after an initial authentication flow, JWTs are used to maintain authenticated sessions. Tokens are signed using RS256.

• Token Location: The JWT should be included in the Authorization header as a Bearer token.
• Example Request Header:

GET /api/v1/secure/data HTTP/1.1
Host: api.msdocscore.com
Authorization: Bearer YOUR_JWT_TOKEN
Content-Type: application/json

The structure of the JWT payload includes standard claims like iss, sub, aud, exp, and custom claims related to user roles and permissions.

Authentication Endpoints

The following endpoints are crucial for managing authentication:

Endpoint	Method	Description	Authentication
/auth/login	POST	Initiates the authentication process (e.g., for username/password or OAuth redirect).	None (for initial login) / API Key (for programmatic login)
/auth/refresh	POST	Refreshes an expired JWT.	Valid JWT required.
/auth/validate	GET	Validates the authenticity and expiration of a provided JWT.	Valid JWT required.
/oauth/authorize	GET	OAuth 2.0 authorization endpoint.	Session-based or API Key.
/oauth/token	POST	OAuth 2.0 token endpoint.	Client credentials or Authorization Code.

Best Practices

• HTTPS: Always use HTTPS for all communication to encrypt credentials and tokens in transit.
• Token Expiration: Implement mechanisms to handle token expiration and renewal gracefully.
• Rate Limiting: Be mindful of API rate limits to prevent denial-of-service attacks and ensure fair usage.
• Least Privilege: Grant only the necessary permissions to authenticated users and services.