Repository navigation
feat: Add Permissions API support - #578
Conversation
|
@Jericho, @xt0rted, @Niladri24dutta, @jonnybee, @nate-fr, @owre, @spib, @shortstuffsushi, @JefStat, @teabaggs, @paritoshmmmec If you're available, can you please give this a look and give feedback? Thank you!! |
|
I'm not familiar with the permissions API stuff, what's the point of this? How / when would I use this as a consumer of the repo? |
|
This would be a thing that you would use for creating API Keys and Teammates - as both of them use the same permissions. Eventually, I would like to build a system that would auto-rotate API Keys using this code. |
|
@teabaggs We have not been able to merge your Pull Request, but because you are awesome - we wanted to make sure you could still get a SendGrid Hacktoberfest shirt. Please go fill out our swag form before Nov 5th and we will send the shirt! (We know that you might have tried this before and it didn’t work, sorry about that!) You have till Nov 5th to fill out this form in order to get the Hacktoberfest shirt!Thank you for contributing during Hacktoberfest! We hope to see you in the repos soon! Just so you know, we always give away a SendGrid shirt for your first ever non-Hacktoberfest PR that gets merged. |
|
Hi @mbernier . Thank you. I haven't had time to touch this lately and I was waiting for some feedback for a bit. I expect to get some time this weekend and intend to complete this in any case. |
|
No worries @teabaggs, We appreciate your contributions and support! |
|
Hello @teabaggs, It looks like all we are missing on this PR is some documentation. Do you need some help with that? With Best Regards, Elmer |
thinkingserious
left a comment
There was a problem hiding this comment.
Please include an entry in USE_CASES.md to demonstrate usage.
… the JSON up manually
…be cool if it were just alphabetical
|
Hello @teabaggs, Just checking in to find out if you want to continue working on this PR. Thanks! |
|
hello @thinkingserious , |
thinkingserious
left a comment
There was a problem hiding this comment.
This code review is WIP ...
Thanks again for the PR!
| # Working with permissions | ||
|
|
||
| The permissions builder is a convenient way to manipulate API key permissions when creating new API keys or managing existing API keys. | ||
| You can use the types named according to the various [permissions](https://sendgrid.api-docs.io/v3.0/api-key-permissions) to add the scopes required for those permissions. |
There was a problem hiding this comment.
nit: Please add line breaks after paragraphs.
|
|
||
| The permissions builder is a convenient way to manipulate API key permissions when creating new API keys or managing existing API keys. | ||
| You can use the types named according to the various [permissions](https://sendgrid.api-docs.io/v3.0/api-key-permissions) to add the scopes required for those permissions. | ||
| For example, to create an API key for Alerts and Stats: |
There was a problem hiding this comment.
We should note that this example enables permissions for all scopes.
| var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY"); | ||
| var client = new SendGridClient(apiKey); | ||
| var builder = new SendGridPermissionsBuilder(); | ||
| builder.CreateReadOnlyMailSend(); |
There was a problem hiding this comment.
It might be nice if we had:
builder.CreateReadOnlyMailSend();
client.Request(builder);but I think that's out of scope for this PR. This is a note to self to file a follow up issue.
| ``` | ||
|
|
||
| The builder filters out duplicate scopes by default but you can also add filters to the builder so that your application will never create keys with certain scopes. | ||
| For example, you may want to allow an API key to do just about anything EXCEPT create more API keys. |
| /// Builds the specified options. | ||
| /// </summary> | ||
| /// <param name="requestedOptions">The options.</param> | ||
| /// <param name="prefix">The prefix.</param> |
There was a problem hiding this comment.
I think we might want to be a bit more descriptive here. What does a valid prefix look like?
There was a problem hiding this comment.
I'm going to refactor this a bit and just hardcode and enumerate all the scope strings per permission. This code is a few years old now and I've just re-checked and some of them have changed it looks like. Also some permissions (namely Stats is non-conforming to the naming of permission.operation and won't fit in this model. With this change this prefix will be removed.
|
@thinkingserious If I create a new "Full Access" API Key from the web and fetch the scopes via the API that list of scopes does not match what is listed at https://sendgrid.api-docs.io/v3.0/api-key-permissions/api-key-permissions#Admin-API-Key-Permissions. I feel like they should but want to check with you before I code it up that way. |
|
Quick update. I am awaiting confirmation on the correct list of scopes. When I get confirmation, I will update here. |
|
Here is the correct documentation: https://sendgrid.api-docs.io/v3.0/how-to-use-the-sendgrid-v3-api/api-authorization Please let us know if you find anything incorrect. Thanks! |
| /// Adds the permissions for the specified <typeparamref name="TScope"/> | ||
| /// </summary> | ||
| /// <typeparam name="TScope">The type of the scope.</typeparam> | ||
| /// <param name="options">The o.</param> |
There was a problem hiding this comment.
Looks like documentation here got cut off.
| public bool IsMutuallyExclusive { get; protected internal set; } | ||
|
|
||
| /// <inheritdoc/> | ||
| public IEnumerable<string> Build(ScopeOptions requestedOptions) |
There was a problem hiding this comment.
Not seeing a unit test for this function where ScopeOptions.ReadOnly or ScopeOptions.All are passed in?
| /// <param name="client">The client.</param> | ||
| /// <param name="cancellationToken">The cancellation token.</param> | ||
| /// <returns>The builder instance with the filter applied.</returns> | ||
| public async Task<SendGridPermissionsBuilder> FilterByCurrentApiKeyAsync(ISendGridClient client, CancellationToken cancellationToken = default(CancellationToken)) |
There was a problem hiding this comment.
Thinking this would be better as a standalone helper function. Seems like we should have a function that calls the GET /scopes endpoint, then passes in the resulting data to a new SendGridPermissionsBuilder object. It doesn't make sense to me that this would be a member function of the permissions object itself.
| /// </summary> | ||
| /// <param name="filter">The filter.</param> | ||
| /// <returns>The builder instance with the exclusion filter applied.</returns> | ||
| public SendGridPermissionsBuilder Exclude(Func<string, bool> filter) |
There was a problem hiding this comment.
Would also like to see an Include function, ideally one that also accepts a list of scopes, so it can easily be built from the returned body of the GET /scopes api call
There was a problem hiding this comment.
Should such a method mask against a list of known scopes so that arbitrary (e.g. invalid) scopes cannot be included? I believe the request will ultimately fail if it is called with scopes that don't actually exist. If so, should the Build method throw if invalid scopes have been included or should they just be omitted from the final list of omitted scopes?
There was a problem hiding this comment.
The function should accept based on a list of known scopes. If the function is called with an invalid scope, that doesn't exist, the method should throw.
- add Include method to permissions builder - add utility extension method for creating a builder masking against the scopes granted to the current API key - add utility extension method for creating an API key from a permissions builder
- Swap classes for enums and a lookup - Add helper methods for mutual exclusivity and scope validation - Adjust tests
thinkingserious
left a comment
There was a problem hiding this comment.
This one looks just about done (just needs a few docs updates) to me! 🥳
|
|
||
| The permissions builder is a convenient way to manipulate API key permissions when creating new API keys or managing existing API keys. | ||
|
|
||
| You can enums named according to the various [permissions](https://sendgrid.api-docs.io/v3.0/api-key-permissions) to add the scopes required for those permissions. |
There was a problem hiding this comment.
Please update the wording here, particularly "You can enums named".
|
|
||
| // now use the provided extension method to create an API key | ||
|
|
||
| await client.CreateApiKey(builder, "Alerts & Read-Only Marketing Campaigns API Key"); |
|
|
||
| There are also some methods to easily create API keys for various common use cases. | ||
|
|
||
| For example, to create a Mail API: |
There was a problem hiding this comment.
"create a Mail API" to something like "create a Mail Send API Key scoped for sending email"
thinkingserious
left a comment
There was a problem hiding this comment.
Thank you for all the work put into this PR and responding timely to our requests. We appreciate it!
This is not complete but is a working example of the permissions builder. I'm looking for some feedback please before I go ahead and build out the classes for all the possible api key permission types. I want to get this right first since the rest will be mostly boilerplate classes for the new permission types.