Auth (Taskcluster Client (java port) 1.0.311 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: * Authorize a request signed with Taskcluster credentials, * Manage clients and roles, * Inspect or audit clients and roles, * Gain access to various services guarded by this API.
Note that in this service “authentication” refers to validating the correctness of the supplied credentials (that the caller posesses the appropriate access token). This service does not provide any kind of user authentication (identifying a particular person).
Clients
The authentication service manages clients, at a high-level each client consists of a clientId, an accessToken, scopes, and some metadata. The clientId and accessToken can be used for authentication when calling Taskcluster APIs.
The client’s scopes control the client’s access to Taskcluster resources. The scopes are expanded by substituting roles, as defined below.
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.
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 Also:

Auth API Documentation

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(Credentials credentials)`
`Auth(Credentials credentials, String baseURL)`
`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,AzureListAccountResponse>`	`azureAccounts()` Retrieve a list of all Azure accounts managed by Taskcluster Auth.
`CallSummary<EmptyPayload,AzureListContainersResponse>`	`azureContainers(String account)` Retrieve a list of all containers in an account.
`CallSummary<EmptyPayload,AzureBlobSharedAccessSignature>`	`azureContainerSAS(String account, String container, String level)` Get a shared access signature (SAS) string for use with a specific Azure Blob Storage container.
`CallSummary<EmptyPayload,AzureListTableResponse>`	`azureTables(String account)` Retrieve a list of all tables in an account.
`CallSummary<EmptyPayload,AzureTableSharedAccessSignature>`	`azureTableSAS(String account, String table, String level)` 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,SetOfScopes>`	`currentScopes()` Return the expanded scopes available in the request, taking into account all sources of scopes and scope restrictions (temporary credentials, assumeScopes, client scopes, and roles).
`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<EmptyPayload,GetClientResponse>`	`disableClient(String clientId)` Disable a client.
`CallSummary<EmptyPayload,GetClientResponse>`	`enableClient(String clientId)` Enable a client that was disabled with `disableClient`.
`CallSummary<SetOfScopes,SetOfScopes>`	`expandScopes(SetOfScopes payload)` Return an expanded copy of the given scopeset, with scopes implied by any roles included.
`CallSummary<SetOfScopes,SetOfScopes>`	`expandScopesGet(SetOfScopes payload)` Return an expanded copy of the given scopeset, with scopes implied by any roles included.
`CallSummary<EmptyPayload,ListClientResponse>`	`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()` Respond without doing anything.
`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<EmptyPayload,SentryDSNResponse>`	`sentryDSN(String project)` Get temporary DSN (access credentials) for a sentry project.
`CallSummary<EmptyPayload,StatsumTokenResponse>`	`statsumToken(String project)` Get temporary `token` and `baseUrl` for sending metrics to statsum.
`CallSummary<TestAuthenticateRequest,TestAuthenticateResponse>`	`testAuthenticate(TestAuthenticateRequest payload)` Utility method to test client implementations of Taskcluster authentication.
`CallSummary<EmptyPayload,TestAuthenticateResponse>`	`testAuthenticateGet()` Utility method similar to `testAuthenticate`, but with the GET method, so it can be used with signed URLs (bewits).
`CallSummary<CreateClientRequest,GetClientResponse>`	`updateClient(String clientId, CreateClientRequest payload)` Update an exisiting client.
`CallSummary<CreateRoleRequest,GetRoleResponse>`	`updateRole(String roleId, CreateRoleRequest payload)` Update an existing role.
`CallSummary<EmptyPayload,WebhooktunnelTokenResponse>`	`webhooktunnelToken()` Get temporary `token` and `id` for connecting to webhooktunnel The token is valid for 96 hours, clients should refresh after expiration.

Methods inherited from class org.mozilla.taskcluster.client.TaskclusterRequestHandler
apiCall, 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(Credentials credentials)
```
  - Auth
```
public Auth(Credentials credentials,
            String baseURL)
```
  - 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
  - ping
```
public CallSummary<EmptyPayload,EmptyPayload> ping()
                                            throws APICallFailure
```
    Respond without doing anything. This endpoint is used to check that the service is up.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Ping Server API Documentation
  - listClients
```
public CallSummary<EmptyPayload,ListClientResponse> listClients()
                                                         throws APICallFailure
```
    Get a list of all clients. With prefix, only clients for which it is a prefix of the clientId are returned.
    By default this end-point will try to return up to 1000 clients in one request. But it may return less, even none. It may also return a continuationToken even though there are no more results. However, you can only be sure to have seen all results if you keep calling listClients with the last continuationToken until you get a result without a continuationToken.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    List Clients API Documentation
  - client
```
public CallSummary<EmptyPayload,GetClientResponse> client(String clientId)
                                                   throws APICallFailure
```
    Get information about a single client.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Get Client API Documentation
  - 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.
    The caller’s scopes must satisfy scopes.
    Required scopes: All of: * auth:create-client: * For scope in scopes each
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Create Client API Documentation
  - 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.
    Required scopes: auth:reset-access-token:
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Reset `accessToken` API Documentation
  - updateClient
```
public CallSummary<CreateClientRequest,GetClientResponse> updateClient(String clientId,
                                                                       CreateClientRequest payload)
                                                                throws APICallFailure
```
    Update an exisiting client. The clientId and accessToken cannot be updated, but scopes can be modified. The caller’s scopes must satisfy all scopes being added to the client in the update operation. If no scopes are given in the request, the client’s scopes remain unchanged
    Required scopes: All of: * auth:update-client: * For scope in scopesAdded each
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Update Client API Documentation
  - enableClient
```
public CallSummary<EmptyPayload,GetClientResponse> enableClient(String clientId)
                                                         throws APICallFailure
```
    Enable a client that was disabled with disableClient. If the client is already enabled, this does nothing.
    This is typically used by identity providers to re-enable clients that had been disabled when the corresponding identity’s scopes changed.
    Required scopes: auth:enable-client:
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Enable Client API Documentation
  - disableClient
```
public CallSummary<EmptyPayload,GetClientResponse> disableClient(String clientId)
                                                          throws APICallFailure
```
    Disable a client. If the client is already disabled, this does nothing.
    This is typically used by identity providers to disable clients when the corresponding identity’s scopes no longer satisfy the client’s scopes.
    Required scopes: auth:disable-client:
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Disable Client API Documentation
  - 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.
    Required scopes: auth:delete-client:
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Delete Client API Documentation
  - 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.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    List Roles API Documentation
  - 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.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Get Role API Documentation
  - createRole
```
public CallSummary<CreateRoleRequest,GetRoleResponse> createRole(String roleId,
                                                                 CreateRoleRequest payload)
                                                          throws APICallFailure
```
    Create a new role.
    The caller’s scopes must satisfy the new role’s scopes.
    If there already exists a role with the same roleId this operation will fail. Use updateRole to modify an existing role.
    Creation of a role that will generate an infinite expansion will result in an error response.
    Required scopes: All of: * auth:create-role: * For scope in scopes each
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Create Role API Documentation
  - updateRole
```
public CallSummary<CreateRoleRequest,GetRoleResponse> updateRole(String roleId,
                                                                 CreateRoleRequest payload)
                                                          throws APICallFailure
```
    Update an existing role.
    The caller’s scopes must satisfy all of the new scopes being added, but need not satisfy all of the client’s existing scopes.
    An update of a role that will generate an infinite expansion will result in an error response.
    Required scopes: All of: * auth:update-role: * For scope in scopesAdded each
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Update Role API Documentation
  - 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.
    Required scopes: auth:delete-role:
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Delete Role API Documentation
  - expandScopesGet
```
public CallSummary<SetOfScopes,SetOfScopes> expandScopesGet(SetOfScopes payload)
                                                     throws APICallFailure
```
    Return an expanded copy of the given scopeset, with scopes implied by any roles included.
    This call uses the GET method with an HTTP body. It remains only for backward compatibility.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Expand Scopes API Documentation
  - expandScopes
```
public CallSummary<SetOfScopes,SetOfScopes> expandScopes(SetOfScopes payload)
                                                  throws APICallFailure
```
    Return an expanded copy of the given scopeset, with scopes implied by any roles included.
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Expand Scopes API Documentation
  - currentScopes
```
public CallSummary<EmptyPayload,SetOfScopes> currentScopes()
                                                    throws APICallFailure
```
    Return the expanded scopes available in the request, taking into account all sources of scopes and scope restrictions (temporary credentials, assumeScopes, client scopes, and roles).
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Get Current Scopes API Documentation
  - 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 bucket name must not contain ., as recommended by Amazon.
    This method can only allow access to a whitelisted set of buckets. To add a bucket to that whitelist, contact the Taskcluster team, who will add it to the appropriate IAM policy. If the bucket is in a different AWS account, you will also need to add a bucket policy allowing access from the Taskcluster account. That policy should look like this:
```
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "allow-taskcluster-auth-to-delegate-access",
      "Effect": "Allow",
      "Principal": {
        "AWS": "arn:aws:iam::692406183521:root"
      },
      "Action": [
        "s3:ListBucket",
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:GetBucketLocation"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket>",
        "arn:aws:s3:::<bucket>/*"
      ]
    }
  ]
}
```
    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.
    Finally, note that the PutObjectAcl call is not allowed. Passing a canned ACL other than private to PutObject is treated as a PutObjectAcl call, and will result in an access-denied error from AWS. This limitation is due to a security flaw in Amazon S3 which might otherwise allow indefinite access to uploaded objects.
    EC2 metadata compatibility, if the querystring parameter ?format=iam-role-compat is given, the response will be compatible with the JSON exposed by the EC2 metadata service. This aims to ease compatibility for libraries and tools built to auto-refresh credentials. For details on the format returned by EC2 metadata service see: EC2 User Guide.
    Required scopes: If levelIsReadOnly: Any of: - auth:aws-s3:read-only:/ - auth:aws-s3:read-write:/
    Throws:
    
    APICallFailure
    
    See Also:
    
    Get Temporary Read/Write Credentials S3 API Documentation
  - azureAccounts
```
public CallSummary<EmptyPayload,AzureListAccountResponse> azureAccounts()
                                                                 throws APICallFailure
