Skip to content
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

API Guide: update auth section on bearer tokens #11099

Merged
merged 2 commits into from
Jan 28, 2025
Merged

API Guide: update auth section on bearer tokens #11099

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4551779
Update auth.rst
qqmyers Dec 16, 2024
063fa5e
Apply suggestions from code review
qqmyers Jan 24, 2025
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
16 changes: 7 additions & 9 deletions doc/sphinx-guides/source/api/auth.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,22 +87,20 @@ To register a new user who has authenticated via an OIDC provider, the following

curl -H "Authorization: Bearer $TOKEN" -X POST http://localhost:8080/api/users/register --data '{"termsAccepted":true}'

If the feature flag ``api-bearer-auth-handle-tos-acceptance-in-idp``` is disabled, it is essential to send a JSON that includes the property ``termsAccepted``` set to true, indicating that you accept the Terms of Use of the installation. Otherwise, you will not be able to create an account. However, if the feature flag is enabled, Terms of Service acceptance is handled by the identity provider, and it is no longer necessary to include the ``termsAccepted``` parameter in the JSON.

In this JSON, we can also include the fields ``position`` or ``affiliation``, in the same way as when we register a user through the Dataverse UI. These fields are optional, and if not provided, they will be persisted as empty in Dataverse.

There is another flag called ``api-bearer-auth-provide-missing-claims`` that can be enabled to allow sending missing user claims in the registration JSON. This is useful when the identity provider does not supply the necessary claims. However, this flag will only be considered if the ``api-bearer-auth`` feature flag is enabled. If the latter is not enabled, the ``api-bearer-auth-provide-missing-claims`` flag will be ignored.

With the ``api-bearer-auth-provide-missing-claims`` feature flag enabled, you can include the following properties in the request JSON:
By default, the Bearer token is expected to include the following claims that will be used to create the user account:

- ``username``
- ``firstName``
- ``lastName``
- ``emailAddress``

If properties are provided in the JSON, but corresponding claims already exist in the identity provider, an error will be thrown, outlining the conflicting properties.
The one parameter required by default is ``termsAccepted`` which must be set to true, indicating that the user has seen and accepted the Terms of Use of the installation.

If the feature flag ``api-bearer-auth-handle-tos-acceptance-in-idp`` is enabled (along with the ``api-bearer-auth`` feature flag), Dataverse assumes that the Terms of Service acceptance was handled by the identity provider, e.g. in the OIDC ``consent`` dialog, and the ``termsAccepted`` parameter is not needed.
Copy link
Contributor

Choose a reason for hiding this comment

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

@pdurbin: Could we do this?
"If the feature flag api-bearer-auth-handle-tos-acceptance-in-idp is enabled (along with the api-bearer-auth feature flag), Dataverse assumes that the Terms of Service acceptance is handled by the Identity Provider and therefore the ``termsAccepted'' parameter is not needed."

The current process is not true authentication. The system receives a token that may not be intended for it, and uses it to create an account without prompting. The real authentication takes place somewhere else, we assume the SPA, where hopefully the consent screen is used. With this formulation, the behaviour is less ambiguous, since Dataverse itself has no means of using a consent screen.

Copy link
Member

Choose a reason for hiding this comment

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

@qqmyers what do you think?

Copy link
Member Author

Choose a reason for hiding this comment

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

This is a documentation PR trying to clarify what has already been implemented/merged in #10972.

If there's something to change other than tweaking language, it should probably be a new issue (which should probably be in the dataverse-security repo). FWIW: I could be wrong, but I don't believe that "The system receives a token that may not be intended for it, and uses it to create an account without prompting" is true - the received token is used to call the userinfo API of registered providers only, and only if one of them returns a valid userinfo response is an account created.

Copy link
Contributor

Choose a reason for hiding this comment

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

FWIW: I could be wrong, but I don't believe that "The system receives a token that may not be intended for it, and uses it to create an account without prompting" is true - the received token is used to call the userinfo API of registered providers only, and only if one of them returns a valid userinfo response is an account created.

This scenario only applies if a third party has a valid token (which stays valid during the user info API calls) and send it without user consent to a dataverse instance. This is to be honest a malicious scenario, which most likely will not occur.


There is another flag called ``api-bearer-auth-provide-missing-claims`` that can be enabled (along with the ``api-bearer-auth`` feature flag) to allow sending missing user claims in the registration JSON. This is useful when the identity provider does not supply the necessary claims listed above. If properties are provided in the JSON, but corresponding claims already exist in the identity provider, an error will be thrown, outlining the conflicting properties. Note that supplying missing claims is configured via a separate feature flag because using it may introduce user impersonation issues, for example if the identity provider does not provide an email field and the user submits an email address they do not own.

This functionality is included under a feature flag because using it may introduce user impersonation issues, for example if the identity provider does not provide an email field and the user submits an email address they do not own.
In all cases, the submitted JSON can optionally include the fields ``position`` or ``affiliation``, which will be added to the user's Dataverse account. These fields are optional, and if not provided, they will be persisted as empty in Dataverse.

Signed URLs
-----------
Expand Down
Loading