Manual OIDC Configuration

This guide provides the technical details needed to configure a generic OIDC client or to implement the flow manually.

OAuth 2.1 Compliance

MC-ID implements OAuth 2.1 with OpenID Connect. This means:

• PKCE is mandatory - You must include code_challenge and code_challenge_method=S256 in authorization requests
• Only response_type=code - The implicit flow is not supported
• State parameter required - For CSRF protection

Caution

Authorization requests without PKCE will be rejected. See the Vanilla JS guide for a complete implementation example.

Discovery Endpoints

MC-ID provides standard discovery endpoints for automatic client configuration:

Endpoint	Path	Description
OpenID Configuration	/.well-known/openid-configuration	Standard OIDC discovery document.
OAuth Authorization Server	/.well-known/oauth-authorization-server	OAuth 2.0 AS metadata (RFC 8414).

Most OIDC libraries can auto-configure using just the issuer URL (https://mc-id.com).

Endpoints

If you are self-hosting MC-ID or configuring a client manually, use the following endpoints. Replace https://mc-id.com with your instance URL if self-hosting.

Endpoint	Path	Description
Issuer	https://mc-id.com	The OIDC Issuer URL.
Authorization	/api/auth/oauth2/authorize	URL to redirect users to for login.
Token	/api/auth/oauth2/token	URL to exchange code for tokens.
Userinfo	/api/auth/oauth2/userinfo	URL to fetch user claims.
JWKS	/api/auth/oauth2/jwks	URL to fetch public signing keys.

Scopes

MC-ID supports the following scopes:

Scope	Required	Description
openid	Yes	Required for OIDC. Returns the sub claim.
profile	Yes	Access to MC-ID account details (name, accounts).
email	No	Access to email address (email, email_verified).
connections	No	Access to linked accounts, e.g. Minecraft, Discord (connections).
offline_access	No	Enables refresh tokens for long-lived sessions.

Tip

The openid scope is automatically included if omitted. For refresh tokens, you must explicitly request offline_access.

Authorization Request Parameters

When redirecting users to the authorization endpoint, include these parameters:

Parameter	Description
client_id	Your application’s Client ID.
redirect_uri	Must exactly match a registered redirect URI.
response_type	Must be code.
scope	Space-separated list of scopes (must include openid).
state	Random string for CSRF protection.
code_challenge	Base64url-encoded SHA-256 hash of the code verifier.
code_challenge_method	Must be S256 (case-sensitive).

Token Request Parameters

When exchanging the authorization code for tokens:

Parameter	Description
grant_type	Must be authorization_code.
code	The authorization code from the callback.
redirect_uri	Must match the authorization request.
client_id	Your application’s Client ID.
client_secret	Your application’s Client Secret.
code_verifier	The original random string used to generate the code challenge.

User Info Response

The Userinfo endpoint returns claims based on the scopes you requested.

{
  "sub": "AaltJ3XUoyDQiqDVk865CILljZBXrjZz",
  "email": "user@example.com",
  "name": "Notch",
  "email_verified": true,
  "accounts": [
    {
      "uuid": "069a79f444e94726a5befca90e38aaf5",
      "primary": true,
      "username": "Notch"
    }
  ],
  "connections": [
    {
      "providerId": "discord",
      "accountId": "123456789012345678"
    }
  ]
}

Claims by Scope

Scope	Claims Returned
openid	sub
profile	name, accounts
email	email, email_verified
connections	connections