Self-service microsite parameters

Introduction

This document describes the parameters that can be used to customize the appearance and behavior of a Nametag self-service microsite.

Hints

You can provide hints in the URL in the form of query parameters. These hints do not restrict who can use the service (because the user can simply edit the URL) but they can smooth out the user experience.

Suggesting email address

You can pre-fill the email address field on the microsite by appending the email query parameter to the URL. For example:

https://recovery.example.com/?email=alice@example.com

Suggesting Directories

You can restrict the directories that are eligible for reset by specifying the dir query parameter to the URL. To allow multiple directories, specify the parameter multiple times. The directory ID can be found in the Nametag console under the Directories tab. For example:

https://recovery.example.com/?dir=12345678-1234-1234-1234-1234567890ab&dir=87654321-4321-4321-4321-0987654321ba

Suggesting Operations

You can restrict the operations that are available on the microsite by specifying the op query parameter to the URL. To allow multiple operations, specify the parameter multiple times.

Note: Not all operations are available for all directories.

Suggesting Flow

You can alter the text to accommodate the specific flow you wish to present to the user. Valid values of flow query parameter are:

Restrictions

Providing hints can be helpful to users, but it does not prevent a user from modifying the request to invoke different operations. For a higher level of assurance, you can provide a presigned id_token query parameter.

To require a presigned URL, set the Require presigned URL setting in the Nametag Console under the Self Service tab.

Enabling this option will make your self-service site available only to people with presigned URLs.

Producing presigned URLs

Construct presigned URLs with the API or the nametag command line tool.

nametag -e ENV self-service presign \
    --email alice@example.com \
    --operation mfa \
    --password \
    --directory 12345678-1234-1234-1234-1234567890ab \
    --flow enroll \
    --ttl 1h
https://recovery.example.com/?id_token=.....

The arguments to the presign command are:

• --email: The email address of the user. If not specified, the presigned URL is valid for any user.
• --operation: The operation to perform. Valid values are mfa, password, unlock, and temporary-access-pass. Specify this argument multiple times to allow multiple operations. If not specified, the presigned URL is valid for any operation.
• --directory: The directory ID. If not specified, the presigned URL is valid for any directory. Specify this argument multiple times to allow multiple directories. If not specified, the presigned URL is valid for any directory.
• --flow: The flow to present to the user. Valid values are recover and enroll. This parameter doesn’t change the behavior of the self-service site, but it does change the text in various places to accommodate the specific flow you wish to present to the user.
• --ttl: The validity period for the presigned URL. The default is 1 hour. A duration string is a sequence of decimal numbers, each with optional fraction and a unit suffix, such as “300ms”, “1.5h” or “2h45m”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

You can also use the API to produce presigned URLs, as shown in the following example:

POST /api/env/ENV/recovery/presign?
    email=alice@example.com&
    operation=mfa&
    operation=password&
    directory=DIRECTORY&
    flow=enroll& \
    ttl=1h

The response will be a JSON object with a URL field:

{"url": "https://recovery.example.com/?id_token=....."}