[DOCS-16628] Improve API docs specification on databaseName in role assignment for database users Created: 22/Jan/24  Updated: 02/Feb/24

Status: Needs Triage
Project: Documentation
Component/s: API, Atlas
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major - P3
Reporter: Fiona Rowan Assignee: Unassigned
Resolution: Unresolved Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PNG File Screenshot 2024-01-22 at 2.24.13 PM.png    
Participants:
Days since reply: 5 days ago

 Description   

In the API docs for creating / updating a database user, the "roles" assignment currently look as follows (please note the "databaseName" attribute): 

 

The description currently looks identical to "databaseName" attribute on the top-level database user in the same request body, but is not helpful for role assignment written as is. This value is not the database against which the user authenticates, but the scope of the role being assigned.

Let's tweak the description for roles.databaseName to be something like the following (worth double-checking with product on exact language here): 

Database where the role is defined and where the role and can grant access down to a collection-level of granularity. Note that custom database roles are always created in the admin database in Atlas. Please refer to documentation for MongoDB built-in database roles to determine which database scope is appropriate when assigning those roles based on the access you'd like to grant the given database user.



 Comments   
Comment by Matteo Vesprini-Heidrich [ 02/Feb/24 ]

Our new arrangement should be that the docs team will handle these API doc changes for us.

Comment by Memento Slack Bot [ 22/Jan/24 ]

Slack Thread captured from #ask-cloud-atlas-clusters by fiona.rowan@mongodb.com

Based on the condition in mms it looks like `databasename == 'admin'` is required for a custom DB role. Is this something that should instead be inherited from the custom role? instead of having the user specify 'admin' database
What is the reasoning behind having the user specifically mention `admin` database here?

Please feel free to redirect to another channel if needed.

  • fiona.rowan@mongodb.com: I'd say this is a Product question - you're right, we could automatically assign `admin` . it's not necessary from a MongoDB perspective to specify that specific database though - roles could be created in any database, but Atlas enforces all user-defined or custom roles are created in `admin` so that it may include privileges that apply to any database in the deployment.

maybe sue.nguyen@mongodb.com could weigh in on whether specifying `admin` by default for Atlas-managed user-defined roles is desirable, or if we intentionally want users to be aware of the implications?

  • sue.nguyen@mongodb.com: sorry for the delay. Is this problem specific to just Terraform only? If the only option is “admin” , allowing users to specify something different only to have it break doesn’t seem right
  • aastha.mahendru@mongodb.com: thanks for the insights fiona.rowan@mongodb.com sue.nguyen@mongodb.com
    > If the only option is “admin” , allowing users to specify something different only to have it break doesn’t seem right
    agreed, i think the question here is that it isn't specified anywhere in the documentation that for a custom role, user needs to specify the database to be 'admin'. However, this is enforced in the code and `databaseName` under `roles` is a required attribute in the API as well

So the issue here is either we should call this out somewhere in the documentation for users AND if possible, call out the rationale behind having users specify `admin` database for custom roles
OR let the API default database name to `admin` without having the user specify it (and in this case `databaseName` under `roles` will need to be made Optional.

IMO a doc update is a feasible option

> is this problem specific to just Terraform only?
no this is on API level

  • sue.nguyen@mongodb.com: Based on the Admin API doc, the `databaseName` could be “$external” or “admin”. Can a custom role be “$external”?
  • aastha.mahendru@mongodb.com: I am not sure about that unfortunately, fiona.rowan@mongodb.com are you able to advise on that? would be good for my understanding as well
  • aastha.mahendru@mongodb.com: hey fiona.rowan@mongodb.com just following up on this one again
  • fiona.rowan@mongodb.com: apologies for the delay - a couple things:
    • "$external" database name is reserved for defining a MongoDB user. the `databaseName` we're referring to has to do with assigning a user a role, and that `databaseName` indicates the database the assigned role should be scoped to
    • looking at that github issue again and the code, I just want to get on the same page about one point: custom roles are defined with the `admin` database by Atlas on the backend - the user doesn't have to specify the database when creating the custom role. they are only required to specify the database the role is scoped to when assigning to a user.
    • there are built-in MongoDB roles, like `readWrite`, that do not need to be scoped to the `admin` database when assigned to a user, and can be scoped to any database name
    always requiring that the user specifies the `databaseName` when assigning the role to a given user ensures the payload for assigning a role looks consistent regardless of whether they're assigning a built-in role or custom role. however, as mentioned in thread, Atlas could also auto-scope the database for a custom role to be `admin` if not specified by the user in the API payload.

hope this makes sense - let me know if there are further questions here on how Atlas handles roles!

  • aastha.mahendru@mongodb.com: thanks fiona.rowan@mongodb.com! makes sense, and totally understand the API consistency pov as well. I think given this we are going to update the Atlas Terraform documentation to mention that custom role assignment to a database user should include `databaseName = admin`.
    I think same should be updated in the API spec as well, WDYT?
  • fiona.rowan@mongodb.com: yes that would make sense to me - I can file a ticket for the public API docs. thanks for raising this!
  • aastha.mahendru@mongodb.com: sounds great! please share the ticket here once you have it , thanks again!
Generated at Thu Feb 08 08:15:46 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.