- Access protection recommendations
- Settings, enabling EN Express
- Settings, adding system contacts
- Settings, code settings
- Settings, SMS
- Authenticated SMS
- Adding users
- API keys
- ENX redirector service
- Mobile apps
- Statistics
- Rotating certificate signing keys
This guide provides high-level steps for realm administrators to follow.
If you are not a realm administrator, you will not have access to these screens.
We provide a base level of account protection measures that we urge you to share with your caseworkers that are issuing verification codes.
- All user accounts must verify ownership of their email address before using the system.
- Multi-factor authentication (MFA) is available, we strongly suggest you require your users to enroll in MFA using a mobile device under their sole control.
- Users should not share logins to the verification system.
- Users should only issue codes to people who have a verified COVID-19 diagnosis.
A member of the realm should be responsible for monitoring the number of codes issued and take corrective action (including user account suspension) for abuse. Realm administrators can also enable Abuse Prevention.
- API keys should not be checked into source code.
- ADMIN level API Keys can issue codes, these should be closely guarded and their access should be monitored. Periodically, the API key should be rotated.
Go to the realm settings by selecting the settings drop down menu (shown under your name).
Under general settings, confirm the Name (display name only) and Region code settings.
The region code is important for EN Express customers and must match the
ISO 3166-1 country codes and ISO 3166-2 subdivision codes
for the geographic region that you cover.
Once that is confirmed and saved, click the Enable EN Express button.
Go to the realm settings by selecting the settings drop down menu (shown under
your name).
Under general settings, you can add up to 10 system contacts ("emergency contacts") which will receive automated alerts when the system detects critical issues with your realm. These issues include a sudden drop in code claim rate or potential issues with your SMS configuration.
Although recommended, the email addresses in this list do not need to be users in the system. To alert more than 10 contacts, consider creating a Google Group or similar mailing list system.
Also under realm settings settings from the drop down menu, there are several settings for code issuance.
-
Enabled
A new tab is added to the realm that allows the issuance of many codes from a CSV file. This can be useful for case-workers who are given a data-set of test results rather than administering tests one-by-one. Details about how to bulk-issue codes can be found here.
-
Disabled
Only the single issue-code tab will be shown. Calls to the batch issue API will fail for this realm.
Realms may allow the following test result types from case workers.
- Positive + Likely + Negative
- Positive + Likely
- Positive
Although only positive and likely are used for matching exposure notifications on the client,
negative is recommended for realms where the test result is shown to the user through the patient app.
Showing all diagnosis - including negative through the app upon code issuance is a more powerful way to
drive adoption of this system and can be more secure because the receipt of an SMS from this system does not
reveal the diagnosis outcome.
The system also supports user initiated reporting (self report). This feature is especially useful if a large percentage of tests in our jurisdiction are at home (self test) or if there is significant delay in labs reporting results to the public health authority in the region.
To enable, select the "Allow user initiated report" setting. As an anti abuse measure, phone numbers provided by users to request verification codes may be temporarily stored on the server to deduplicate future requests. The default retention period is 90 days, but contact your server operator for specific configuration.
If you are an Exposure Notifications Express (ENX) customer, you will also want to select "Enable user report webview" which is the UI used on iOS ENX. ENX customers should work directly with Apple and Google on enabling user report.
The "Admin API can issue user-report codes" setting generally does not need to be used, please discuss with Apple and Google before enabling.
Issuing codes have two date fields testDate and symptomDate. If this setting is marked required
the issuer must pass one or both of these dates. Case workers might ask for the date of symptom onset together
with the test, but when only testDate is given, apps are optionally recommended to prompt the user to enter
a date for first onset of symptoms - this may allow for more accurate matching of exposure.
If set to optional, codes may be issued successfully with no dates present.
This setting adjusts the number of characters required for both long and short codes. Realm admins may also define how long an issued code lasts before it expires. Once expired, the patient will not longer be able to claim the diagnosis as theirs.
If EN Express is enabled, these fields are not adjustable.
Short codes are intended to be used where a case-worker may need to dictate the code to their patients whereas long codes may be more secure for realms where they may be sent via SMS (but may be more difficult to dictate and recall).
To dispatch verification codes / links over SMS, a realm must provide their credentials for Twilio. The necessary credentials (Twilio account, auth token, and phone number) must be obtained from the Twilio console.
If your realm uses Twilio to send SMS messages and your server operator has enabled the SMS Error Webhook feature, your SMS form will include a "Twilio alerts webhook URL" on the page. If this webhook is configured on Twilio, the Verification Server will capture and present SMS errors on the statistics page. Like all statistics in the Verification Server, the Twilio webhook statistics are best-effort. This URL is unique to your realm.
-
If you manage your own Twilio account, authenticate to the Twilio console and go to
Monitor > Logs > Errors > Webhooks & Alerts. Enter the URL displayed in the Verification Server UI into the field and click save.
-
If your server operator manages your Twilio account, work with your server operator to ensure the webhook URL is registered on your Twilio account.
Once configured, a graph displaying the sum total of SMS errors will appear on the realm statistics page. Additionally, more detailed statistics are available via the realm statistics API, including a breakdown of failures by error code:
There are many possible reasons why Twilio might be returning errors, but the most common are:
-
30003, 30005 - The message could not be delivered because the handset was unreachable. This error could also mean the message was sent to a landline.
-
30006 - The message was sent to a landline or non-SMS-capable phone number.
Here is the full list of possible Twilio errors.
It is possible to customize the text of the SMS message that gets sent to patients. See the help text on that page for guidance.
The fields [region], [code], [expires], [longcode], and [longexpires] may be included with brackets which will be programmatically substituted with values. It is recommended that the text of this SMS be composed in such a way that is respectful to the patient and does not reveal details about their diagnosis to potential onlookers of the phone's notifications with further information presented in-app.
Authenticated SMS adds a cryptographic signature to SMS messages which Android and iOS use to validate the integrity of the SMS message. You should only enable Authenticated SMS if you have been instructed by Google or Apple to do so.
Click "Authenticated SMS" in the main dropdown navigation menu. If you do not see "Authenticated SMS" in the menu, it means your system administrator has not enabled this functionality on the servers. Contact your server operator for more information.
The default Authenticated SMS page will be mostly empty. Create an initial Authenticated SMS signing key version by clicking the "Create new signing key version":
The page will refresh and you will see the new key version and an option to Enable Authenticated SMS. Click "Enable Authenticated SMS" to enable it:
Finally, share the resulting key information with Google and Apple:
Go to realm users admin by selecting 'Users' from the drop-down menu.
Add users, by clicking on the + in the header. If you do not see the +, you
do not have permission to add users.
Enter the name of the user and the email address to add. The email address will need to be verified on the person's first login.
Choose the permissions the new user should have. Since permissions are
constantly evolving, your list might be different than the one shown here. In
general, permissions take the format: <Entity><Action> like UserRead and
UserWrite. Read permissions are read-only and Write permissions include
create, update, and delete permissions. Always practice the Principle of Least
Privilege and only grant the most minimal set of permissions.
Note, you can only grant permissions at or below your current level.
Note, you may also want to configure System contacts, which is a list of contacts to receive critical system notifications.
API Keys are used by your mobile app to access the verification server. These API keys should be kept secret and only used by your mobile app. Go to API keys admin by selecting 'API keys' from the drop-down menu.
Create API keys by clicking on the + in the header. If you do not see the +, you
do not have permission to create API keys.
Enter a name that indicates what this API key is for and select the type.
The Device type is the one that is needed by mobile apps.
When ready, click the Create API key button.
Once the API key is created, it will be displayed to you. This is the only time that this API key will be displayed. If you fail to copy it, you will need to create another one.
This section is only applicable for realms that have adopted to Exposure Notifications Express (ENX).
The ENX redirector service performs the following primary functions:
-
Serve a
.well-known/directory at a public-accessible URL with files required by iOS and Android to properly handle app deep-links. -
Open your realm's mobile app on the patient's phone. Alternatively, if the patient does not have your mobile app installed, it can redirect them to your app in Apple App Store or Android Play Store automatically based on the device type.
In order for your mobile apps to consume this functionality, you need to create mobile app records on your realm. Note this is different from an API key. Creating a mobile app is documented below.
If your system supports the ENX redirector service, the system administrator should share your redirect domain. Typically this is comprised of your realm's region code and a base domain, like:
https://<region-code>.<domain>
# Example:
https://us-ca.enexpress.com
Your system administrator defines the root domain. You can use URLs with this domain on mobile devices. As mentioned above, if the patient has your app installed, the URL will deep-link into the application. If the patient does not have your app installed, they will be redirected to the appropriate app store and prompted to install.
Go to Mobile apps admin by selecting 'Mobile apps' from the drop-down menu.
Create mobile apps by clicking on the + in the header. If you do not see the +, you
do not have permission to create mobile apps.
Complete the information for your mobile app. Depending on the platform (iOS or Android), you may be required to enter different information. Click "Create mobile app" to save the entry.
Once the mobile app has been created, it can take up to 30 minutes for the ENX redirector service to create your entry.
Note that this process is separate from the Google and Apple app review processes. You still must submit your application for inclusion in the Play Store and App Store respectively, separate from this system.
The verification server provides statistics for various facets of the system. Most statistics are also available via the API.
Some statistics are automatically collected, while other statistics require opt-in consent. The system automatically collects information about the number of codes issued, codes claimed, and error rates.
You can optionally enable enhanced statistics collection from the corresponding key server. Enabling these statistics may require an update to your application's privacy policy or data handling agreement. If enabled, enhanced statistics include information such as:
-
Total number of TEKs published: the total number of TEKs that have been published to the key server (per day).
-
Requests with revisions: the total number of uploads that contained at least one TEK revision.
-
Requests missing onset: the total number of uploads where no onset date was provided.
-
Requests by operating system: a breakdown of requests by target operating system (Android and iPhone).
-
TEK age distribution: this shows a distribution of the ages of TEKs by how many days old each TEK is.
-
Onset upload distribution: reflects the distribution of the time between the TEK's symptom onset time and when the key was uploaded.
This chart shows all of the process points involved in issuing and using a verification code.
- The delta between codes issued and codes claimed can be used as a rudimentary measure of adoption.
- The delta between codes claimed and tokens claimed indicates users that enter a valid verification code but don't get through the consent to share data screen.
- The delta between tokens claimed and publish requests indicates that a user got past the consent screen but keys were not uploaded. Note that an iOS device that has previously published based on a confirmed report and subsequently attempts a self-report will claim a token but fail to publish.
There are two charts here. The first is a histogram showing how quickly users are using verification codes (once successfully used).
The second shows the mean of the code usage time (in minutes).
This chart shows the total number of temporary exposure keys published due to verification certificates issued by your public health authority.
This chart will only appear if you have enabled an SMS provider configuration for your realm. It shows the number of SMS errors reported by the upstream provider by day, grouped by error code.
A small number of errors is to be expected due to the unreliability of cellular networks. A large number of errors (or a sudden increase in the number of errors) could indicate a problem with your SMS configuration. Y
This chart shows a stacked bar chart of the total number of publish requests (uploads to the key sever) due to verification certificates issued by your public health authority.
The total line is an overlay that provides the OS breakdown as a tooltip.
Missing onset date, indicates the count of the number of publish request where the verification certificate did not contain a test date or a symptom onset date and the user also declined to provide a symptom onset date, or one was not known. In that case, those requests received default values according to the configuration of the key server.
This histogram shows, based on publish requests, how many days a device had EN activated before reporting a diagnosis. Ideally this chart will skew to the right (active longer).
This histogram shows, based on publish requests where a symptom onset or test date was provided, how many days ago that symptom onset date was compared to the upload date.
The lower this chart skews, the healthier the testing pipeline and verification code delivery system is.
Periodically, you will want to rotate the certificate signing key for your verification certificates.
This is done from the 'Signing Keys' screen. There are two modes of operation (1) automatic rotation and (2) manual rotation. If your key server supports it, automatic rotation is recommended.
🛑
Once you have confirmed that public key discovery is set up directly, click the "Enable automatic verification certificate key rotation." link (as pictured below).
You will then be asked to confirm that pubic key discovery is set up correctly. When automatic rotation is enabled, the "Realm public keys" section will be note that automatic rotation is enabled.
If you visit this page ever 30d, you should see that there is a different set of available/active public keys.
The first rotation will start between 60 and 90 minutes after you enable rotation.
Click the "Create a new signing key version" button. This will create but not make active a new key.
If successful, you will get a message indicating the new key version that was created. This keyID and the public key need to be communicated to your key sever operator.
When your key server operator confirms that this key is configured, you can click 'Activate.'
15 minutes after activating the new key, you can destroy the old version. Caution: destroying the old key too early it may invalidate already issued, and still valid, certificate tokens.