Auth (Taskcluster Client (java port) 1.0.5 API)

java.lang.Object
- org.mozilla.taskcluster.client.TaskClusterRequestHandler
- - org.mozilla.taskcluster.client.auth.Auth

```
public class Auth
extends TaskClusterRequestHandler
```
Authentication related API end-points for TaskCluster and related services. These API end-points are of interest if you wish to: * Authenticate request signed with TaskCluster credentials, * Manage clients and roles, * Inspect or audit clients and roles, * Gain access to various services guarded by this API.
Clients
The authentication service manages clients, at a high-level each client consists of a clientId, an accessToken, expiration and description. The clientId and accessToken can be used for authentication when calling TaskCluster APIs.
Each client is assigned a single scope on the form: assume:client-id:<clientId>, this scope doesn’t really do much on its own. But when you dive into the roles section you’ll see that you can create a role: client-id:<clientId> that assigns scopes to the client. This way it’s easy to audit all scope assignments, by only listing roles.
Roles
A role consists of a roleId, a set of scopes and a description. Each role constitutes a simple expansion rule that says if you have the scope: assume:<roleId> you get the set of scopes the role has. Think of the assume:<roleId> as a scope that allows a client to assume a role.
As in scopes the * kleene star also have special meaning if it is located at the end of a roleId. If you have a role with the following roleId: my-prefix*, then any client which has a scope staring with assume:my-prefix will be allowed to assume the role.
As previously mentioned each client gets the scope: assume:client-id:<clientId>, it trivially follows that you can create a role with the roleId: client-id:<clientId> to assign additional scopes to a client. You can also create a role client-id:user-* if you wish to assign a set of scopes to all clients whose clientId starts with user-.
Guarded Services
The authentication service also has API end-points for delegating access to some guarded service such as AWS S3, or Azure Table Storage. Generally, we add API end-points to this server when we wish to use TaskCluster credentials to grant access to a third-party service used by many TaskCluster components.
See: http://docs.taskcluster.net/auth/api-docs

Field Summary

Fields
Modifier and Type Field and Description

protected static String defaultBaseURL

Fields
Modifier and Type	Field and Description
`protected static String`	`defaultBaseURL`

Constructor Summary

Constructors
Constructor and Description
`Auth()`
`Auth(String baseURL)`
`Auth(String clientId, String accessToken)`
`Auth(String clientId, String accessToken, String certificate)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`CallSummary<HawkSignatureAuthenticationRequest,Object>`	`authenticateHawk(HawkSignatureAuthenticationRequest payload)` Validate the request signature given on input and return list of scopes that the authenticating client has.
`CallSummary<EmptyPayload,AWSS3CredentialsResponse>`	`awsS3Credentials(String level, String bucket, String prefix)` Get temporary AWS credentials for `read-write` or `read-only` access to a given `bucket` and `prefix` within that bucket.
`CallSummary<EmptyPayload,AzureSharedAccessSignatureResponse>`	`azureTableSAS(String account, String table)` Get a shared access signature (SAS) string for use with a specific Azure Table Storage table.
`CallSummary<EmptyPayload,GetClientResponse>`	`client(String clientId)` Get information about a single client.
`CallSummary<CreateClientRequest,CreateClientResponse>`	`createClient(String clientId, CreateClientRequest payload)` Create a new client and get the `accessToken` for this client.
`CallSummary<CreateRoleRequest,GetRoleResponse>`	`createRole(String roleId, CreateRoleRequest payload)` Create a new role.
`CallSummary<EmptyPayload,EmptyPayload>`	`deleteClient(String clientId)` Delete a client, please note that any roles related to this client must be deleted independently.
`CallSummary<EmptyPayload,EmptyPayload>`	`deleteRole(String roleId)` Delete a role.
`CallSummary<ExportedClients,EmptyPayload>`	`importClients(ExportedClients payload)` Import client from JSON list, overwriting any clients that already exists.
`CallSummary<EmptyPayload,GetClientResponse[]>`	`listClients()` Get a list of all clients.
`CallSummary<EmptyPayload,GetRoleResponse[]>`	`listRoles()` Get a list of all roles, each role object also includes the list of scopes it expands to.
`CallSummary<EmptyPayload,EmptyPayload>`	`ping()` Documented later…
`CallSummary<EmptyPayload,CreateClientResponse>`	`resetAccessToken(String clientId)` Reset a clients `accessToken`, this will revoke the existing `accessToken`, generate a new `accessToken` and return it from this call.
`CallSummary<EmptyPayload,GetRoleResponse>`	`role(String roleId)` Get information about a single role, including the set of scopes that the role expands to.
`CallSummary<CreateClientRequest,GetClientResponse>`	`updateClient(String clientId, CreateClientRequest payload)` Update an exisiting client.
`CallSummary<CreateRoleRequest,GetRoleResponse>`	`updateRole(String roleId, CreateRoleRequest payload)` Update existing role.

Methods inherited from class org.mozilla.taskcluster.client.TaskClusterRequestHandler
apiCall, configureHawk, setBaseURL, uriEncode

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - defaultBaseURL
```
protected static final String defaultBaseURL
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - Auth
```
public Auth(String clientId,
            String accessToken)
```
  - Auth