```
    Retrieve a list of all Azure accounts managed by Taskcluster Auth.
    Required scopes: auth:azure-table:list-accounts
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    List Accounts Managed by Auth API Documentation
  - azureTables
```
public CallSummary<EmptyPayload,AzureListTableResponse> azureTables(String account)
                                                             throws APICallFailure
```
    Retrieve a list of all tables in an account.
    Required scopes: auth:azure-table:list-tables:
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    List Tables in an Account Managed by Auth API Documentation
  - azureTableSAS
```
public CallSummary<EmptyPayload,AzureTableSharedAccessSignature> azureTableSAS(String account,
                                                                               String table,
                                                                               String level)
                                                                        throws APICallFailure
```
    Get a shared access signature (SAS) string for use with a specific Azure Table Storage table.
    The level parameter can be read-write or read-only and determines which type of credentials are returned. If level is read-write, it will create the table if it doesn’t already exist.
    Required scopes: If levelIsReadOnly: Any of: - auth:azure-table:read-only:/
    - auth:azure-table:read-write:/
    
    Throws:
    
    APICallFailure
    
    See Also:
    
    Get Shared-Access-Signature for Azure Table API Documentation
    - azureContainers
      
      public CallSummary<EmptyPayload,AzureListContainersResponse> azureContainers(String account) throws APICallFailure
      
      Retrieve a list of all containers in an account.
      Required scopes: auth:azure-container:list-containers:
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      List containers in an Account Managed by Auth API Documentation
    - azureContainerSAS
      
      public CallSummary<EmptyPayload,AzureBlobSharedAccessSignature> azureContainerSAS(String account, String container, String level) throws APICallFailure
      
      Get a shared access signature (SAS) string for use with a specific Azure Blob Storage container.
      The level parameter can be read-write or read-only and determines which type of credentials are returned. If level is read-write, it will create the container if it doesn’t already exist.
      Required scopes: If levelIsReadOnly: Any of: - auth:azure-container:read-only:/ - auth:azure-container:read-write:/
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      Get Shared-Access-Signature for Azure Container API Documentation
    - sentryDSN
      
      public CallSummary<EmptyPayload,SentryDSNResponse> sentryDSN(String project) throws APICallFailure
      
      Get temporary DSN (access credentials) for a sentry project. The credentials returned can be used with any Sentry client for up to 24 hours, after which the credentials will be automatically disabled.
      If the project doesn’t exist it will be created, and assigned to the initial team configured for this component. Contact a Sentry admin to have the project transferred to a team you have access to if needed
      Required scopes: auth:sentry:
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      Get DSN for Sentry Project API Documentation
    - statsumToken
      
      public CallSummary<EmptyPayload,StatsumTokenResponse> statsumToken(String project) throws APICallFailure
      
      Get temporary token and baseUrl for sending metrics to statsum.
      The token is valid for 24 hours, clients should refresh after expiration.
      Required scopes: auth:statsum:
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      Get Token for Statsum Project API Documentation
    - webhooktunnelToken
      
      public CallSummary<EmptyPayload,WebhooktunnelTokenResponse> webhooktunnelToken() throws APICallFailure
      
      Get temporary token and id for connecting to webhooktunnel The token is valid for 96 hours, clients should refresh after expiration.
      Required scopes: auth:webhooktunnel
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      Get Token for Webhooktunnel Proxy API Documentation
    - 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.
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      Authenticate Hawk Request API Documentation
    - testAuthenticate
      
      public CallSummary<TestAuthenticateRequest,TestAuthenticateResponse> testAuthenticate(TestAuthenticateRequest payload) throws APICallFailure
      
      Utility method to test client implementations of Taskcluster authentication.
      Rather than using real credentials, this endpoint accepts requests with clientId tester and accessToken no-secret. That client’s scopes are based on clientScopes in the request body.
      The request is validated, with any certificate, authorizedScopes, etc. applied, and the resulting scopes are checked against requiredScopes from the request body. On success, the response contains the clientId and scopes as seen by the API method.
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      Test Authentication API Documentation
    - testAuthenticateGet
      
      public CallSummary<EmptyPayload,TestAuthenticateResponse> testAuthenticateGet() throws APICallFailure
      
      Utility method similar to testAuthenticate, but with the GET method, so it can be used with signed URLs (bewits).
      Rather than using real credentials, this endpoint accepts requests with clientId tester and accessToken no-secret. That client’s scopes are ['test:*', 'auth:create-client:test:*']. The call fails if the test:authenticate-get scope is not available.
      The request is validated, with any certificate, authorizedScopes, etc. applied, and the resulting scopes are checked, just like any API call. On success, the response contains the clientId and scopes as seen by the API method.
      This method may later be extended to allow specification of client and required scopes via query arguments.
      
      Throws:
      
      APICallFailure
      
      See Also:
      
      "[Test Authentication (GET) API Documentation](https://docs.taskcluster.net/reference/platform/auth/api-docs#testAuthenticateGet)"
    Skip navigation links
    
    Overview
    
    Package
    
    Class
    
    Use
    
    Tree
    
    Deprecated
    
    Index
    
    Help
    Prev Class
    
    Next Class
    
    Frames
    
    No Frames
    
    All Classes
    
    Summary:
    
    Nested |
    
    Field |
    
    Constr |
    
    Method
    
    Detail:
    
    Field |
    
    Constr |
    
    Method
    Copyright © 2014–2018 Mozilla. All rights reserved.

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

Auth

Auth

Method Detail

ping

listClients

client

createClient

resetAccessToken

updateClient

enableClient

disableClient

deleteClient

listRoles

role

createRole

updateRole

deleteRole

expandScopesGet

expandScopes

currentScopes

awsS3Credentials

azureAccounts

azureTables

azureTableSAS

azureContainers

azureContainerSAS

sentryDSN

statsumToken

webhooktunnelToken

authenticateHawk

testAuthenticate

testAuthenticateGet