slack context: https://codercom.slack.com/archives/C014JH42DBJ/p1763983935459739

This is a feature request to add support for including the original values supplied in CODER_OIDC_SCOPES in the scopes parameter when submitting a token refresh request to Azure in order to solve a token refresh failure problem. This issue exists specifically in Azure due to Azure requiring the scopes parameter be included on refresh requests. The RFC states:

scope
OPTIONAL. The scope of the access request as described by
Section 3.3. The requested scope MUST NOT include any scope
not originally granted by the resource owner, and if omitted is
treated as equal to the scope originally granted by the
resource owner.

However Microsoft have advised:

Although the OAuth 2.0/OIDC specifications consider the scope to be optional, Azure AD enforces its use for custom APIs and refresh tokens. This enforcement is crucial because, without a scope, Azure AD cannot determine which resource or permissions to grant, leading to errors such as AADSTS90009 (missing resource identifier) during refresh token requests.

For custom APIs, you must expose an API and define delegated or application permissions. When requesting tokens, use the .default scope (e.g., api:///.default). This is the only way Azure AD identifies the resource the token pertains to. The refresh token flow in Azure AD requires the resource context, and omitting the scope prevents the platform from inferring which API permissions apply. This is a deliberate design choice to enhance security and manage multi-resource scenarios.

Azure AD does not support refresh token requests without a scope for custom APIs. Despite the RFC treating the scope as optional, Azure AD mandates it for clarity and security. The only exception is when using Microsoft-hosted resources, such as Graph, but even in these cases, using .default is recommended.

When authenticating to Coder with OIDC, specifically via Azure, i.e. following the guide at https://coder.com/docs/admin/users/oidc-auth/microsoft while specifying CODER_OIDC_SCOPES=offline_access,openid,email,profile and CODER_OIDC_IGNORE_USERINFO=false (the default value), a JSON response is received from Azure to coderd which is as follows:

{
    "token_type": "Bearer",
    "scope": "email openid profile",
    "expires_in": 4977,
    "ext_expires_in": 4977,
    "access_token": "<jwt-access-token>",
    "refresh_token": "<refresh-token>",
    "id_token": "<jwt-id-token>"
}

The access token has claims as follows:

{
  "aud": "00000003-0000-0000-c000-000000000000",
  "iss": "https://sts.windows.net/110f0c0f-cd76-4717-a6f8-4eea3d0f8109/",
....

These values correspond to the Azure graph service and not to the customer's Azure tenant. In Microsoft terminology this is considered a version 1 token. As a result of this the access_token can only be validated by Azure, which means it is unsuitable for use cases such as https://registry.coder.com/modules/coder/vault-jwt. When attempting to authenticate to Vault using this token Vault responds with:

{
    "errors": [
        "error validating token: error verifying token signature: failed to verify id token signature"
    ]
}

If Microsoft's guidance is followed and the 'Expose an API' option is used to create an API scope, and the scope is then added to the 'API permissions' list to be included on the token, the following changes can be made to Coder to request a token for the scope:

    - name: CODER_OIDC_SCOPES
      value: 'offline_access,openid,email,profile,api://<azure-tenant-guid>/<exposed-scope-name>'
    - name: CODER_OIDC_IGNORE_USERINFO
      value: "true"

The resulting response now includes a version 2 token with the scope corresponding to the requested value in CODER_OIDC_SCOPES:

{
    "token_type": "Bearer",
    "scope": "<azure-tenant-guid>/<exposed-scope-name>",
    "expires_in": 4923,
    "ext_expires_in": 4923,
    "access_token": "<jwt-access-token>",
    "refresh_token": "<refresh-token>",
    "id_token": "<id-token>"
}

The access_token field is now populated with an audience value corresponding to the Azure app registration used for OIDC and the issuer now reflects the customer's Azure tenant:

{
  "aud": "<azure-app-registration-guid>",
  "iss": "https://login.microsoftonline.com/<azure-tenant-guid>/v2.0",
...

This token is then able to be used for authenticating to Vault, or other services which may consume a JWT and validate it against the customer's Azure tenant.

In the background coderd will as required attempt to perform a refresh of the OIDC access token using the following request body:

grant_type: refresh_token
refresh_token: 
  <refresh-token>

This however will fail with an HTTP 400 response:

{
    "error": "invalid_request",
    "error_description": "AADSTS90009: Application '<azure-app-registration-guid>'(<azure-app-registration-guid>) is requesting a token for itself. This scenario is supported only if resource is specified using the GUID based App Identifier. Trace ID: 35c6f182-34bb-4420-beaf-71aaa7c50700 Correlation ID: 6703e3f3-8c1b-4263-975c-5af44ed81c5e Timestamp: 2025-12-10 01:15:52Z",
    "error_codes": [
        90009
    ],
    "timestamp": "2025-12-10 01:15:52Z",
    "trace_id": "35c6f182-34bb-4420-beaf-71aaa7c50700",
    "correlation_id": "6703e3f3-8c1b-4263-975c-5af44ed81c5e"
}

As the scopes parameter is not included in the request the token refresh process fails and the customer is logged out of Coder and must reauthenticate. For the customer this issue is logged against they are logged out of Coder after 10 minutes.

Coder appears to use the x/oauth2 package to construct the refresh requests in https://github.com/coder/coder/blob/a59a84b2a789d46a96d0214e8923f1bcd3cc93d8/coderd/httpmw/oauth2.go, and per x/oauth2's oauth2.go refresh implementation it does not include the scopes parameter on the token refresh request.

An alternative approach was considered to capture the id_token from the initial Azure login response body and make it available for use (i.e. authenticate to Vault) as it would negate the requirement for using the 'Expose an API' function in Azure and does not result in the session timeout issue, however the idea was rejected due to security concerns and a desire to solve the issue using another method, potentially by supplying the scopes parameter on refresh requests.