To use Moonshot, the user's device needs to have a way of storing and selecting credentials to use to authenticate to a service. One option to achieve this is to use the Moonshot Identity Selector.

Contents

Manual configuration of the Moonshot Identity Selection is only appropriate for power users.

1. What is the Moonshot Identity Selector?

The Moonshot Identity Selector is a central point from which you can manage your credentials to be used by Moonshot.

2. Managing credentials Using the Moonshot Identity Selector

The main way of interacting with the Moonshot Identity Selector is through a UI. There are two variants, one for X environments (GTK UI) and one for text-only environments (TXT UI). They provide the same functionality and have a similar layout. It can also be used in a headless mode or have identity information deployed to it - see this page for enterprise deployment options.

2.1. Loading the Identity Selector

Normally, there is no need to manually load the identity selector - it is invoked automatically when you try to log in to a moonshot-enabled service. If you need to modify and remove an existing identity (or manually add an identity), then you will manually load it. To do this, you can either:

Locate the Moonshot Identity Manager in the Administration menu of your desktop and click on it.
or
Open a terminal window and type "moonshot".

The Administration menu

On Debian, the Administration menu is found under Applications | System Tools.
On RH-based systems (e.g. Redhat, CentOS, Fedora, Scientific Linux), the Administration menu is usually found under System.

The Moonshot Identity Selector should appear.

2.2. Choosing the storage backend

The Moonshot UI currently supports four different storage backends, each one providing different security levels and suited to different users. The UI will try to use the supported backends in order of security, moving from the more secure ones to the less secure. You can see the name of the backend in use at any moment in the status bar of the GTK UI, and in the first line of the TXT UI.

LIBSECRET. The backend uses libsecret to store identity information. libsecret is a standard DBUS API to talk to a FreeDesktop's Secret Service, such as GnomeKeyring or KDE Wallet. The requirements for this backend are to have an active X session and any of the available Secret Services running. Note that it's up to your Secret Service to prompt you to unlock the keyring, keep sessions open, etc. This backend is the preferred choice for desktop users.
GNOME_KEYRING. This backend uses stores identity information using Gnome Keyring. It is very similar to LIBSECRET, only that instead of using the generic API provided by libsecret, it uses Gnome Keyring API directly. The requirements for this backend are having an active X session and Gnome Keyring running. It is used only where libsecret is not available (ie. CentOS / RHEL / SL 6).
ENCRYPTED_FLAT_FILE. This backend stores identity information in an encrypted, integrity protected and authenticated file. The only requirement for this backend to work is setting up a master key called moonshot-ui stored in the Kernel's Session Keyring. You can do so by using (check https://linux.die.net/man/1/keyctl for more options):
```
keyctl add user moonshot-ui MY_PASSWD @s
```
This is the preferred choice for desktop users when X is not available.
FLAT_FILE. This backend stores identity information in a clear text file. This is the typical choice for servers, where interactive backend unlocking is not possible.

2.3. Working with Identities

Once the Moonshot Identity Selector has loaded, you can now add, modify, or remove identities.

2.3.1. Adding an Identity

Manually adding identities is strongly discouraged, instead the enterprise deployment options available provide a much more secure way of adding identity information as this can include extra information known as a "trust anchor" (information that stops one server pretending to be another).

Load the Moonshot Identity Selector.
Click on the "Add" button on the right.
Fill in the details of the identity you wish to add:
1. Display Name: this a friendly name for the identity that will be displayed in the identities list.
2. User name: this should be your username (e.g. bob.jones).
3. Realm: this should be the realm associated with your organisation (e.g. camford.ac.uk).
4. Password: the password associated with that username.
5. Remember password: whether the password must be remembered for the next time this identity is used. The password is be stored in the available secure storage, as described above.
6. Requires 2FA. Whether this identity requires a second factor. This means that the UI will prompt the user for a second factor, even if the Remember Password check is selected.
Click OK/Add button to save the identity.

2.3.2. Importing identities from a file

