2021 - Q2 Newsletter
Update July 14,2021 The release date for the experiment "search.return.enhanced.gedcomx" has been confirmed for release to production on Oct 5, 2021.
Update July 14,2021 The security policies and ciphers for the TLS update are different based on the domain referenced. FamilySearch uses AWS policy TLSv1.2_2019 for www.familysearch.org and ELBSecurityPolicy-FS-1-2-Res-2019-08 for api.familysearch.org. If your https security library throws errors, you will want to refer to these documents.
Note To add or remove an email address from the FamilySearch developer notification list, please contact email@example.com
This edition will cover the following topics:
- 2021 - Q2 Newsletter
TLS 1.1 Removal
On May 7, 2021, you should have received the following notification regarding an important security update for TLS 1.1. This change is already effective in Beta and will be released to Production on Monday, July 12, 2021.
According to the December 2020 Developer Newsletter, we noted that support for TLS 1.0 would be removed. As TLS 1.1 is also considered a legacy protocol, FamilySearch will be removing support for TLS 1.1 as well. This change is scheduled for the maintenance update on Monday, July 12, 2021. To enable adequate testing, support for TLS 1.1 will be removed from the Beta environment on June 1, 2021.
Moving forward, FamilySearch will be following this maintenance plan for TLS security upgrades:
- In future quarterly developer newsletters, we will note the current industry standard for Transport Layer Security. Today it is TLS 1.3, which has been available since 2018.
- FamilySearch will support the current industry standard and one major release prior. For now this is TLS 1.3 and 1.2.
- During planned maintenance updates, FamilySearch will remove support for earlier versions of TLS in order to follow industry security protocols. Partners are encouraged to upgrade their security libraries regularly to avoid potential security issues as well as to continue to use the FamilySearch API.
FamilySearch Framing Prevention
As FamilySearch strives to increase application security and to follow industry best practices, we are planning a change to the headers on the
www.familysearch.org site to prevent framing. This change would protect FamilySearch patrons from malicious sites attempting to trick patrons into performing unauthorized actions by overlaying a malicious page with the FamilySearch site. This technique is similar to the practice of phishing and is more commonly known as clickjacking.
The plan is to implement 2 changes in the headers similar to the following:
X-Frame options: DENY Content Security Polity: frame-ancestors ‘none’
In order to provide partners enough time to test for this change, this security update will take place on
beta.familysearch.org on July 12, 2021. We encourage you to test your site on Beta to prevent service interruptions. The change will roll out to production on October 11, 2021.
Please note: this may also affect applications which use embedded browsers that reference familysearch.org. Please confirm that your application is working as expected once this has been released to Beta.
503 Retry-After Header Response Update
503 Service Unavailable response indicates that there was an internal issue preventing the service from responding. However, this error code does not indicate when the request can be resubmitted. An update to the
503 http responses for all FamilySearch API requests was released to Production in March 2021. Where possible, a new Retry-After header indicates when that service will be available again.
429 Throttling response has always included a Retry-After header. You should adjust how your application reacts to the new
503 Retry-After response in a similar manner if it is available. Please refer to the Throttling Guide for details on how your application should respond in these cases.
Change to Search Results
The release for data changes to search results previously announced in March 2021 were delayed. These changes are now available in the Beta environment. This includes changes to the following:
- Person Names
- Person facts/fields/identifiers
- Person display information
Please use the following experiment header. The final release to Production is anticipated for October 2021.
[UPDATE] OAuth 2.0 Changes for Desktop and Mobile
As announced in the March 2021 Developer Newsletter, the enhancement for long-lived refresh tokens is now available in each server environment. Please note that your app key must be configured on the server to request refresh tokens, so please send a message to firstname.lastname@example.org if this has not already been done. To request a 90-day refresh token, your application can pass a new scope parameter
offline_access on the authorization request. Example request:
https://ident.familysearch.org/cis-web/oauth2/v3/authorization ?response_type=code &scope=openid%20offline_access &client_id=a02j000000KTRjpAAH &redirect_uri=https://example.com/auth/
For more details on these refresh tokens and the transition away from Password Flow authentication, please refer to the following documentation:
- OAuth 2.0 for Native Apps transition guide
- FamilySearch Authentication developer guide
- Authorization API specification
All applications that have previously completed the Compatibility review for Authentication can be released with updated OAuth 2.0 code to Production at any time. The Password Flow authentication has been deprecated and support for this method will be removed by the end of 2021.
FamilySearch GEDCOM 7.0 Released
At RootsTech 2020, FamilySearch launched an effort to create a new version of GEDCOM based on the 5.5.1 version that would include: 1) new expressivity, flexibility, and compatibility; 2) zip packaging of associated images and other files with the related GEDCOM file; and 3) public access using a GitHub repository. Many industry software providers and key influencers participated, and the initiative concluded May 15, 2021.
FamilySearch GEDCOM 7.0 is the outcome of those efforts and includes the following new enhancements:
- Zip packaging capabilities for photos and files have been added.
- Notes have been expanded for more versatile use and styling of text.
- Tools, sample files, sample code, and self-testing guides are included.
- The FamilySearch GEDCOM specification and any code available from FamilySearch based on the specification is subject to the terms and conditions of the Apache License, Version 2.0.
- Ambiguities in the GEDCOM Version 5.5.1 specification have been removed.
- A public GitHub repository generates maintenance requests and on-going discussions about future features.
Technical information, specifications, tools, and guides can be found at GEDCOM.io.