GEODE-9933: documentation for authorization expiry

[jmelchio]

Describes the addition of throwing AuthenticationExpiredException in SecurityManager.authorize and SecurityManager.authenticate methods along with some additional information on token based authentication.

[davebarnes97]

@jmelchio Thanks for your contribution to the user guide!
I approve the two example files as-is.
I request a few changes to the implementation files - I've attached a diff containing these changes.
One change is mandatory in each file - please replace Geode with the product_name variable (see diff for syntax).
A discretionary change in the implementing_authentication file would be my suggested re-phrasing (three occurrences) that emphasizes that the token is one alternative, and that the username/password combination is a second alternative. Your choice on this one - read it and see what you think.
GEODE-9933.DIFF.zip

[jinmeiliao]

We should somehow convey these to the readers:

1. the Properties returned by the getCredentials call is passed directly to the authenticate call, and the subject returned by the authenticate call is passed directly to the authorize. So getCredentials() --> authenticate() --> authorize(). the output of the previous call is fed to the next. The interface doesn't dictate what should be in the input/output.
2. When a AuthorizationExpiredException is thrown anywhere in the calling chain, the client will try one more time to call getCredentials again and re-login automatically behind the scene, if the re-try failed, user will then see AuthorizationExpiredException. Bear in mind there is a time gap between getCredentials call on the client and authorize call on the server, so if client returns a credential that's gonna expire in the very near future, even the retry might fail.
3. limitation of this auto-retry: currently only supported on client/server protocol, and is not supported in event-dispatching (cq and registered interest) in multi-user client mode.

[jmelchio]

@jmelchio Thanks for your contribution to the user guide! I approve the two example files as-is. I request a few changes to the implementation files - I've attached a diff containing these changes. One change is mandatory in each file - please replace Geode with the product_name variable (see diff for syntax). A discretionary change in the implementing_authentication file would be my suggested re-phrasing (three occurrences) that emphasizes that the token is one alternative, and that the username/password combination is a second alternative. Your choice on this one - read it and see what you think. GEODE-9933.DIFF.zip

Thanks @davebarnes97, I've applied the patch file and pushed the commit.

[jmelchio]

We should somehow convey these to the readers:

1. the `Properties` returned by the `getCredentials` call is passed directly to the `authenticate` call, and the subject returned by the `authenticate` call is passed directly to the `authorize`. So getCredentials() --> authenticate() --> authorize(). the output of the previous call is fed to the next.  The interface doesn't dictate what should be in the input/output.

2. When a `AuthorizationExpiredException` is thrown anywhere in the calling chain, the client will try one more time to call `getCredentials` again and re-login automatically behind the scene, if the re-try failed, user will then see `AuthorizationExpiredException`. Bear in mind there is a time gap between `getCredentials` call on the client and `authorize` call on the server, so if client returns a credential that's gonna expire in the very near future, even the retry might fail.

3. limitation of this auto-retry: currently only supported on client/server protocol, and is not supported in event-dispatching (cq  and registered interest) in multi-user client mode.

@jinmeiliao I will update to add the information mentioned in the first point. I think the second point is covered in the updated docs, and I will update to clarify the thirst point.

[jinmeiliao]

@jinmeiliao I will update to add the information mentioned in the first point. I think the second point is covered in the updated docs, and I will update to clarify the thirst point.

I think we should dedicate a section for the re-auth feature, outline the process, when the feature is started (1.15.0), what's the behavior on older clients (also for older client, the CQ/register interest client will be disconnected if they have expired credentials ), and those I mentioned in my bullet 3 above.

[davebarnes97]

Thanks @davebarnes97, I've applied the patch file and pushed the commit.
Thanks, @jmelchio - Looks like you'll be making more changes in response to @jinmeiliao's review. I'll hold off on finishing my review until after those changes are in place.

[davebarnes97]

Almost there.
Good new page on expiry. I edited it in place to make one format tweak: a blank line before the bullet list so it would display as intended.
One more request: Since you've added a new file, it needs an entry in the left-hand navigation source file: /geode-book/master_middleman/source/subnavs/geode-subnav.erb
Attached diff file shows the change.
GEODE-9933-2.DIFF.zip

[davebarnes97]

One more comment for the record:
The retry behavior is a new feature in Geode v1.15, but much of the material relating to tokens was applicable in earlier Geode releases, and could be back-ported to earlier Geode docs after this PR is merged.
I will undertake to create a JIRA ticket for that work after this PR is merged.
Thanks, @jmelchio and @jinmeiliao, for your contributions to the docs!

[jinmeiliao]

I think this is misleading. Older client with multi-user auth will still work in regular user operations like put/get etc.

Probably a diagram would explain this better

                       single user ops  |    single user CQ/RI  |  multi user ops  |  multi user CQ/RI
1.15 and later                          |                       |                  |         X
previous                                |             X         |                  |         X

[davebarnes97]

@jmelchio Be sure to say "Geode 1.15", as this source file is consumed by other products whose versioning may differ.

[jmelchio]

@davebarnes97 updated the code

[jinmeiliao]

Oh, this table shows client version, did we mention anywhere in the doc that the re-authentication feature is only supported by server with Geode 1.15 and higher

[jinmeiliao]

Emphasize that there would be time gap between the call of getCredential and authorize

[davebarnes97]

Nice work, @jmelchio . Thanks for your contribution.