Sendgrid-csharp: Make SendGrid permissions management easy

[thinkingserious]

Create a class for managing permission scopes that has the following features:

• Allow you to add create, delete, read, update permissions for each of the groups defined here -- these can be hard coded in
• Allow for creating an array of all the scopes possible, as a "create admin permissions" method
• Allow for "read only" which pulls only read permissions
• Create a method for each of the example groups here, which provide the appropriate permissions. Note: Some of these are redundant with the previous requests on this issue.

[teabaggs]

I'll work on this.

[thinkingserious]

Awesome, thanks @teabaggs!

[teabaggs]

I'm having some issues with the fork and creds at the moment so I just threw up a gist with an initial idea. https://gist.github.com/teabaggs/34b2b88ba194fd93d4d30dac1330f4a6

I have a few questions.

1. does the order of the scopes in the output matter?
2. what should the output be? Currently spitting out a string. Perhaps a list of strings is better; then the client can order and format them as needed?

I'm not a huge fan of the typed scopes but it does allow one to ensure the added scopes are valid pretty easily perhaps at the cost of class bloat. I'm thinking of making this a lookup based on an enum key instead. Did you have anything in mind?

[thinkingserious]

Hi @teabaggs,

1. It would be preferable if the order can match what we have in the documentation.
2. I like a list of strings.

I'm OK with some class bloat if it means a better experience.

I hope that helps!

With Best Regards,

Elmer

[Jericho]

@thinkingserious regarding "create admin permissions" method: I would like to make two observations:

1. The SendGrid API does not allow you to grant a given permission (or "scope" as it's called in SendGrid's documentation) if you have not been granted this permission in the first place. This makes a lot of sense because, for instance, you don't want a "read-only" user to be able to create a new API Key with "admin" privileges. This would effectively allow them to gain privileges they have not been granted. If the list of privileges that make up an "admin" role is hard-coded, there's a good chance the call to create the new Api Key will fail because the developer may or may not have been granted all of these privileges. I faced this exact problem in StrongGrid and my workaround was to retrieve the permissions associated with the current user and then to create the new Api Key with these privileges. This has two benefits: I don't have to hard-code the privileges and it eliminates the risk of exceptions due to the fact that I may be trying to grant a permission that I haven't been granted.

2. The SendGrid documentation mentions that certain permissions are mutually exclusive. Specifically, the "billing" permissions are mutually exclusive from all others. Therefore, make sure you don't include these billing permissions in the "admin" role.

Speaking of "billing" privileges, what are they for? I don't see any documented Api endpoint related to billing functionality.

[teabaggs]

@Jericho @thinkingserious

1. I was not aware of this so thanks for pointing it out. I this we can solve this by letting this builder work as is and build out a complete list of scopes with no awareness of any user's permissions. Then we offer a MergeWithUserPermissions method to trim that list down to only those scopes that are possible for a given user. So the builder will essentially have a filtering mechanism before the final Build call which emits the list of scopes. This offers an extensibility point for other types of filtering too. Now the main question is, should the permissions builder make the api call to get a user's current permissions or should the be left to the application?

1. Dealing with this is mutual exclusivity is easy enough but what should the API do if some user attempts to set both a billing permission and some other permission then? It seems to me this warrants an exception being thrown.

* Edit * another question about the second point: Should the method that creates all the admin permissions include the billing scopes?

[teabaggs]

@thinkingserious
the admin API key permission list exists on both pages linked in the original issue here and here and are different. I'm going to assume the one with more scopes, the second one linked here, is the correct one but please let me know if that is not the case.

[teabaggs]

@thinkingserious regarding the ordering of the permissions: everything in the documentation is ordered alphabetically except where "mail_settings.*" is before "mail.batch" and "mail.send". I don't think it makes sense to have a custom comparer to break the otherwise alphabetical ordering. What bout updating the docs to be alphabetically ordered instead?

[thinkingserious]

@ksigler7, @mbernier,

Thoughts?

[apigirl]

Just talked with @mbernier about this, and we don't think the order should matter - so go ahead and do it alphabetically!

Just so you know, you can get an updated permission list by using the GET
/api_keys/{api_key_id} method. Just create an API key with the level of permissions you need, and then you can use that method to look up exactly which permissions it has. In this case, the api_key_id is everything in the API key after the SG and before the second dot, so if this were an example API key: SG.aaaaaaaaaaaaaa.bbbbbbbbbbbbbbbbbbbbbbbb, your api_key_id would be aaaaaaaaaaaaaa.

[thinkingserious]

@teabaggs ^^

[teabaggs]

@thinkingserious, Thanks, I got it. My account got flagged so I am waiting on getting access back so I
can play around with the api for real. I have tests for verifying that the
list of claims (as string) output from the builder matched the linked docs.
I will change those to match the results of the api calls but those will
still be hardcoded. I need to look at the integration tests more since they
all fail on my machine. I think they are really calling the api and I don't
have the auth configured properly? If they really do call the api then
should I add integration tests to verify that the builder output matches
the actual api results too?

[mbernier]

@teabaggs - hit me up at my email (github + company URL) with your ticket ID, I'll go see if I can help with the support ticket.

[thinkingserious]

Hi @teabaggs,

The tests do not make any live API calls. Please see this documentation for instruction on how to setup a local test environment.

Thanks!

With Best Regards,

Elmer

[Jericho]

Back on October 22 2017 I asked a question that was overlooked. My question was:

Speaking of "billing" privileges, what are they for? I don't see any documented Api endpoint related to billing functionality.

@thinkingserious @ksigler7 can you help?

[apigirl]

Hey @Jericho! Billing level API key access gives admin level control over the account - you can update billing information and account ownership. You're right though, that there's no documented API methods that allow you to update billing settings - our research has found that there's not really a need for this (let me know if you disagree!).

I think we just initially released this level of API key so that it has parity with the access levels that are offered in the UI.

[thinkingserious]

Since there has been no activity on this issue since March 1, 2020, we are closing this issue. Please feel free to reopen or create a new issue if you still require assistance. Thank you!