Set Up Credentials

MMT talks to your store through the JSON API. A credential tells it the store’s API URL and how to sign in: with an API token or with an admin user’s SSH key. You add a credential once, give it a name, and every remote that uses that name connects with it.

API token#

Create the token#

1. In the admin, go to Settings > User Management > API Tokens and add a token.

2. Set it up:

   Setting	For MMT
   Name	Any name, such as MMT
   Access Token	Copy it; MMT calls it the token
   Allowed IP Address(es)	The addresses you’ll run MMT from. 0.0.0.0/0 (and ::/0 for IPv6) allows any address, which isn’t recommended.
   Signature	Required. MMT signs every request with HMAC-SHA256 and won’t accept a token without a signing key. Copy the signing key.
   Timestamp	Either setting works, because MMT always sends a timestamp. Requiring it is safer.

3. Give the token permission to the functions MMT uses. Select the token in the list, open Groups, and assign the User Interface group, which covers everything MMT does. To limit the token, assign only the functions below under Functions instead.

MMT calls these JSON API functions:

A token with only the list and load functions can check out and pull but not push or manage branches.

Add the credential#

mmt credential add -u https://www.example.com/mm5/json.mvc -t YOUR_ACCESS_TOKEN -s YOUR_SIGNING_KEY mystore

mystore is the name you’ll use for this credential. Use the signing key exactly as the admin shows it.

SSH key#

SSH requests are made as an admin user, so changesets show that user’s name. The user must not be locked out, and its password can’t be expired or due to be changed.

Create a key and add it to your user#

1. Create an RSA key. Miva accepts only RSA keys, not DSA, ECDSA or ed25519:

   ssh-keygen -t rsa -m pem
   

   This writes a private key and a public key (the .pub file).

2. In the admin, open Edit Profile > Manage SSH Authentication and add the contents of the .pub file.

Add the credential#

mmt credential add -u https://www.example.com/mm5/json.mvc -n your_admin_username -k ~/.ssh/id_rsa mystore-ssh

-k is the path to the private key. MMT saves the path, not the key, so don’t move the file afterwards.

If the key has a passphrase, MMT asks for it every time it connects, with three tries. It doesn’t use ssh-agent.

Add the public key with provisioning#

To save a step when setting up a store, add the public key with an XML provisioning file. SSHAuthentication takes the whole line from the .pub file. Provisioning checks the key and stops with an SSHAuthentication: error if it can’t read it.

To add the key to an admin user that already exists:

<Provision>
    <Domain>
        <User_Update name="MIVA_USERNAME">
            <SSHAuthentication>ssh-rsa AAAA... [email protected]</SSHAuthentication>
        </User_Update>
    </Domain>
</Provision>

To create a new admin user with the key:

<Provision>
    <Domain>
        <User_Add>
            <Name>MIVA_USERNAME</Name>
            <Password>SECURE_PASSWORD_HERE</Password>
            <Email>[email protected]</Email>
            <Administrator>Yes</Administrator>
            <ForcePasswordChange>No</ForcePasswordChange>
            <SSHAuthentication>ssh-rsa AAAA... [email protected]</SSHAuthentication>
            <!-- Optional. type: none, totp, yubicloud or webauthn -->
            <TwoFactorAuthentication type="totp">
                <TOTPKey>YOUR_BASE32_TOTP_KEY</TOTPKey>
            </TwoFactorAuthentication>
        </User_Add>
    </Domain>
</Provision>

• User_Add fails if a user with that name exists. Use User_Update for existing users.
• Leave ForcePasswordChange off or set to No: MMT can’t sign in as a user whose password has to be changed.
• The two-factor settings go inside TwoFactorAuthentication: TOTPKey for totp, YubiKeyID for yubicloud, and WebAuthn_KeyID and WebAuthn_PublicKey for webauthn. Leave the tag out to set up two-factor authentication at first sign-in.

User_Add and User_Update are domain tags, so the admin’s Import Data and Settings in XML Provisioning Format skips them. Run them with the Provision_Domain JSON API function. A provisioning file on the server only runs if Miva has signed it; see Provisioning file on the server.

<Provision oncomplete="delete">
    <Domain>
        <User_Add>
            <Name>MIVA_USERNAME</Name>
            <Password>SECURE_PASSWORD_HERE</Password>
            <Email>YOUR_EMAIL</Email>
            <!-- If using 2FA, possible types: totp, yubicloud -->
            <TwoFactorAuthentication type="yubicloud">
                <YubiKeyID>YOUR_YUBIKEY_ID_FIRST_12_CHARACTERS</YubiKeyID>
            </TwoFactorAuthentication>
            <TOTPKey></TOTPKey>
            <DefaultPagination>1000</DefaultPagination>
            <Administrator>1</Administrator>
            <SSHAuthentication>ssh-rsa xxxxxxxxxxxxxxxxxxx ... </SSHAuthentication>
        </User_Add>
    </Domain>
</Provision>

Stores behind HTTP basic authentication#

If the store (often a development store) asks for a login before you reach it, add it to either kind of credential with -m. MMT asks for the password if you leave out -w:

mmt credential add -u https://dev.example.com/mm5/json.mvc -t YOUR_ACCESS_TOKEN -s YOUR_SIGNING_KEY -m dev_login mystore-dev

Where credentials are stored#

MMT saves credentials, remotes and settings in config.json in a .mmt folder in your home folder (~/.mmt/config.json; on Windows, %USERPROFILE%\.mmt\config.json).

mmt credential list shows your credentials. It prints API tokens in plain text but never signing keys or passwords.

Next step#

Make your first checkout