Add ExternalIDClaim option for OAuth2 OIDC auth source (#37229)

This PR adds an External ID Claim Name configuration field to the OIDC
auth source. When set, Gitea uses the specified JWT claim as the user's
`ExternalID` instead of the default `sub` claim.

This PR fixes the bug when migrating from Azure AD V2 to OIDC. When an
admin migrates the same auth source to OIDC, goth's `openidConnect`
provider defaults to using the `sub` claim as `UserID`. However, Azure
AD's `sub` is a pairwise identifier:

> `sub`: The subject is a pairwise identifier and is unique to an
application ID. If a single user signs into two different apps using two
different client IDs, those apps receive two different values for the
subject claim.


https://learn.microsoft.com/en-us/entra/identity-platform/id-token-claims-reference#payload-claims

As a result, every existing user appears as a new account after
migration.

To fix this issue, Gitea should use `oid` claim for `UserID`.

> `oid`: This ID uniquely identifies the user across applications - two
different applications signing in the same user receives the same value
in the oid claim.

Note: The `oid` claim is not included in Azure AD tokens by default. The
`profile` scope must be added to the Scopes field of the auth source.

services/auth/source/oauth2/providers_openid.go

@@ -46,8 +46,14 @@ func (o *OpenIDProvider) CreateGothProvider(providerName, callbackURL string, so
 	provider, err := openidConnect.New(source.ClientID, source.ClientSecret, callbackURL, source.OpenIDConnectAutoDiscoveryURL, scopes...)
 	if err != nil {
 		log.Warn("Failed to create OpenID Connect Provider with name '%s' with url '%s': %v", providerName, source.OpenIDConnectAutoDiscoveryURL, err)
+		return nil, err
 	}
-	return provider, err
+	if source.ExternalIDClaim != "" {
+		// UserIdClaims is a fallback list; goth returns the first non-empty matching claim.
+		// A single entry is sufficient because the admin explicitly chooses one claim (e.g. "oid" for Azure AD).
+		provider.UserIdClaims = []string{source.ExternalIDClaim}
+	}
+	return provider, nil
 }
 
 // CustomURLSettings returns the custom url settings for this provider

services/auth/source/oauth2/source.go

@@ -30,6 +30,7 @@ type Source struct {
 
 	SSHPublicKeyClaimName string
 	FullNameClaimName     string
+	ExternalIDClaim       string
 }
 
 // FromDB fills up an OAuth2Config from serialized format.

services/forms/auth_form.go

@@ -88,6 +88,7 @@ type AuthenticationForm struct {
 	Oauth2GroupTeamMapRemoval     bool
 	Oauth2SSHPublicKeyClaimName   string
 	Oauth2FullNameClaimName       string
+	OpenIDConnectExternalIDClaim  string
 
 	// SSPI
 	SSPIAutoCreateUsers      bool