Skip to content

signalapp/registration-service

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Signal registration service

This is a multi-provider phone number verification service for use with Signal.

When Signal users first create an account, they do so by associating that account with a phone number. Signal verifies that users actually control that phone number by sending a verification code to that number via SMS or via a phone call. This service manages the process of sending verification codes and checking codes provided by clients.

Major components

External callers interact with this service by sending gRPC requests. The gRPC interface is defined in registration_service.proto. gRPC requests are handled by RegistrationServiceGrpcEndpoint, which sanitizes client input and dispatches requests to RegistrationService, which orchestrates the major business logic for the entire service.

RegistrationService uses a SenderSelectionStrategy to choose a concrete VerificationCodeSender implementation to send a verification code to a client. VerificationCodeSenders are responsible for sending verification codes via a specific transport (i.e. SMS or voice) and service provider and later for verifying codes provided by clients. A SessionRepository stores session data (i.e. verification codes or references to external verification sessions) for VerificationCodeSenders.

Configuration

At a minimum, the registration service needs at least one VerificationCodeSender, a SenderSelectionStrategy, and a SessionRepository. No beans of those types will be instantiated unless they're configured, and so some configuration properties must be provided. The following table describes the currently-supported (and required, in production environments) configuration properties.

Property Description
analytics.bigtable.table-id The identifier for a Cloud Bigtable table to be used to store verification attempts pending follow-up analysis (optional)
analytics.bigtable.column-family-name The name of a column family within analytics.bigtable.table-id to be used to store verification attempts pending follow-up analysis (optional)
analytics.pubsub.analyzed-attempts.topic The name of a GCP pub/sub topic to which to send events when attempts are fully analyzed
analytics.pubsub.completed-attempts.topic The name of a GCP pub/sub topic to which to send attempts without analysis
analytics.twilio.sms.price-estimate.default-number-types A prioritized list of Twilio number types used by default to send messages to when using Twilio Programmable Messaging
analytics.twilio.sms.price-estimate.nanpa-number-types A prioritized list of Twilio number types used to send messages to NANPA numbers when using Twilio Programmable Messaging
analytics.twilio.sms.price-estimate.regional-number-types A map of ISO region codes to prioritized lists of Twilio number types used to send messages when using Twilio Programmable Messaging; may be empty
analytics.twilio.verify.fee-amount The amount of the fee charged by Twilio Verify for successful verifications
analytics.twilio.verify.fee-currency The currency of the fee charged by Twilio Verify for successful verifications
fictitious-numbers.firestore.collection-name The name of the Cloud Firestore collection that stores verification codes for fictitious phone numbers
fictitious-numbers.firestore.expiration-field-name The name of the field in documents in the Cloud Firestore collection for verification codes for fictitious phone numbers that identifies when the document expires and may be removed automatically
gcp.bigtable.project-id The identifier for a Google Cloud Platform project that contains the Cloud Bigtable instance to be used for various data storage applications
gcp.bigtable.instance-id The identifier for a Cloud Bigtable instance to be used for various data storage applications
gcp.pubsub.project-id The identifier for a Google Cloud Platform project that contains the pubsub topics to be used
messagebird.access-key The access key used to authenticate with MessageBird
messagebird.default-sender-id The default originating number or alphanumeric sender id for MessageBird messages and calls
messagebird.region-sender-ids The originating number or alphanumeric sender id for MessageBird messages and calls by region
messagebird.sms.session-ttl The maximum lifetime of a registration started by sending a verification code via MessageBird sms (optional)
messagebird.verify.session-ttl The maximum lifetime of a registration started by sending a verification code via MessageBird verify (optional)
messagebird.voice.session-ttl The maximum lifetime of a registration started by sending a verification code via MessageBird voice (optional)
messagebird.voice.supported-languages A list of BCP 47 language tags for which translations of spoken messages delivered via the MessageBird Voice API are available
prescribed-verification-codes.firestore.collection-name The name of the Cloud Firestore collection that contains prescribed verification codes
rate-limits.check-verification-code.delays A list of durations that callers must wait between successive attempts to check verification codes
rate-limits.leaky-bucket.session-creation.max-capacity The maximum number of permits in a session creation rate limiter "bucket"
rate-limits.leaky-bucket.session-creation.permit-regeneration-period The time required for a permit in a session creation rate limiter "bucket" to regenerate
rate-limits.leaky-bucket.session-creation.min-delay The minimum amount of time that must elapse between taking permits from a session creation rate limiter "bucket"
rate-limits.send-sms-verification-code.delays A list of durations that callers must wait between successive attempts to send verification codes via SMS
rate-limits.send-voice-verification-code.delay-after-first-sms The amount of time a caller must wait after requesting their first SMS before they may request a phone call
rate-limits.send-voice-verification-code.delays A list of durations that callers must wait between successive attempts to send verification codes via phone calls
selection.[transport].fallback-senders A nonempty ordered list of senders to fall back on. The first sender that supports the request will be used, or the first sender if no sender supports the request.
selection.[transport].default-weights A map by service of weights by which requests are assigned to services. (e.g. twilio-verify = 50, messagebird-verify = 50) (optional)
selection.[transport].region-weights A map by region of weights that override the default weights (e.g. us.twilio-verify = 9, us.messagebird-verify = 1) (optional)
selection.[transport].region-overrides A map of regions to service that indicate that a region should always go to that service (e.g. de = messagebird-verify) (optional)
session-repository.bigtable.table-name The name of the Bigtable table that contains registration sessions
session-repository.bigtable.column-family-name The name of the Bigtable column family name within the configured Bigtable table that contains registration sessions
twilio.account-sid The SID of the Twilio account to use to send verification codes via Twilio's Programmable Messaging, Programmable Voice, and Verify APIs
twilio.api-key-sid The SID of the Twilio API key used to authenticate with Twilio
twilio.api-key-secret The secret component of the API key used to authenticate with Twilio
twilio.messaging.nanpa-messaging-service-sid The SID of the Twilio messaging service to be used to send SMS messages to NANPA phone numbers
twilio.messaging.global-messaging-service-sid The SID of the Twilio messaging service to be used to send SMS messages to phone numbers outside of NANPA
twilio.messaging.session-ttl The maximum lifetime of a registration started by sending a verification code via the Twilio Programmable Messaging API (optional)
twilio.voice.phone-numbers A list of E.164-formatted phone numbers from which Twilio voice calls can originate
twilio.voice.cdn-uri The base URI from which voice messages translated to various languages may be retrieved
twilio.voice.supported-languages A list of BCP 47 language tags for which translations of spoken messages delivered via the Twilio Programmable Voice API are available
twilio.voice.session-ttl The maximum lifetime of a registration started by sending a verification code via the Twilio Programmable Voice API (optional)
twilio.verify.service-sid The SID of a Twilio Verify service to be used to send verification codes
twilio.verify.service-friendly-name A "friendly" name for the Twilio Verify service, which may appear in verification messages (optional)
twilio.verify.android-app-hash The app hash to include in SMS messages sent by Twilio Verify for Android devices that support Automatic SMS Verification
twilio.verify.supported-languages A list of BCP 47 language tags supported by Twilio Verify
verification.sms.android-app-hash The app hash to include in SMS messages for Android devices that support Automatic SMS Verification
verification.sms.message-variants-by-region A map of two-letter region codes (e.g. "US") to names of SMS message variants; message variants should have corresponding entries in the SMS message string table
verification.[transport].supported-languages A list of BCP 47 language tags for which translations of a verification SMS message sent via the Twilio Programmable Messaging API are available

