Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Clarify that authorize can be given just a token #186

Closed
wants to merge 3 commits into from
Closed

Clarify that authorize can be given just a token #186

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
a46acc7
Clarify RSA10e (Auth#authorize requesting tokens)
SimonWoolf Nov 1, 2016
dbfcaa5
Add missing token and tokenDetails properties to authOptions
SimonWoolf Nov 1, 2016
0203f19
Clarify TokenDetails
SimonWoolf Nov 23, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions content/client-lib-development-guide/features.textile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -107,6 +107,7 @@ h3(#rest-auth). Auth
*** @(RSA4c1)@An @ErrorInfo@ with @code@ @80019@ and description of the underlying failure should be emitted with the state change, in the @errorReason@ and/or in the callback as appropriate
*** @(RSA4c2)@If the connection is @CONNECTING@, then the connection attempt should be treated as unsuccessful, and as such the connection should transition to the @DISCONNECTED@ or @SUSPENDED@ state as defined in "RTN14":#RTN14 and "RTN15":#RTN15
*** @(RSA4c3)@If the connection is @CONNECTED@, then the connection should remain @CONNECTED@
** @(RSA4d)@ If multiple @authOptions@ are used to initialize the library, the preference ordering among them is identical to @Auth#authorize@, defined in @RSA10e@
Copy link
Contributor

Choose a reason for hiding this comment

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

I think "multiple authOptions" is confusing. What's an authOption? The formatting seems to indicate it's something formal in the code, like a specified field or type.

Copy link
Member

Choose a reason for hiding this comment

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

Agreed.

* @(RSA14)@ If Token Auth is selected, yet a token is not provided and there is no means to generate a token, then this will result in an error. For example, if only the option @useTokenAuth@ is specified, and a @key@ is not provided, then the client library is unable to authenticate or issue a token
* @(RSA15)@ If Token Auth is selected and @clientId@ has been set in the @ClientOptions@ when the library was instanced:
** @(RSA15a)@ Any @clientId@ provided in @ClientOptions@ must match any non wildcard (@'*'@) @clientId@ value in @TokenDetails@ or @connectionDetails@ of the @CONNECTED@ @ProtocolMessage@, where applicable
Expand Down Expand Up @@ -159,7 +160,7 @@ h3(#rest-auth). Auth
** @(RSA10j)@ Method signature is @authorize(TokenParams, AuthOptions)@. @TokenParams@ and @AuthOptions@ are optional. When the arguments are present, even if empty, the @TokenParams@ and @AuthOptions@ supersede any previously client library configured @TokenParams@ and @AuthOptions@. For example, if a client is initialised with @TokenParams#ttl@ configured with a custom value, and a @TokenParams@ object is passed in as an argument to @#authorize@ with a @null@ or missing value for @ttl@, then the @ttl@ used for every subsequent authorization will be @null@
** @(RSA10b)@ Supports all @AuthOptions@ and @TokenParams@ in the function arguments
** @(RSA10k)@ If the @AuthOption@ argument's @queryTime@ attribute is true, it will obtain the server time once and persist the offset from the local clock. All future token requests generated directly or indirectly via a call to @authorize@ will not obtain the server time, but instead use the local clock offset to calculate the server time. The client library itself MAY internally discard the cached local clock offset in situations in which it may have been invalidated, such as if there is a local change to the date, time, or timezone, of the client device. For clarity however, there is no requirement for this cache invalidation to be available to consumers of the client library API.
** @(RSA10e)@ Adheres to the implementation of @requestToken@ when issuing new tokens
** @(RSA10e)@ If the @authOptions@ contains a way of obtaining a token (an @authCallback@, @authUrl@, or @key@), that should be used to obtain a new token, as per @requestToken@ (@RSA8@). If it contains a token (@token@ or @tokenDetails@), that should be used as-is. If it contains both a token and a way of obtaining a token, the token should be used, with the way of obtaining a token being stored per @RSA10g@ for when the token expires. (Ordering of preference within those groups is not defined and is left up to individual implementations)
Copy link
Contributor

Choose a reason for hiding this comment

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

Nitpick: either "authOptions" or "the AuthOptions". (I prefer the latter since we don't name the arguments in RSA10j, just the types.)

Copy link
Member

Choose a reason for hiding this comment

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

👍 for this change.

** @(RSA10f)@ Returns a @TokenDetails@ object that contains the token string + token metadata
** @(RSA10g)@ Stores the @AuthOptions@ and @TokenParams@ arguments as defaults for subsequent authorisations with the exception of the attributes @TokenParams#timestamp@ and @AuthOptions#queryTime@
** @(RSA10h)@ Will use the value from @Auth#clientId@ by default, if not @null@
Expand Down Expand Up @@ -1019,7 +1020,7 @@ h4. ClientOptions
** @(TO3j)@ Auth option attributes:
*** @(TO3j1)@ @key@ string - Full Ably key string as obtained from dashboard
*** @(TO3j2)@ @token@ string - An authentication token string issued for this application
*** @(TO3j3)@ @tokenDetails@ @TokenDetails@ - An authentication token issued for this application
*** @(TO3j3)@ @tokenDetails@ @TokenDetails@ - An authentication token (token string plus associated details, per @TD1@) issued for this application
*** @(TO3j4)@ @useTokenAuth@ boolean - When true, token authentication will always be used by the client. If @clientId@ is unspecified, then the token issued will inherently be anonymous i.e. it will contain an empty @clientId@
*** @(TO3j5)@ @authCallback@ - A callback to call to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token requests or tokens from another entity, so tokens can be renewed without the client requiring a key
*** @(TO3j6)@ @authUrl@ string - A URL to query to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token request or token from another entity, so tokens can be renewed without the client requiring a key
Expand Down Expand Up @@ -1057,6 +1058,8 @@ h4. AuthOptions
* @(AO1)@ A class providing configurable authentication options used when authenticating or issuing tokens explicitly. These options are used when invoking @Auth#authorize@, @Auth#requestToken@, @Auth#createTokenRequest@ and @Auth#authorize@
* @(AO2)@ The attributes of @AuthOptions@ consist of:
** @(AO2a)@ @key@ string - Full Ably key string, as obtained from dashboard, used when signing token requests locally
** @(AO2h)@ @token@ string - An authentication token string issued for this application
** @(AO2i)@ @tokenDetails@ @TokenDetails@ - An authentication token (token string plus associated details, per @TD1@) issued for this application
** @(AO2b)@ @authCallback@ - A callback to call to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token requests or tokens from another entity, so tokens can be renewed without the client requiring a key
** @(AO2c)@ @authUrl@ string - A URL to query to obtain a signed @TokenRequest@, @TokenDetails@ or a token string. This enables a client to obtain token request or token from another entity, so tokens can be renewed without the client requiring a key
** @(AO2d)@ @authMethod@ - The HTTP verb to be used when a request is made by the library to the @authUrl@. Defaults to @GET@, supports @GET@ and @POST@
Expand Down