Support refreshtokens in OAuth flow

[Kencdk]

Resolves #2731

---

Behavior

Before the change?

• OAuth Client doesn't support getting the refresh token, nor utilizing it to get a new access token.
• Additionally, it doesn't return information about when the access token expires.

After the change?

• CreateAccessToken now returns all fields from the returned body, including token expiration, refresh token and refresh token expiration time.
• CreateAccessTokenFromRefreshToken accepts a clientId, clientSecret and refresh token, in order to create a new access token on behalf of the user, the refresh token was created for.

Other information

While the endpoint is the same for creating an access token from a response code and for creating an access token based on the refresh token, there are key differences in the expected parameters. When creating based on a refresh token, the grant_type needs to be set.

As a result, I opted to create a new function instead of adding a mix of optional and required parameters (depending on input) to the existing CreateAccessToken function. Please advise if you'd prefer otherwise.

• https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app
• https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/refreshing-user-access-tokens

---

Additional info

Added <inheritdoc /> instead of having the xml doc in both interfaces and implementation.
The end-result is the same, it just avoids having to keep both up-to-date.

Pull request checklist

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• Added the appropriate label for the given change

Does this introduce a breaking change?

Please see our docs on breaking changes to help!

• Yes (Please add the Type: Breaking change label)
• No

If Yes, what's the impact:

• N/A

Pull request type

Type: Feature

---

[kfcampbell]

This approach seems reasonable and I love the functionality!

[kfcampbell]

Do you think it'd be worthwhile to add a comment here and above describing the situations when you'd want to use each constructor?

[Kencdk]

I primarily kept the old one, to keep the change binary compatible - to avoid breaking changes :)
Added a summary for good measure.

These constructors aren't really meant to be used manually - so wondering if the one without the refresh token should be marked as deprecated, so it can be removed sometime in the future? :)

[kfcampbell]

Got it, thank you! I think it's reasonable to mark the old one as deprecated to be removed in a future major release. After that's done, I can merge and release this!

[kfcampbell]

@Kencdk are you okay with the updates I've made? If so, I can ship this!

[Kencdk]

@Kencdk are you okay with the updates I've made? If so, I can ship this!

@kfcampbell, Yup, looks good to me!