```
public Auth(String clientId,
            String accessToken,
            String certificate)
```
  - Auth
```
public Auth(String baseURL)
```
  - Auth
```
public Auth()
```
- Method Detail
  - listClients
```
public CallSummary<EmptyPayload,GetClientResponse[]> listClients()
                                                          throws APICallFailure
```
    Get a list of all clients.
    See http://docs.taskcluster.net/auth/api-docs/#listClients
    
    Throws:
    
    APICallFailure
  - client
```
public CallSummary<EmptyPayload,GetClientResponse> client(String clientId)
                                                   throws APICallFailure
```
    Get information about a single client.
    See http://docs.taskcluster.net/auth/api-docs/#client
    
    Throws:
    
    APICallFailure
  - createClient
```
public CallSummary<CreateClientRequest,CreateClientResponse> createClient(String clientId,
                                                                          CreateClientRequest payload)
                                                                   throws APICallFailure
```
    Create a new client and get the accessToken for this client. You should store the accessToken from this API call as there is no other way to retrieve it.
    If you loose the accessToken you can call resetAccessToken to reset it, and a new accessToken will be returned, but you cannot retrieve the current accessToken.
    If a client with the same clientId already exists this operation will fail. Use updateClient if you wish to update an existing client.
    See http://docs.taskcluster.net/auth/api-docs/#createClient
    
    Throws:
    
    APICallFailure
  - resetAccessToken
```
public CallSummary<EmptyPayload,CreateClientResponse> resetAccessToken(String clientId)
                                                                throws APICallFailure
```
    Reset a clients accessToken, this will revoke the existing accessToken, generate a new accessToken and return it from this call.
    There is no way to retrieve an existing accessToken, so if you loose it you must reset the accessToken to acquire it again.
    See http://docs.taskcluster.net/auth/api-docs/#resetAccessToken
    
    Throws:
    
    APICallFailure
  - updateClient
```
public CallSummary<CreateClientRequest,GetClientResponse> updateClient(String clientId,
                                                                       CreateClientRequest payload)
                                                                throws APICallFailure
```
    Update an exisiting client. This is really only useful for changing the description and expiration, as you won’t be allowed to the clientId or accessToken.
    See http://docs.taskcluster.net/auth/api-docs/#updateClient
    
    Throws:
    
    APICallFailure
  - deleteClient
```
public CallSummary<EmptyPayload,EmptyPayload> deleteClient(String clientId)
                                                    throws APICallFailure
```
    Delete a client, please note that any roles related to this client must be deleted independently.
    See http://docs.taskcluster.net/auth/api-docs/#deleteClient
    
    Throws:
    
    APICallFailure
  - listRoles
```
public CallSummary<EmptyPayload,GetRoleResponse[]> listRoles()
                                                      throws APICallFailure
```
    Get a list of all roles, each role object also includes the list of scopes it expands to.
    See http://docs.taskcluster.net/auth/api-docs/#listRoles
    
    Throws:
    
    APICallFailure
  - role
```
public CallSummary<EmptyPayload,GetRoleResponse> role(String roleId)
                                               throws APICallFailure
```
    Get information about a single role, including the set of scopes that the role expands to.
    See http://docs.taskcluster.net/auth/api-docs/#role
    
    Throws:
    
    APICallFailure
  - createRole
