Package io.ably.lib.rest

Class Auth

java.lang.Object

io.ably.lib.rest.Auth

public class Auth
extends java.lang.Object

Token-generation and authentication operations for the Ably API. See the Ably Authentication documentation for details of the authentication methods available.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Auth.AuthMethod	Authentication methods
static class	Auth.AuthOptions	Authentication options when instancing the Ably library
static interface	Auth.AuthUpdateResult	An interface providing update result for onAuthUpdated
static interface	Auth.RenewAuthResult	An interface providing completion callbackk for renewAuth
static interface	Auth.TokenCallback	An interface implemented by a callback that provides either tokens, or signed token requests, in response to a request with given token params.
static class	Auth.TokenDetails	A class providing details of a token and its associated metadata, provided when the system successfully requests a token from the system.
static class	Auth.TokenParams	A class providing parameters of a token request.
static class	Auth.TokenRequest	A class providing parameters of a token request.

Field Summary

Fields

Modifier and Type	Field	Description
java.lang.String	clientId	The clientId for this library instance Spec RSA7b
static java.lang.String	WILDCARD_CLIENTID

Method Summary

Modifier and Type	Method	Description
void	assertAuthorizationHeader(boolean forceRenew)	Get the Authorization header, forcing the creation of a new token if requested
Auth.TokenDetails	assertValidToken()
Auth.TokenDetails	authorise(Auth.TokenParams params, Auth.AuthOptions options)	Deprecated.
Auth.TokenDetails	authorize(Auth.TokenParams params, Auth.AuthOptions options)	Ensure valid auth credentials are present.
java.lang.String	checkClientId(BaseMessage msg, boolean allowNullClientId, boolean connected)	Verify that a message, possibly containing a clientId, is compatible with Auth.clientId if it is set
void	clearCachedServerTime()	For testing purposes we need method to clear cached timeDelta
Auth.TokenRequest	createTokenRequest(Auth.TokenParams params, Auth.AuthOptions options)	Create a signed token request based on known credentials and the given token params.
Auth.AuthMethod	getAuthMethod()	Get the authentication method for this library instance.
Auth.AuthOptions	getAuthOptions()	Get (a copy of) auth options currently set in this Auth.
java.lang.String	getAuthorizationHeader()
Param[]	getAuthParams()	Get query params representing the current authentication method and credentials.
java.lang.String	getBasicCredentials()	Get the credentials for HTTP basic auth, if available.
java.lang.String	getEncodedToken()
Auth.TokenDetails	getTokenDetails()
void	onAuthError(ErrorInfo err)
Auth.TokenDetails	renew()	Deprecated. Because the method returns early before renew() completes and does not provide a completion handler for callers.
void	renewAuth(Auth.RenewAuthResult result)	Renew auth credentials.
Auth.TokenDetails	requestToken(Auth.TokenParams params, Auth.AuthOptions tokenOptions)	Make a token request.
long	serverTimestamp()	Using time delta obtained before guess current server time
void	setClientId(java.lang.String clientId)	Set the clientId, after first initialisation in the construction of the library therefore an existing null value is significant - it means that ClientOptions.clientId was null
static long	timestamp()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

clientId

public java.lang.String clientId

The clientId for this library instance Spec RSA7b

WILDCARD_CLIENTID

public static final java.lang.String WILDCARD_CLIENTID

See Also:

Constant Field Values

Method Detail

authorize

public Auth.TokenDetails authorize(Auth.TokenParams params,
                                   Auth.AuthOptions options)
                            throws AblyException

Ensure valid auth credentials are present. This may rely in an already-known and valid token, and will obtain a new token if necessary or explicitly requested. Authorization will use the parameters supplied on construction except where overridden with the options supplied in the call.

Parameters:

params - an object containing the request params: - key: (optional) the key to use; if not specified, the key passed in constructing the Rest interface may be used - ttl: (optional) the requested life of any new token in ms. If none is specified a default of 1 hour is provided. The maximum lifetime is 24hours; any request exceeding that lifetime will be rejected with an error. - capability: (optional) the capability to associate with the access token. If none is specified, a token will be requested with all of the capabilities of the specified key. - clientId: (optional) a client Id to associate with the token - timestamp: (optional) the time in ms since the epoch. If none is specified, the system will be queried for a time value to use. - queryTime (optional) boolean indicating that the Ably system should be queried for the current time when none is specified explicitly.

options -

Throws:

