docs: document Entra password login and prerequisites #1612
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -68,3 +68,4 @@ unmount | |
| vendorize | ||
| webview | ||
| whitespace | ||
| passwordless | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -102,7 +102,7 @@ Limited-Input Device Applications documentation](https://developers.google.com/i | |
| ::::{tab-item} Microsoft Entra ID | ||
| :sync: msentraid | ||
|
|
||
| Register a new application in the Microsoft Entra admin center. To register a | ||
| new application, select the menu {menuselection}`Entra ID --> App registrations`: | ||
|
|
||
|  | ||
|
|
@@ -129,10 +129,12 @@ Ensure the API permission type is set to **Delegated** for each permission. | |
| The {guilabel}`GroupMember.Read.All` permission needs admin consent. Click on | ||
| {guilabel}`Grant admin consent for <TENANT_NAME>` to provide this consent. | ||
|
|
||
| If you plan to use the [device code flow](#device-code-flow), you also need to allow public client | ||
| flows. In {menuselection}`Manage --> Authentication (Preview) --> Settings`, | ||
| ensure that {guilabel}`Allow public client flows` is set to **Enabled**. This | ||
| isn't required if only the Entra authentication flow is used, since it authenticates | ||
| through the Microsoft Broker App rather than through this application | ||
| registration. | ||
|
|
||
| [The Microsoft documentation](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app) | ||
| provides detailed instructions for registering an application with the Microsoft | ||
|
|
@@ -503,6 +505,70 @@ The authd-oidc broker does not support device registration. | |
| :::: | ||
| ::::: | ||
|
|
||
| (ref::config-auth-flows)= | ||
|
|
||
| ## Configure authentication flows | ||
|
|
||
| :::::{tab-set} | ||
| :sync-group: broker | ||
|
|
||
| ::::{tab-item} Google IAM | ||
| :sync: google | ||
|
|
||
| The Google IAM broker only supports the device code flow, where the user visits a URL | ||
| and enters a code to complete authentication. | ||
| :::: | ||
|
|
||
| ::::{tab-item} Microsoft Entra ID | ||
| :sync: msentraid | ||
|
|
||
| The `[flows]` section of the broker configuration file controls which | ||
| authentication flows are offered to the user at login. By default, both | ||
| Entra authentication and device code flow | ||
| (browser-based) are enabled. | ||
|
|
||
| ```ini | ||
| [flows] | ||
| ## Enable Entra authentication (default: true) | ||
| #entra_auth = true | ||
|
|
||
| ## Enable browser-based device code flow (default: true) | ||
| #device_code = true | ||
| ``` | ||
|
|
||
| ### Entra authentication flow | ||
|
|
||
| When `entra_auth` is enabled, the user can enter their Entra ID password | ||
| directly. After password verification, Microsoft Entra ID requires a second | ||
| factor (MFA). The broker automatically handles the MFA challenge: | ||
|
|
||
| - **Push notification or number matching**: The user approves a notification on | ||
| their registered authenticator app. | ||
| - **TOTP code**: The user enters a time-based one-time password from their | ||
| authenticator app. | ||
|
|
||
| ```{admonition} FIDO2/WebAuthn security key support | ||
| :class: note | ||
| FIDO2/WebAuthn security keys are currently not supported for the Entra authentication flow. | ||
| If only FIDO methods are registered, the user is prompted to switch to the device code flow | ||
| instead. | ||
| ``` | ||
|
Comment on lines
+541
to
+555
Contributor
There was a problem hiding this comment. At this point, it probably makes sense to also document the passwordless authentication here, and merge it after #1723 (which I expect to be merged soon anyway). WDYT?
Member
Author
There was a problem hiding this comment. That's fine with me, we can do it in a separate commit in this PR. The only blocker would be waiting for https://gitlab.com/samba-team/libhimmelblau/-/merge_requests/165 to be merged |
||
|
|
||
| ### Device code flow | ||
|
|
||
| When `device_code` is enabled, the user is presented with a device code and | ||
| a URL to visit in a browser to complete authentication. This is the standard | ||
| OAuth 2.0 Device Authorization Grant flow. | ||
| :::: | ||
|
|
||
| ::::{tab-item} Keycloak | ||
| :sync: keycloak | ||
|
|
||
| The authd-oidc broker only supports the device code flow, where the user visits a URL | ||
| and enters a code to complete authentication. | ||
| :::: | ||
| ::::: | ||
|
|
||
| ## Restart the broker | ||
|
|
||
| When a configuration file is added you have to restart authd: | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| --- | ||
| myst: | ||
| html_meta: | ||
| "description lang=en": "Authentication flows supported by authd brokers." | ||
| --- | ||
|
|
||
| # Authentication flows | ||
|
|
||
| An authentication flow is the sequence of steps a user goes through to verify | ||
| their identity at login. | ||
|
|
||
| ## Google IAM | ||
|
|
||
| Google IAM supports the **device code flow**, where the user visits a URL | ||
| and enters a code to complete authentication. | ||
|
adombeck marked this conversation as resolved.
|
||
|
|
||
| ## Microsoft Entra ID | ||
|
|
||
| Microsoft Entra ID supports the following authentication flows: | ||
|
|
||
| - **Device code flow**: The user visits a URL and enters a code to authenticate. | ||
| - **Entra authentication**: The user authenticates directly with Microsoft Entra ID, | ||
| using their password or a supported passwordless method, followed by an MFA | ||
| challenge if required. On success, authd caches the credentials locally for | ||
| subsequent logins. | ||
|
|
||
| Both flows are enabled by default and can be individually configured using the | ||
| `[flows]` section of the broker configuration file. See | ||
| [Configure authentication flows](ref::config-auth-flows) for details. | ||
|
|
||
| The **Entra authentication** flow has additional requirements for resolving group | ||
| membership, depending on whether device registration is enabled. See | ||
| [Group membership resolution with Entra authentication](reference::group-membership-resolution). | ||
|
|
||
| ### Compatibility and requirements | ||
|
|
||
| The **device code flow** works with all Microsoft Entra ID account types. | ||
|
|
||
| The **Entra authentication** flow requires an MFA method enrolled on the account | ||
| that is supported by authd. The following account types cannot complete this | ||
| flow and fall back to the device code flow if it is enabled, or are denied | ||
| otherwise: | ||
|
|
||
| - Accounts without an MFA method enrolled | ||
| - Accounts whose only MFA method is a FIDO2/passkey credential | ||
| - Federated (on-premises AD FS) accounts | ||
|
|
||
| ## Keycloak | ||
|
|
||
| Keycloak supports the **device code flow**, where the user visits a URL and | ||
| enters a code to complete authentication. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should we allow disabling the passwordless authentication here? Maybe with a
allow_entra_passwordlesssetting?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(if we decide we want that, the implementation should be in a separate PR)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What would be the expected behavior here? to redirect to DAG or fail the authentication if the user has a passwordless MFA method and that setting is disabled?
or then the user would be required to enter a password at all times? (Not sure if this can contradict the Entra's policies/configuration, but I can try to experimenting with that)
Usually I don't like extending the config with too many flags, but I think it's something we can consider if the users requested it, I checked himmelblau conf, and they don't have an equivalent config. But let's test and validate the scenarios further before deciding. Maybe there is a valid use case for that.
Created https://warthogs.atlassian.net/browse/UDENG-10999 to track and investigate this further
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
agreed, let's wait for users actually requesting such a feature before spending time on it