Skip to content

PROJQUAY-10283: update Entra OIDC server example #1626

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
JoeAldinger wants to merge 1 commit into
base: master
Choose a base branch
from
Open

PROJQUAY-10283: update Entra OIDC server example #1626

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions modules/configuring-oidc-authentication.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,20 +40,20 @@ AZURE_LOGIN_CONFIG: <1>
OIDC_SERVER: <oidc_server_address_> <4>
SERVICE_NAME: Microsoft Entra ID <5>
VERIFIED_EMAIL_CLAIM_NAME: <verified_email> <6>
USE_PKCE: True <7>
USE_PKCE: true <7>
PKCE_METHOD: "S256" <8>
PUBLIC_CLIENT: True <9>
PUBLIC_CLIENT: true <9>
# ...
----
<1> The parent key that holds the OIDC configuration settings. In this example, the parent key used is `AZURE_LOGIN_CONFIG`, however, the string `AZURE` can be replaced with any arbitrary string based on your specific needs, for example `ABC123`.However, the following strings are not accepted: `GOOGLE`, `GITHUB`. These strings are reserved for their respective identity platforms and require a specific `config.yaml` entry contingent upon when platform you are using.
<2> The client ID of the application that is being registered with the identity provider.
<3> The client secret of the application that is being registered with the identity provider.
<4> The address of the OIDC server that is being used for authentication. In this example, you must use `sts.windows.net` as the issuer identifier. Using `https://login.microsoftonline.com` results in the following error: `Could not create provider for AzureAD. Error: oidc: issuer did not match the issuer returned by provider, expected "https://login.microsoftonline.com/73f2e714-xxxx-xxxx-xxxx-dffe1df8a5d5" got "https://sts.windows.net/73f2e714-xxxx-xxxx-xxxx-dffe1df8a5d5/"`.
<4> The address of the OIDC server that is being used for authentication. For Microsoft Entra ID, you can typically use the v2 endpoint, for example `\https://login.microsoftonline.com/<tenant_id>/v2.0/`.

@LiZhang19817 LiZhang19817 May 8, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"typically" is vague — it either works or it doesn't.

The v2.0 endpoint returns an issuer of https://login.microsoftonline.com/<tenant_id>/v2.0 in its discovery document, which matches the OIDC_SERVER value. The v1 endpoint returns issuer https://sts.windows.net/<tenant_id>/ — a different domain. The code at oauth/oidc.py:237 reads the issuer from the discovery document and loginmanager.py:55 compares it with rstrip("/"). So v2.0 works because the issuer matches. This should be stated explicitly, not hedged with "typically."

No mention of OIDC_ISSUER fallback — The codebase has an OIDC_ISSUER override field (oauth/oidc.py:240) specifically designed for issuer mismatch scenarios. If a customer must use the v1 endpoint for some reason, they can set OIDC_ISSUER: https://sts.windows.net/<tenant_id>/. This is undocumented in both the old and new docs.

<5> The name of the service that is being authenticated.
<6> The name of the claim that is used to verify the email address of the user.
<7> Specifies whether to enable Proof Key for Code Exchange (PKCE) for OIDC authentication. Defaults to `False`.
<7> Specifies whether to enable Proof Key for Code Exchange (PKCE) for OIDC authentication. Defaults to `false`.
<8> Specifies the code challenge method used to generate the `code_challenge` sent in the initial authorization request. Defaults to `S256`.
<9> Specifies whether to omit `client_secret` during token request when the client is public. Defaults to `False`.
<9> Specifies whether to omit `client_secret` during token request when the client is public. Defaults to `false`.

. Proper configuration of Microsoft Entra ID results three redirects with the following format:
+
Expand Down
14 changes: 7 additions & 7 deletions modules/oidc-config-fields.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ You can configure {productname} to authenticate users through any OpenID Connect
| **{nbsp}{nbsp}{nbsp}.OIDC_SERVER** +
(Required) | String | The address of the OIDC server that is being used for authentication. +
+
**Example:** `\https://sts.windows.net/6c878.../`
**Example:** `\https://login.microsoftonline.com/<tenant_id>/v2.0/`
| **{nbsp}{nbsp}{nbsp}.PREFERRED_USERNAME_CLAIM_NAME** |String |Sets the preferred username to a parameter from the token.
| **{nbsp}{nbsp}{nbsp}.SERVICE_ICON** | String | Changes the icon on the login screen.

Expand All @@ -45,21 +45,21 @@ You can configure {productname} to authenticate users through any OpenID Connect

| **{nbsp}{nbsp}{nbsp}.PREFERRED_GROUP_CLAIM_NAME** | String | The key name within the OIDC token payload that holds information about the user's group memberships.

| **{nbsp}{nbsp}{nbsp}.OIDC_DISABLE_USER_ENDPOINT** | Boolean | Whether to allow or disable the `/userinfo` endpoint. If using Azure Entra ID, this field must be set to `True` because Azure obtains the user's information from the token instead of calling the `/userinfo` endpoint. +
| **{nbsp}{nbsp}{nbsp}.OIDC_DISABLE_USER_ENDPOINT** | Boolean | Whether to allow or disable the `/userinfo` endpoint. If using Azure Entra ID, this field must be set to `true` because Azure obtains the user's information from the token instead of calling the `/userinfo` endpoint. +
+
**Default:** `False`
**Default:** `false`

| *USE_PKCE* | Boolean | Whether to enable support for Proof Key for Code Exchange. +
+
**Default:** `False`
**Default:** `false`

|*PKCE_METHOD* |Integer | The code challenge method used to generate the `code_challenge` sent in the initial authorization request. +

@LiZhang19817 LiZhang19817 May 8, 2026 •
edited
Loading

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In oidc-config-fields.adoc, PKCE_METHOD is listed with type Integer. The codebase (oauth/oidc.py:147-152) shows:

    def pkce_method(self) -> str:                                                                                                                                    
                                                                                                                                                                     
        method = self.config.get("PKCE_METHOD", "S256")                                                                                                              
                                                                                                                                                                     
        allowed_methods = {"S256", "plain"}

It's a String, valid values are "S256" or "plain". The docs should also list "plain" as a valid option.

+
**Default:** `S256`

|*PUBLIC_CLIENT* |Boolean | Whether to omit `client_secret` during token request when the client is public. +
+
**Default:** `False`
**Default:** `false`
|===

.OIDC example YAML
Expand Down Expand Up @@ -90,8 +90,8 @@ AUTHENTICATION_TYPE: OIDC
VERIFIED_EMAIL_CLAIM_NAME: <verified_email_claim>
PREFERRED_GROUP_CLAIM_NAME: <preferred_group_claim>
OIDC_DISABLE_USER_ENDPOINT: true
USE_PKCE: True
USE_PKCE: true
PKCE_METHOD: "S256"
PUBLIC_CLIENT: True
PUBLIC_CLIENT: true
# ...
----
Loading