```
public CallSummary<CreateRoleRequest,GetRoleResponse> createRole(String roleId,
                                                                 CreateRoleRequest payload)
                                                          throws APICallFailure
```
    Create a new role. If there already exists a role with the same roleId this operation will fail. Use updateRole to modify an existing role
    See http://docs.taskcluster.net/auth/api-docs/#createRole
    
    Throws:
    
    APICallFailure
  - updateRole
```
public CallSummary<CreateRoleRequest,GetRoleResponse> updateRole(String roleId,
                                                                 CreateRoleRequest payload)
                                                          throws APICallFailure
```
    Update existing role.
    See http://docs.taskcluster.net/auth/api-docs/#updateRole
    
    Throws:
    
    APICallFailure
  - deleteRole
```
public CallSummary<EmptyPayload,EmptyPayload> deleteRole(String roleId)
                                                  throws APICallFailure
```
    Delete a role. This operation will succeed regardless of whether or not the role exists.
    See http://docs.taskcluster.net/auth/api-docs/#deleteRole
    
    Throws:
    
    APICallFailure
  - awsS3Credentials
```
public CallSummary<EmptyPayload,AWSS3CredentialsResponse> awsS3Credentials(String level,
                                                                           String bucket,
                                                                           String prefix)
                                                                    throws APICallFailure
```
    Get temporary AWS credentials for read-write or read-only access to a given bucket and prefix within that bucket. The level parameter can be read-write or read-only and determines which type of credentials are returned. Please note that the level parameter is required in the scope guarding access.
    The credentials are set to expire after an hour, but this behavior is subject to change. Hence, you should always read the expires property from the response, if you intend to maintain active credentials in your application.
    Please note that your prefix may not start with slash /. Such a prefix is allowed on S3, but we forbid it here to discourage bad behavior.
    Also note that if your prefix doesn’t end in a slash /, the STS credentials may allow access to unexpected keys, as S3 does not treat slashes specially. For example, a prefix of my-folder will allow access to my-folder/file.txt as expected, but also to my-folder.txt, which may not be intended.
    See http://docs.taskcluster.net/auth/api-docs/#awsS3Credentials
    
    Throws:
    
    APICallFailure
  - azureTableSAS
```
public CallSummary<EmptyPayload,AzureSharedAccessSignatureResponse> azureTableSAS(String account,
                                                                                  String table)
                                                                           throws APICallFailure
```
    Get a shared access signature (SAS) string for use with a specific Azure Table Storage table. Note, this will create the table, if it doesn’t already exist.
    See http://docs.taskcluster.net/auth/api-docs/#azureTableSAS
    
    Throws:
    
    APICallFailure
  - authenticateHawk
```
public CallSummary<HawkSignatureAuthenticationRequest,Object> authenticateHawk(HawkSignatureAuthenticationRequest payload)
                                                                        throws APICallFailure
```
    Validate the request signature given on input and return list of scopes that the authenticating client has.
    This method is used by other services that wish rely on TaskCluster credentials for authentication. This way we can use Hawk without having the secret credentials leave this service.
    See http://docs.taskcluster.net/auth/api-docs/#authenticateHawk
    
    Throws:
    
    APICallFailure
  - importClients
```
public CallSummary<ExportedClients,EmptyPayload> importClients(ExportedClients payload)
                                                        throws APICallFailure
```
    Import client from JSON list, overwriting any clients that already exists. Returns a list of all clients imported.
    See http://docs.taskcluster.net/auth/api-docs/#importClients
    
    Throws:
    
    APICallFailure
  - ping
```
public CallSummary<EmptyPayload,EmptyPayload> ping()
                                            throws APICallFailure
```
    Documented later…
    Warning this api end-point is not stable.
    See http://docs.taskcluster.net/auth/api-docs/#ping
    
    Throws:
    
    APICallFailure

Class Auth

Clients

Roles

Guarded Services

Field Summary

Constructor Summary

Method Summary

Methods inherited from class org.mozilla.taskcluster.client.TaskClusterRequestHandler

Methods inherited from class java.lang.Object

Field Detail

defaultBaseURL

Constructor Detail

Auth

Auth

Auth

Auth

Method Detail

listClients

client

createClient

resetAccessToken

updateClient

deleteClient

listRoles

role

createRole

updateRole

deleteRole

awsS3Credentials

azureTableSAS

authenticateHawk

importClients

ping