Running in development mode

For local testing, this service can be run in the dev Micronaut environment. In the dev environment, the following components are provided (assuming no others of have been configured):

  • A trivial verification code sender that always uses the last six digits of a phone number as a verification code
  • A trivial sender selection strategy that always chooses the last-six-digits "sender"
  • An in-memory session store

These components are, obviously, not suitable for production use and are intended only to facilitate local development and testing.

To run the registration service locally with the dev environment enabled:

./mvnw mn:run -Dmicronaut.environments=dev

Testing with command-line tools

The registration service include a set of CLI tools to facilitate testing and development. The tools allow operators to create and inspect registration sessions, send verification codes, and check verification codes.

To build the CLI tools:

./mvnw clean package

To run the tool and get an exhaustive list of subcommands and flags:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient

…which yields (at the time of writing):

Usage: <main class> [--api-key=<apiKey>] [--host=<host>] [--port=<port>]
                    [[--plaintext] |
                    --trusted-server-certificate=<trustedServerCertificate>]
                    [COMMAND]
      --api-key=<apiKey>   API key for this call
      --host=<host>        Registration service hostname (default: localhost)
      --plaintext          Use plaintext instead of TLS? (default: false)
      --port=<port>        Registration service port (default: 50051)
      --trusted-server-certificate=<trustedServerCertificate>
                           Path to a trusted server certificate; signal.org
                           certificate trusted by default
Commands:
  create-session, create          Start a new registration session
  get-session, get                Describe an existing registration session
  send-verification-code, send    Send a verification code to a phone number
                                  associated with a session
  check-verification-code, check  Check a verification code for a registration
                                  session

As a concrete example of interacting with a local registration service running on port 50051, callers may create a registration session with the following command:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient \
  --host=localhost \
  --port=50051 \
  --plaintext \
  create-session +18005550123

…which yields (in this example):

Created registration session 2a3d2a2a41ff41fb9ce41687ddcc51a4

To send an SMS verification code for that session:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient \
  --host=localhost \
  --port=50051 \
  --plaintext \
  send-verification-code 2a3d2a2a41ff41fb9ce41687ddcc51a4

…and, finally, to submit a verification code for that session:

java -cp target/registration-service-0.1.jar org.signal.registration.cli.RegistrationClient \
  --host=localhost \
  --port=50051 \
  --plaintext \
  check-verification-code 2a3d2a2a41ff41fb9ce41687ddcc51a4 550123

About

Registration Service for Signal

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages