FamilySearch uses OAuth 2 for API authentication. This presentation covers several authentication options in the context of OAuth 2.

1. 1
FamilySearch
Authentication Options
25 Sep 2014
© 2013 by Intellectual Reserve, Inc. All rights reserved.

2. 2
Agenda
• Access to the API
• OAuth2
- Access Tokens
- Authorization Grants
• Special Configurations
- OpenID

3. 3
How do I gain access to the
API?

4. 4
Grant my users access to the
API through my app

5. 5
FamilySearch
API
access to
through
user
Grant

6. 6
OAuth 2.0

7. 7
OAuth 2.0
The OAuth 2.0 authorization framework enables a
third-party application to obtain limited access to
an HTTP service, either on behalf of a resource
owner by orchestrating an approval interaction
between the resource owner and the HTTP
service, or by allowing the third-party application to
obtain access on its own behalf.

8. 8
OAuth 2.0
• Third-party application
• Obtain limited access
• HTTP Service
• On behalf of a resource owner
Client
FamilySearch API

9. 9
OAuth 2.0 – Access Tokens
• Access Tokens
- Credentials used to access protected
resources.
- A string representing authorization issued to
client.

10. 10
FamilySearch – Access Tokens
• String
- USYSB839321B7082635DBDCB50AB50F0C98E_idses-int01.a.fsglobal.net
• Type: Bearer Token (RFC 6750)
- Sent in Authorization header
- If can't use header, access_token
querystring parameter
• Expire after 1 hour of inactivity
• Have max life of 24 hours

11. 11
How does my client obtain an
access token for its user?

12. 12
OAuth 2.0 – Authorization Grant
• Client exchanges an authorization grant for an
access token
✔

13. 13
OAuth 2.0 – Authorization Grant
• A resource owner ( ) gives:
- authorization ( )
- to access its protected resources ( API
)
- used by client ( ) to get access token ( )
✔
✔

14. 14
OAuth 2.0 – Grant Types
• Grant Types
✔
- Authorization Code
- Implicit
- Resource Owner Password Credentials
- Client Credentials
- Extensions…

15. 15
FamilySearch – Grant Types
• Grant Types
✔
- Authorization Code
- Implicit
- Resource Owner Password Credentials
- Client Credentials
- Unauthenticated (Extension)
• All Grant Types require an Client ID (App Key)

16. 16
Authorization Code ✔

17. 17
Authorization Code ✔
https://myapp.com
Get FamilySearch Data

18. 18
Authorization Code ✔
Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…

19. 19
Authorization Code ✔
Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…

20. 20
Authorization Code ✔
Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…

21. 21
Authorization Code ✔
Redirect Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth… myapp.com?code={}
Authorization code passed
to client as ?code={code}

22. 22
Authorization Code ✔
https://myapp.com/redirect-uri?code=S3CRT-4UTH-C0D3 ✔
The code ( ✔
) is the user's ( )
authorization to access
protected resources ( API
)

23. 23
Authorization Code ✔
https://myapp.com/redirect-uri?code=S3CRT-4UTH-C0D3 ✔
The client needs to exchange the code ( )
for an access token ( ).
Client performs POST w/ code to the
Token URI which returns access token.
✔

24. 24
Authorization Code ✔
FamilySearch
OAuth2.0
Token
Resource
POST (code) ✔
{access_token: "token"}

25. 25
Authorization Code
• This is the required grant type for web apps.
- Must not use an iframe for authorization
screen.
- Full-page redirect or pop-up.
- Register your redirect URI.
• Your web app must never prompt the user for
username/password directly.
✔

26. Resource Owner Password Credentials ✔
26

27. 27
Resource Owner Password Credentials
• The user's username and password are used
directly as an authorization grant ( ).
✔
✔
Login to FamilySearch
Login with your FamilySearch
username and password.
username
**********
Login!
Cancel

28. Resource Owner Password Credentials ✔
FamilySearch
OAuth2.0
28
Token
Resource
POST
✔
(username & password)
{access_token: "token"}

29. 29
Resource Owner Password Credentials
• This may only be used by Native Clients.
- Mobile or Desktop apps
- Must be enabled on your app key
• With user's permission, username & password
may be saved via a secure mechanism (like
Apple Keychain).
✔

30. 30
Unauthenticated ✔

31. Unauthenticated ✔
FamilySearch
OAuth2.0
31
Token
Resource
POST
{access_token: "token"}

32. 32
Unauthenticated
• Only used for non-user specific read-only
resources.
- Places
- Person Match
• Throttled by App Key.
✔

33. 33
Client Credentials ✔

34. 34
Client Credentials
✔
• System-to-system authentication
• Internally called "Service Accounts"
• Requires secure, confidential client (Server)
• Very, very rarely granted to FS partners

35. 35
Special Configurations

36. How can I make it so my user
doesn't have to log in so often?
36

37. 37
Special Configurations
• Refresh Tokens
• OAuth2 + OpenID

38. 38
Refresh Tokens

39. Special Configuration – Refresh Tokens
39
• Client receives
- Access Token and Refresh Token
• Client exchanges
- Refresh Token for Access Token
• FamilySearch supports refresh up to 2 weeks if
user opts-in.

40. 40
Authorization Code ✔
FamilySearch
OAuth2.0
Token
Resource
POST (code) ✔
{access_token: "token",
refresh_token:"r_token"}
POST (r_token) ✔
{access_token: "token2",
refresh_token:"r_token2"}

41. Special Configuration – Refresh Tokens
41
• Only available to Confidential Clients
- Server that can keep a secret secure
• Approved on a case-by-case basis
• Talk to an account manager

42. 42
OAuth 2 + OpenID

43. 43
OAuth 2 + OpenID (v2) Configuration
• Enables single-sign-on when obtaining
Authorization Code
• Doesn't require patrons to be prompted with
FamilySearch credentials every time
• Requires your website to have a trusted
OpenID Provider
- Currently supporting OpenID v2.0
- Must pass FamilySearch security review

44. 44
Authorization Code w/ OpenID ✔
https://myapp.com
Get FamilySearch Data

45. 45
Authorization Code w/ OpenID ✔
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…
Who?
Redirect

46. 46
Authorization Code w/ OpenID ✔
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…
Who?
Redirect
Begin OpenID Dance!

47. 47
Authorization Code w/ OpenID ✔
Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…
Who?
myapp.com/openID...
myapp.com/John

48. 48
Authorization Code w/ OpenID ✔
Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…
Who?
I know
myapp.com/John
myapp.com/openID...
myapp.com/John

49. 49
Authorization Code w/ OpenID ✔
Redirect Redirect
https://myapp.com
Get FamilySearch Data
https://fs.org/auth…
Who?
myapp.com?code={}
I know
myapp.com/John Auth Code!
myapp.com/openID...
myapp.com/John

50. 50
OAuth 2 + OpenID (v2) Configuration
• In order for FamilySearch to recognize
myapp.com/John
- Link to existing FS account
- Create a new FS account

51. 51
Special Configurations
• All special configurations require case-by-case
approval.
• Talk to your account manager

52. 52
Recap of Authentication Options
• Authorization Code (Web Apps)
• Username Password (Mobile & Desktop)
• Unauthenticated (All)
• Client Credentials (Servers in rare case)
• Refresh Tokens (Confidential web clients)
• OAuth + OpenID (Web Apps)

53. 53
Resources
• Documentation
- https://familysearch.org/developers/docs/guides/oauth2
- http://tools.ietf.org/html/rfc6749
• Questions & Account Manager Requests
- devsupport@familysearch.org