For large-scale deployments of Moonshot authentication, it is recommended that user credentials are pre-provisioned, i.e. that users are issued with a credential file that is imported into their local keyring and/or local identity storage. This method also allows the deployment of trust anchors, without which credentials could be exposed to malicious resource providers.

The Moonshot credential file is simple XML. The format of the file is described on the Moonshot identity file format page. A sample of the file can be found at /usr/share/moonshot-ui/default-identity.msht

Keeping identity files safe

Identity files are simple XML, which may include passwords in plain-text (encoded for valid XML). As such, credential files should be kept safe.

For importing credentials, use the Import button. That will open a file browser where you can choose the credential file to import. The UI will prompt you for each identity to be imported.

Additionally, Moonshot ships with a tool, moonshot-webp, to securely and correctly provision credentials onto clients in a non-interactive way from the command line.

The usage of the tool is very simple:

moonshot-webp command-line

moonshot-webp [-f] credential-file.xml

2.3.3. Using an identity

Whenever you attempt to use a Moonshot enabled service for which the UI has no active Service association, the Identity Selector will pop up. Simply choose an existing identity, or create a new one as described above, then hit the Send button.

By default, the Remember my identity choice for this service is checked. That means that a new association is be created so next time you attempt to access to the same service, the UI will use the linked identity without prompting you. You can view and remove existing Service associations at any time (see Modifying an Identity section below to see how).

If you regularly use a service which is not Moonshot enabled or that you use traditional, non-Moonshot, credentials to access, you can tell the Identity Selector to stop appearing every time you attempt to access the service by doing the following:

Attempt to access the service as normal; the Moonshot Identity Selector should pop up.
Choose the identity labelled "No Identity", and hit the "Send" button.
For all subsequent authentication attempts, the Moonshot Identity Selector should not appear.

2.3.4. Accepting Trust Anchor information

If the chosen identity had no trust anchor information (eg. it was added manually), the UI will prompt you to accept the IDP certificate fingerprint. If you confirm, the fingerprint will be stored with your identity and you will not be prompted again unless the IDP certificate changes.

Note that even though you can view the IDP certificate information, that does not mean it's been validated. The only secure way of validating an IDP certificate it by means of the fingerprint.

Do not accept any IDP certificate if you have not checked the fingerprint with your IDP administrator!

2.3.5. Modifying an Identity

You can modify most of the properties of an stored identity (ie. display name, password, mapped services...). However, for security reasons, Trust Anchor details cannot be manually edited, only cleared.

Load the Moonshot Identity Selector.
Choose the identity to modify, then click Edit to display the details of the identity.

2.3.6. Removing an Identity

Load the Moonshot Identity Selector.
Select the identity to remove.
Click the "Remove" button to delete the identity. You will be prompted to confirm the deletion.

3. Using the Identity Selector modes of operation

Starting from version 1.2.10, the Identity Selector for Linux allows setting the mode of operation, allowing each user to adjust the desired level of interactivity shown by the UI.

3.1. Modes of operation

There are three different modes of operation:

INTERACTIVE. This is the default mode, and it fully matches the behaviour of previous versions. When a GSS-API request for authentication is received, the Identity Selector checks whether one of the stored identities is suitable for it. If one is found, the authentication is performed without prompting the user. However, if no suitable identity is found, the Identity Selector is shown so the user can manually select the desired identity, create a new one, or dismiss using Moonshot for this authentication.
NON_INTERACTIVE. In this mode, the Identity Selector will still check whether one of the stored identities is suitable for the requested authentication, and use it when found. However, if no suitable identity is found, it automatically dismisses using Moonshot for the authentication without prompting the user. In other words, Moonshot is only used for the set of configured servers.
DISABLED. In this mode, Moonshot authentication will always be dismissed, even if there are identities that would work for the requested service.

3.2. Setting the mode of operation

The Identity Selector mode of operation is configured per-user. The UI shows information about the current mode and allows changing it in an easy way.

The current mode is shown at the status bar on the bottom part of the window. This value can be easily changed by clicking on it in the GTK version of the UI, or on the "Set Mode" button in the TEXT version of the UI.

When the value is changed, a warning message is shown describing how the selected mode works, to avoid accidental changes.