AblyException

authorise

@Deprecated
public Auth.TokenDetails authorise(Auth.TokenParams params,
                                   Auth.AuthOptions options)
                            throws AblyException

Deprecated.

Alias of authorize() (0.9 RSA10l)

Throws:

AblyException

requestToken

public Auth.TokenDetails requestToken(Auth.TokenParams params,
                                      Auth.AuthOptions tokenOptions)
                               throws AblyException

Make a token request. This will make a token request now, even if the library already has a valid token. It would typically be used to issue tokens for use by other clients.

Parameters:

params - : see authorize(io.ably.lib.rest.Auth.TokenParams, io.ably.lib.rest.Auth.AuthOptions) for params

tokenOptions - : see authorize(io.ably.lib.rest.Auth.TokenParams, io.ably.lib.rest.Auth.AuthOptions) for options

Returns:

the TokenDetails

Throws:

AblyException

createTokenRequest

public Auth.TokenRequest createTokenRequest(Auth.TokenParams params,
                                            Auth.AuthOptions options)
                                     throws AblyException

Create a signed token request based on known credentials and the given token params. This would typically be used if creating signed requests for submission by another client.

Parameters:

params - : see authorize(io.ably.lib.rest.Auth.TokenParams, io.ably.lib.rest.Auth.AuthOptions) for params

options - : see authorize(io.ably.lib.rest.Auth.TokenParams, io.ably.lib.rest.Auth.AuthOptions) for options

Returns:

the params augmented with the mac.

Throws:

AblyException

getAuthMethod

public Auth.AuthMethod getAuthMethod()

Get the authentication method for this library instance.

Returns:

getBasicCredentials

public java.lang.String getBasicCredentials()

Get the credentials for HTTP basic auth, if available.

Returns:

getAuthParams

public Param[] getAuthParams()
                      throws AblyException

Get query params representing the current authentication method and credentials.

Returns:

Throws:

AblyException

getAuthOptions

public Auth.AuthOptions getAuthOptions()

Get (a copy of) auth options currently set in this Auth.

renew

@Deprecated
public Auth.TokenDetails renew()
                        throws AblyException

Deprecated.

Because the method returns early before renew() completes and does not provide a completion handler for callers. Please use renewAuth(io.ably.lib.rest.Auth.RenewAuthResult) instead

Renew auth credentials. Will obtain a new token, even if we already have an apparently valid one. Authorization will use the parameters supplied on construction.

Throws:

AblyException

renewAuth

public void renewAuth(Auth.RenewAuthResult result)
               throws AblyException

Renew auth credentials. Will obtain a new token, even if we already have an apparently valid one. Authorization will use the parameters supplied on construction.

Parameters:

result - Asynchronous result the completion Please note that completion callback Auth.RenewAuthResult.onCompletion(boolean, TokenDetails, ErrorInfo) is called on a background thread.

Throws:

AblyException

onAuthError

public void onAuthError(ErrorInfo err)

timestamp

public static long timestamp()

getTokenDetails

public Auth.TokenDetails getTokenDetails()

getEncodedToken

public java.lang.String getEncodedToken()

assertValidToken

public Auth.TokenDetails assertValidToken()
                                   throws AblyException

Throws:

AblyException

assertAuthorizationHeader

public void assertAuthorizationHeader(boolean forceRenew)
                               throws AblyException

Get the Authorization header, forcing the creation of a new token if requested

Parameters:

forceRenew -

Throws:

AblyException

getAuthorizationHeader

public java.lang.String getAuthorizationHeader()

setClientId

public void setClientId(java.lang.String clientId)
                 throws AblyException

Set the clientId, after first initialisation in the construction of the library therefore an existing null value is significant - it means that ClientOptions.clientId was null

Parameters:

clientId -

Throws:

AblyException

checkClientId

public java.lang.String checkClientId(BaseMessage msg,
                                      boolean allowNullClientId,
                                      boolean connected)
                               throws AblyException

Verify that a message, possibly containing a clientId, is compatible with Auth.clientId if it is set

Parameters:

msg -

allowNullClientId - true if it is ok for there to be no resolved clientId

connected - true if connected; if false it is ok for the library to be unidentified

Returns:

the resolved clientId

Throws:

AblyException

serverTimestamp

public long serverTimestamp()

Using time delta obtained before guess current server time

clearCachedServerTime

public void clearCachedServerTime()

For testing purposes we need method to clear cached timeDelta