Skip to content

feat: Add Permissions API support - #578

Merged
thinkingserious merged 18 commits into
sendgrid:mainfrom
philrowan:permissions_api
Apr 15, 2021
Merged

thinkingserious merged 18 commits into
sendgrid:mainfrom
philrowan:permissions_api

Conversation

@philrowan

Copy link
Copy Markdown
Contributor

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.

@thinkingserious thinkingserious added the status: code review request requesting a community code review or review from Twilio label Oct 20, 2017
@SendGridDX

SendGridDX commented Oct 20, 2017 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@mbernier mbernier added difficulty: hard fix is hard in difficulty hacktoberfest labels Oct 23, 2017
@mbernier

mbernier commented Oct 23, 2017 •

Copy link
Copy Markdown
Contributor

@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!!

@shortstuffsushi

Copy link
Copy Markdown
Contributor

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?

@mbernier

mbernier commented Nov 2, 2017

Copy link
Copy Markdown
Contributor

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.

@mbernier

mbernier commented Nov 3, 2017

Copy link
Copy Markdown
Contributor

@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.

@philrowan

Copy link
Copy Markdown
Contributor Author

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.

@thinkingserious

thinkingserious commented Nov 3, 2017 •

Copy link
Copy Markdown
Contributor

No worries @teabaggs,

We appreciate your contributions and support!

@thinkingserious thinkingserious added the type: twilio enhancement feature request on Twilio's roadmap label Mar 5, 2018
@thinkingserious

Copy link
Copy Markdown
Contributor

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 thinkingserious added status: waiting for feedback waiting for feedback from the submitter and removed status: code review request requesting a community code review or review from Twilio labels Aug 21, 2018
@childish-sambino childish-sambino removed the type: twilio enhancement feature request on Twilio's roadmap label Jul 20, 2020
@thinkingserious
thinkingserious changed the base branch from master to main July 28, 2020 14:28

@thinkingserious thinkingserious left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please include an entry in USE_CASES.md to demonstrate usage.

@thinkingserious thinkingserious added type: community enhancement feature request not on Twilio's roadmap and removed difficulty: hard fix is hard in difficulty labels Nov 20, 2020
@thinkingserious thinkingserious changed the title Permissions api feat: Add Permissions API support Dec 14, 2020
@thinkingserious

Copy link
Copy Markdown
Contributor

Hello @teabaggs,

Just checking in to find out if you want to continue working on this PR. Thanks!

@philrowan

Copy link
Copy Markdown
Contributor Author

hello @thinkingserious ,
Yes, I did add some documentation in USE_CASED.md. See this commit. What else needs to be done? Thanks.

@thinkingserious thinkingserious left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This code review is WIP ...

Thanks again for the PR!

Comment thread USE_CASES.md Outdated
# 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

nit: Please add line breaks after paragraphs.

Comment thread USE_CASES.md Outdated

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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

We should note that this example enables permissions for all scopes.

Comment thread USE_CASES.md Outdated
var apiKey = Environment.GetEnvironmentVariable("NAME_OF_THE_ENVIRONMENT_VARIABLE_FOR_YOUR_SENDGRID_KEY");
var client = new SendGridClient(apiKey);
var builder = new SendGridPermissionsBuilder();
builder.CreateReadOnlyMailSend();

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

Comment thread USE_CASES.md
```

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nice!

/// Builds the specified options.
/// </summary>
/// <param name="requestedOptions">The options.</param>
/// <param name="prefix">The prefix.</param>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

I think we might want to be a bit more descriptive here. What does a valid prefix look like?

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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.

@philrowan

Copy link
Copy Markdown
Contributor Author

@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.
Thanks.

@thinkingserious

Copy link
Copy Markdown
Contributor

Quick update. I am awaiting confirmation on the correct list of scopes. When I get confirmation, I will update here.

@thinkingserious

Copy link
Copy Markdown
Contributor

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>

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks like documentation here got cut off.

public bool IsMutuallyExclusive { get; protected internal set; }

/// <inheritdoc/>
public IEnumerable<string> Build(ScopeOptions requestedOptions)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

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?

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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 thinkingserious left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This one looks just about done (just needs a few docs updates) to me! 🥳

Comment thread USE_CASES.md Outdated

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Please update the wording here, particularly "You can enums named".

Comment thread USE_CASES.md

// now use the provided extension method to create an API key

await client.CreateApiKey(builder, "Alerts & Read-Only Marketing Campaigns API Key");

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Nice!

Comment thread USE_CASES.md Outdated

There are also some methods to easily create API keys for various common use cases.

For example, to create a Mail API:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

"create a Mail API" to something like "create a Mail Send API Key scoped for sending email"

@thinkingserious thinkingserious left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Thank you for all the work put into this PR and responding timely to our requests. We appreciate it!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

status: waiting for feedback waiting for feedback from the submitter type: community enhancement feature request not on Twilio's roadmap

Projects

None yet

Development

Successfully merging this pull request may close these issues.

9 participants