Enhance SMS-delivered code security with domain-bound codes
August 4, 2020
Many websites and apps offer additional login security in the form of SMS-delivered codes. On iPhone, Security Code AutoFill makes it easy for people to quickly supply these codes by offering them in the QuickType bar. On a Mac running macOS Big Sur, Mac Catalyst and AppKit apps can take advantage of this feature as well.
Additionally, starting with iOS 14 and macOS Big Sur, we’re adding an extra layer of security to SMS-delivered codes by allowing you to associate codes with a specific web domain.
How domain-bound codes work
When you use a domain-bound code, AutoFill will suggest the code if — and only if — the domain is a match for the website or one of your app’s associated domains. For example, if you receive an SMS message that ends with
@example.com #123456, AutoFill will offer to fill that code when they interact with example.com, any of its subdomains, or an app associated with example.com. If instead you receive an SMS message that ends with
@example.net #123456, AutoFill will not offer the code on example.com or in example.com’s associated app. This makes it harder for an attacker to trick someone into entering one-time codes into a phishing site.
While iOS and macOS will also display regular SMS-delivered codes in addition to domain-bound codes, we encourage everyone employing this authentication method to adopt this standard to provide a more secure experience for people on your website or app. If a message contains no domain information, it will continue to be offered in all relevant fields through AutoFill.
How to set up SMS domain-bound codes
You can take advantage of domain-bound codes on both websites and apps with associated domains.
Set up domain-bound codes for your website
In most cases, AutoFill should work automatically on Safari for iOS and macOS Big Sur, and requires no additional information from you. In cases where it does not, you can add the
autocomplete=one-time-code attribute to your web page’s text field. This cues Safari to offer applicable codes in that field.
Set up domain-bound codes for your app You can support domain-bound codes by providing an associated domain for your app. If you support Universal Links for your domain, or if AutoFill is currently suggesting saved passwords for your domain in your app’s login screens, your app is already associated with your domain.
Note: If you’re running into issues when testing your app’s login flows, you may need to provide an additional hint about which fields in your app are one-time code fields. For iOS and Mac Catalyst apps, set the field’s
textContentType property to
UITextContentType.oneTimeCode. For AppKit apps on macOS,
NSTextField has a
contentType property that you should set to
How to format SMS domain-bound codes
Once your app or website is set up to receive domain-bound codes, you’ll need to provide a simple addition to the SMS messages you send through your backend service to include both the domain and code. Here’s what the text you’ll send looks like:
123456 is your Example code. @example.com #123456
Everything above the last line of the message is freeform. You're free to customize this part however you like, but it should be something that makes sense to people receiving the code.
The last line of this message gives AutoFill on iPhone, iPad, or Mac the information it needs to bind the domain and code together and suggest the code for the appropriate website or app.
In order for domain-bound codes to work properly, you must include this information in the last line of the message, and it must contain the domain and code in the correct order.
This is the first part of that last line, and contains the domain of the app or website where you want the code to fill in. Make sure to put a single space after your domain before you begin the segment with your one-time code.
#123456 (represents the code 123456)
The second part of the last line begins with # and contains the string with your app or website’s one-time code.
Improve your SMS-delivered codes
Domain-bound codes are straightforward for developers to implement, easy for people using your apps and websites to understand, and add more security to the SMS-delivered codes. You can also learn more about domain-bound codes and the development of the message format in the W3C’s Web Platform Incubator Community Group.