my-credentials-plugin

Overview

What is it?

This is a custom plugin for Gradle to support storage and retrieval of user-specific credentials under Windows. It provides the following features.

Secure storage of credentials using the Windows Credential Manager.
Methods to retrieve a username and password for use with binary dependency repositories.
Automatic use of credentials for sourceDependencies .
A dialog box to request credentials from the user.
- DSL to specify instructions to be displayed in the dialog box.
- A time-out to prevent the dialog box permanently halting an autobuild machine.

Example build script

Here is an example build script:

buildscript {
    gplugins.use "my-credentials:7.2.5"
}
gplugins.apply()

repositories.ivy {
    credentials {
        username my.username
        password my.password
    }
    url "https://artifactory-server.example-corp.com/artifactory/my-integration-repo/"
}

This will query the Credentials Manager for suitable credentials. If they exist then the username and password will be retrieved and used to configure the repository’s credentials. If no such credentials exist in the Credentials Manager then a dialog box will be displayed, requesting input. Whatever the user enters will be permanently stored in the Credentials Manager. They are stored under an entry labelled "Intrepid - type", where type is the parameter described below. If no argument is supplied, the default is "Intrepid - Domain Credentials".

For example, if your Artifactory server is configured to require encrypted passwords, you could use the following to store that as "Intrepid - Artifactory".

repositories.ivy {
    credentials {
        username my.username("Artifactory")
        password my.password("Artifactory")
    }
    url "https://artifactory-server.example-corp.com/artifactory/my-integration-repo/"
}

If you have multiple repositories, you can apply the same credentials to all of them as follows. The repositories.all method applies the configuration in its block to all repositories, even if they are added later in the script. However, it only applies to repositories for fetching dependencies, defined with the top-level repositories block. It does not apply them to the publishing repository defined in publishPackages.

repositories.all {
    credentials {
        username my.username
        password my.password
    }
}
repositories {
    ivy {
        url "https://artifactory-server.example-corp.com/artifactory/my-integration-repo/"
    }
    ivy {
        url "https://artifactory-server.example-corp.com/artifactory/other-libs-repo/"
    }
}

Source Dependencies

By default the "Domain Credentials" username and password are automatically used for sourceDependencies . From 7.10.0 the credential type can also be set individually for source dependencies. That type is then used as a basis for caching credentials in the Windows Credential Manager for use by Mercurial and Git. See the intrepid plugin documentation for more details.

The Gradle Daemon

By default the Holy Gradle uses the Gradle daemon background process, which will prevent the password dialog being shown. The custom gw.bat in the link:custom-gradle.html distribution will run without the daemon if given the fetchAllDependencies (or fAD) task, but in other cases you may need to run with the --no-daemon argument. If authentication fails multiple times then, depending on your organisation’s IT policies, this may eventually lead to your account being locked.

DSL Guide

username

This property or method will return a username that has previously been entered by the user. If no suitable username exists in the Credentials Manager then a dialog box will be displayed.

If uesd as a method (my.username(type)) this takes one type parameter to allow for different credentials to be used in different situations. When used as a property (my.username) it acts as if calling the method with an argument of "Domain Credentials".

password

This property or method will return a password that has previously been entered by the user. If no suitable password exists in the Credentials Manager then a dialog box will be displayed.

If uesd as a method (my.password(type)) this takes one type parameter to allow for different credentials to be used in different situations. When used as a property (my.password) it acts as if calling the method with an argument of "Domain Credentials".

instructions

This is a container, in which each element corresponds to a credential ‘type’; that is, the parameter passed to the username and password methods. For each credential type, it is possible to add instructions which will be displayed in the dialog, as follows.

my.instructions {
    "Artifactory" {
        add "Visit https://artifactory-server.example-corp.com/artifactory with a web browser."
        add "Log in using your domain username and password."
        add "Click on your username at the top right to visit your user profile."
        add "Enter your password again in the Current Password box, then click Unlock."
        add "Copy the Encrypted Password out of the box."
    }
    "Domain Credentials" {
        add "Enter your usual domain credentials."
        add "Your username should not be prefixed with the domain."
    }
}

The instructions for "Domain Credentials" above will be displayed for use of username or password as properties. This is used automatically by the intrepid-plugin when supplying passwords for sourceDependencies.

The "Artifactory" credentials are not used automatically, but are typically used as shown in Example build script.

If no instructions are set, default instructions will be shown.

Updating Credentials

If your password changes, you can run credential-store.exe as a quick way to update the entries in the Windows Credential Manager. This program is automatically downloaded into your project directory the first time you use the Holy Gradle.

Before 7.10.0

Run it with no arguments and it will show you the command line options, then prompt you for your new password. It will automatically replace all Mercurial credentials with this new password. For any credentials stored under Intrepid - type keys, it will prompt you for each one; you should answer y for "Intrepid - Domain Credentials".

If your Artifactory server requires an encrypted password, you should answer n when prompted for "Intrepid - Artifactory", then run it again as follows.

credential-store "Intrepid - Artifactory" "_username_" "_password_"

Since 7.10.0

To support using different "Intrepid - type" credentials as a basis for different source repositories, credential-store.exe has changed. It reads a file holygradle/credential-bases.txt in your Gradle user home folder, which contains a mapping from credential types to other source dependency credentials which are based on that type. The intrepid plugin updates this file when it fetches source dependencies.

Running credential-store.exe it with no arguments will now output a usage message. Usage is basically as follows.

Updating default "Domain Credentials" and credentials based on that

To update the default "Domain Credentials" type, run the following command.

credential-store for-default

This will prompt you for your username and password, store them as the "Intrepid - Domain Credentials", then also use that to update

cached credentials for Git and Mercurial which are not connected to any specific credential type as a basis; and
any "Intrepid - type" credentials which are not used as a basis for other cached credentials.

Updating other Credential types and credentials based on those

To update other basis credential types, run

credential-store for-basis _type_

where _type_ is the name of the credential type used as a basis.

Updating Individual Credentials

If you need to update a single credential to something different you can run the following command, slightly different from before 7.10.0.

credential-store set "Intrepid - Artifactory" "_username_" "_password_"