From a46acc709aaa7fb6d4b7f4f5ff59c3e3f4810cdd Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Tue, 1 Nov 2016 15:47:11 +0000 Subject: [PATCH 1/3] Clarify RSA10e (Auth#authorize requesting tokens) --- content/client-lib-development-guide/features.textile | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index bfa0e04a34..eb3baa8b2a 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -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@ * @(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 @@ -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) ** @(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@ From dbfcaa51ab720c5389a34f9d8d76b69b437cdade Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Tue, 1 Nov 2016 15:47:51 +0000 Subject: [PATCH 2/3] Add missing token and tokenDetails properties to authOptions --- content/client-lib-development-guide/features.textile | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index eb3baa8b2a..1a4b7027a6 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1058,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 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@ From 0203f19d38b9095b3ec9706532dace0184fb416c Mon Sep 17 00:00:00 2001 From: Simon Woolf Date: Wed, 23 Nov 2016 18:00:00 +0000 Subject: [PATCH 3/3] Clarify TokenDetails --- content/client-lib-development-guide/features.textile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/client-lib-development-guide/features.textile b/content/client-lib-development-guide/features.textile index 1a4b7027a6..ef35e22b31 100644 --- a/content/client-lib-development-guide/features.textile +++ b/content/client-lib-development-guide/features.textile @@ -1020,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 @@ -1059,7 +1059,7 @@ h4. AuthOptions * @(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 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@