Difference between revisions of "Best Practice and Example Self-issued Identifier"

Latest revision as of 08:31, 12 October 2022

Full Title or Meme

Best Practice and Example to assist designers and developers of Native Apps that can act on behalf of the user as an Identifier or Attribute Provider that can issue grants for access to user private information. Technical terms are used to convey the information that they will need to perform their task that may not be familiar to the casual reader.

For a less technical document that shows where user data is collected in various user Objects see the Identity Model Overview.

Context

Goals of the Best Practices and Example

In furtherance of the objective of an ecosystem of trusted identities in cyberspace, it is incumbent on the various standards organizations working on the Identity Ecosystem to produce guidelines that can help designers and developers to create apps that support the ecosystem. There is no better test of the existing guidelines that to create an app that meets those goals. This example gives the UX participants the actual experience of applying their guidelines as well as providing an example of that effort for anyone designing or developing a compliant Native App.

The goals set out the needs and constraints on an example for use by a Relying Party (RP) systems design.

1. Provide Native App guidelines and an example of code that can be used: (in order of priority)
   1. to provide an example that can be used on any device platform to more easily achieve standards compliance,
   2. to create an IDEF compliant Native App that will work with standards organizations own web sites for Authentication,
   3. to create a taxonomy of Identifiers and Attributes that can be used for User Consent.
2. Support any relying party that implements OpenID Connect.
3. Support two factor authentication.
4. Provide in-line guidance in the example code of the IDEF requirements that a developer of any Native App can apply.
5. Support various stake-holders of the Identity Ecosystem, such as Health Care, Finance and Government.

Non-goals for this Example

This project is limited to the case of one user creating their own Identifier (perhaps with Attributes) on their own device. The example does not consider the case where that user has more than one device or other repository for their User Information.

Design Thinking

Given the goals above, design thinking is needed to produce a solution in the form of patterns which meets the user's desires and intent. For example in the need to capture the user's consent to the privacy policy and the terms of use, a design pattern could just let the user read and accept the site's stated policies. But what the user wants is control on how their private information is used. The solution below tries to address both the RP site goals and the user desires in a way that allows users to see their past expressed intent and change it as befits their current intent. This is in keeping with the Usable Best Practice A of the IDEF requirements.

Access to the Example

Currently a working draft of the Native App example web site is TBD

Identifier used in Best Practices

Selection of the format of the Identifier

The operating assumption is that any identifier used for authentication must be unique and work effectively on the internet. On the internet unique identifiers are created as a scheme under the Uniform_Resource_Identifier (URI) as defined in RFC 3986. The only scheme that is widely used for identifiers is the mailto: scheme specified in RFC 822 and RFC 1122 where it is defined as "a@b.c" where "a" is usually considered to be a name and "b.c" to be the Identity Provider (IdP). While other identifiers have been created by IdPs, only the mailto: scheme is both URI compliant and well known to the community and so it is the recommended best practice for IDEF compliance. The specific technical reason for defining the identifier in such a limited structure is so that the RP can find the IdP configuration by looking at some well known URL (see RFC 5785) for that information. (n. b. The OpenID 1.0 code required a different syntax for identifiers that uses URL encoding of a.b.c described in the acct: scheme. There are a few existing Open ID providers that still use only the acct: scheme. If they have not fixed their code to permit the mailto: scheme for acquiring configuration information, they will not be able to provision IDs for this design.)

With the rise of personal communication devices, the internet may not be to the only source of user identifiers. Specifically one good practice is to use the user's cell phone number for authentication. The security and privacy of other authentication identifiers should be explained to the user before they are permitted to select one.

It is not required that any identifier is provisioned with an email (see RFC 7505) or other account that can receive notifications. However, if the relying party wants to use an account for notifications they should verify that the account provided belongs to a user that is willing to receive notifications. It is not sufficient simply to ask the user that is registering with the relying party since an attacker could be trying to send unwanted notifications to the unsuspecting owner of the account. Therefore it is incumbent on the relying party to verify the validity of the account by sending a verification to the account and awaiting a favorable response from someone that can access the account before adding the identifier to a list to receive notifications. This best practice applies to applications installed on mobile devices as well as to web browsers.

Compliance and Recovery of User Identifiers

To minimize the cognitive load on the user, this example asks for the user name in the form of an email address and then populates both the user name and the user email address fields of the database with that one string. If the user starts from a federated identity, like Google, that will be the user's email address at the federated IdP. If the user creates their own logon first then the Google email address will not be stored anywhere as the user identifier from Google is unique to the Google sign in identifier. While that provides some privacy protection, it is only because the user name appears in text form only for limited parts of the interchange, all of which should be protected by TLS. If user cognitive overload is not a primary concern the implementation could be changed to force the user to pick a user name as describe below in this same section.

The identifier used for authentication of a user is not well suited as the primary database key for the user since the specific IdP selected by the user for authentication is known to change over time. For this reason the identifier in the example database is a simple GUID which is statistically sure to be unique. Also the example allows for more than one authentication scheme to be enabled by a user. This choice carries some cognitive load for the user as the specific identifier selected by the user at registration must be known by the user at the time of later authentication. For that reason it is best practice for the RP to provide the user with other means to request their authentication (signin) identifier, which is yet another reason for the user to register an email address or phone number to receive the forgotten information.

If the RP registers itself with a federated IdP (like Microsoft or Google) then the user's email address never needs to be exposed to the RP in any situation, only the GUID assigned by the IdP which is put into the signin data table. If the user tries authentication with a dynamically registered IdP with OpenId Connect, then the user's email address must be requested by the RP for the purposes of locating the configuration information of the IdP. Note that the name part of the user email address is not required, but there is unlikely to be any user experience that would allow that distinction. Note that the OpenId Connect compliance certification process requires dynamic registration with a TCP port number, which is bad privacy practice and incompatible with the known naming schemes listed above. That requires special code to be inserted into the example for the sole purpose of OpenID compliance, and is never used in production.

For compliance tests of the RP system by a privacy auditor, the database dump will show that for preregistered federated IDs, the user email address is not stored in the database. It is likely that compliance tests will force the UX to be modified to encourage the user to enter a user name for display within the RP registration name space that is not related to any email or real world name and address. If the RP requires a real-world name and address for its own compliance criteria, then that must remain distinct from the user display name and the user email address. Any real-world identification information must be protected as befits the compliance criteria that the RP chooses to adopt.

Personal Information evaluated for use in the Example

Note that the term Individual here means a human being. That should not be considered to prevent the RP from also supporting non human users.

1. Categories of data editing enabled for users of data contained in the user data base (these categories are shown part of the data base schema, but some fields may change categories as the relationship between the user and RP changes over time):
   1. Required by the operation of the site and not editable,
   2. Required by the site owner but editable by the user,
   3. Optional data editable by the user,
   4. Links from external IdPs that are removable by the user,
   5. Data provided by 3rd parties together with a link to those 3rd parties for redress by the user.
   6. Data provided by 3rd parties can be marked as in dispute by the user if they cannot alter it.
2. Personal data evaluated against the above categories is shown in the following model of the user. Where possible names used in the model match those used in the Open ID Connect standard claims. In those cases the lower case underline separate name was converted to a user friendly spelling and the background highlight with blue. Strictly speaking identity claims data is ONLY relevant in the AspNetUserLogins table, so this linkage is only for convenience as a taxonomy of the element names.

For more information see this page on User Private Information.

Model of the User in the Database

The goal of the data collected (as a User Object) about the individual and organizational users is to model the Users that are served by the web site with User Private Information intended for release by the users. Field names taken from other standards, like Open ID Connect, are highlighted in blue. This is a practice where the RP can determine the category tag used on each data field in advance based on the needs of the site. It may be necessary for the RP get user consent which requires that some fields are dynamically tagged based on user intent or user actions. In those cases a more complex design might be required. For example a deletion date may need to be associated with some fields.

Site documents and user expressed intent

Note that this record (called a User Stipulation) allows a range of responses from the user, such as would be the case if the user accepted data sharing with affiliated companies, but not with unrelated parties.

Schema used in the Example

The flow used is Authentication using the Implicit Flow of OpenID Connect where only the id_token is requested. When using the Implicit Flow, all tokens are returned from the Authorization Endpoint; the Token Endpoint is not used; the authorization ode is not used.

The following is an example request using the Implicit Flow that would be sent by the User Agent to the Authorization Server in response to a corresponding HTTP 302 redirect response by the Client. The use of response mode query is prohibited by "OAuth 2.0 Multiple Response Type Encoding Practices" with bearer token which are not used here. The "OAuth 2.0 Form Post Response Mode" recommends response_mode=form_post which would be the preferred mode.

 GET /authorize?
   response_type=id_token
   &response_mode=query
   &client_id=s6BhdRkqt3
   &redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb
   &scope=openid%20profile
   &state=af0ifjsldkj
   &nonce=n-0S6_WzA2Mj HTTP/1.1
 Host: server.example.com

The following is an example of a successful response using the Implicit Flow (with line wraps for the display purposes only):

 HTTP/1.1 302 Found
 Location: https://client.example.org/oisi?
   &id_token=eyJ0 ... NiJ9.eyJ1c ... I6IjIifX0.DeWt4Qu ... ZXso
   &expires_in=3600
   &state=af0ifjsldkj

The following is one example of the set of Claims (the JWT Claims Set) in an ID Token:

 {
  "iss": "https://server.example.com",
  "sub": "24400320",
  "aud": "s6BhdRkqt3",
  "exp": 1311281970,
  "iat": 1311280970,
  "identity": proofing
  "acr": "urn:us.trustregistry.ONC.AAL2"
  "amr": "urn:us.trustregistry.ONC.TEE"
  "sub_jwk": {
    "kty":"RSA",
    "n": "0vx7agoebGcQSuuPiLJXZptN9nndrQmbXEps2aiAFbWhM78LhWx
    4cbbfAAtVT86zwu1RK7aPFFxuhDR1L6tSoc_BJECPebWKRXjBZCiFV4n3oknjhMs
    tn64tZ_2W-5JsGY4Hc5n9yBXArwl93lqt7_RN5w6Cf0h4QyQ5v-65YGjQR0_FDW2
    QvzqY368QQMicAtaSqzs8KJZgnYb9c7d0zgdAZHzu6qMQvRL5hajrn1n91CbOpbI
    SD08qNLyrdkt-bFTWhAI4vMQFh6WeZu0fM4lFd2NcRwr3XPksINHaQ-G_xBniIqb
    w0Ls1jF44-csFCur-kEgU8awapJzKnqDKgw",
    "e":"AQAB"
 }

ID Tokens MUST be signed using JWS and optionally both signed and then encrypted using JWS and JWE respectively, thereby providing authentication, integrity, Non-Repudiation, and optionally, confidentiality.

• Identity OPTIONAL(not included in the OpenID Connect documentation) Identity proofing indicates the type or locations of the identity proofing that was performed.
• acr OPTIONAL. Authentication Context Class Reference. String specifying an Authentication Context Class Reference value that identifies the Authentication Context Class that the authentication performed satisfied. The value "0" indicates the End-User authentication did not meet any of the NIST SP 800-61-3 criteria.
• amr OPTIONAL. Authentication Methods References. JSON array of strings that are identifiers for authentication methods used in the authentication. For instance, values might indicate that both

An example Claims request included in a GET auth is as follows:

 {
  "userinfo":
   {
    "given_name": {"essential": true},
    "nickname": null,
    "email": {"essential": true},
    "email_verified": {"essential": true},
    "picture": null,
    "http://example.info/claims/groups": null
   },
  "id_token":
   {
    "auth_time": {"essential": true},
    "acr": {"values": ["urn:us.trustregistry.ONC.AAL2"] }
   }
 }

Note that a Claim that is not in the standard set defined in Section 5.1 of the OpenID Connect, the (example) http://example.info/claims/groups Claim, is being requested. Using the claims parameter is the only way to request Claims outside the standard set. It is also the only way to request specific combinations of the standard Claims that cannot be specified using scope values.password and OTP authentication factors were used.

Threat Model

This is a preliminary model based on a sketch made on 2019-10-29

Working Notes

Next steps

Set up goals and start to build examples and best practices for all of the roles in an ID ecosystem.

1. Now that the IDEF has established a self assessment, work on enabling the ID ecosystem needs enable relying parties and other entities to comply.
2. Promote a Trustmark with UX collateral, images of various sizes for web sites.
3. The Kantara web site itself should be an example of Guidelines.
4. There is an IdP which shows the Guidelines for that industry. (The roles of IdP generates identity tokens. It may consume input from user credentials, but not identity tokens.)
5. The UXC work on suggestions for the look and feel of a Guidelines RP.
6. Move the example RP into broad adoptions for relying parties.
7. Preliminary work on the IdP has begun.
8. The best practice protocol for inter op between IAPs and RPs is the OpenID Connect protocol.

Questions and Answers for Designers and Developers

Will need to build for best practices:

• Privacy policy (PP)
• Terms of use (ToU)
• Are there specific ToU and PP provisions that demonstrate how the IDEAL Native App might deal with User Private Information in their policies.

UX Questions Specific to the RP example code

1. Demo verification of email (or cell phone) address - will be needed in the future
2. What are the canonical terms for identification?
   1. logon logout register resign
   2. login logoff create remove
   3. signin signout signup signoff

Other issues to look at:

• Some method for creating a strong web site identity, e.g. Trusted Identifiers.
• Migration of user Identifiers and Attributes from one device to another (possible cloud migration/backup story).
• Recording devices that are under the control of the user together with the device capabilities for data capture and display

Implementation Guidance for the Xamarin Development Platform

• Build your first Xamarin.Forms App
• Charles Petzold ebook on Xamarin Forms slightly out of date
• Add your own URI to a Xamarin App
• File Handling in Xamarin.Forms
• Xamarin Essentials needed for URI capture
• The Launcher class enables an application to open a URI by the system.
• Navigating to a web site
• SQLite problems and workarounds.
• Xamarin.Essentials: File System Helpers -- to use it with OpenAppPackageFileAsync place as follows:
  • Windows Add any file into the root in the UWP project and mark the Build Action as Content
  • Android Add any file into the Assets folder in the Android project and mark the Build Action as AndroidAsset
  • Apple Add any file into the Resources folder in the iOS project and mark the Build Action as BundledResource

Implementation Guidance for Android

• Xamarin for Java Developers.
• API reference for Xamarin Android.
• MSFT Android Emulator
• The Google Android emulator for Windows is recommended over the one from Visual Studio by Microsoft.
• To determine which version of Android SDK to require. For example on 2018-12-18 SDK 25 (Android version 7.1) was supported by 31% of deployed devices.
• Android Emulator on Visual Studio
• Set the appropriate permissions in Android Manifest - ACCESS_NETWORK_STATE INTERNET
• Get Started with Remote Debugging Android Devices will help debugging your agent code that is displayed in the device browser.
• Android Keystore system protects key material from unauthorized use. Firstly, Android Keystore mitigates unauthorized use of key material outside of the Android device by preventing extraction of the key material from application processes and from the Android device as a whole. Secondly, Android KeyStore mitigates unauthorized use of key material on the Android device by making apps specify authorized uses of their keys and then enforcing these restrictions outside of the apps' processes

Implementation Guidance for iOS

When this was written, Visual studio could build solution on windows for UWP and Android, or an MAC for Apple iOS and Android.

Running Visual Studio on MACOS

Since building the solution for iOS with Visual Studio requires at least some of the processing on a MAC computer, the following describes how to use the MACOS as the host of Visual Studio, which can build the solution for either the Android or Apple iPhone.

• Installing Visual Studio 2019 for MAC is described on on this web site.
• The documentation will tell you that the sdk is on this site /Users/username/Library/Android/sdk but it is not shown anywhere in finder.
  • Library is a hidden folder. If you open Finder and click the Go menu and hold the Option key you'll see it there. Or Unhide it by press Command+Shift+ command

Implementation Guidance for UWP

• In order to use .NET Standard 2.0 in UWP, you need to target Fall Creators Update (FCU) as the minimum version of your UWP project.
• Enabling loopback for a UWP application.
• checknetisolation tool.
• Working around the Network Loopback Isolation of UWP Apps has the simplest directions.
• ]https://superuser.com/questions/1329111/make-localhost-server-exempt-from-uwp-app-network-isolation Possible hack around loopback problem] remaps network address.
• For deployments on the Windows Universal Platform
• App capability declarations for access to client and server internet.
• To enable developer mode on any test machine, hit start button and type "for developers" and select button on "developer mode". This will take a while to enable.
• Handle URI activation.
• DEP600 device error is encountered when the incorrect device/emulator/local machine and platform/ARM/X86/x64 is selected in Visual Studio.
• Universal Windows App Data Storage for Admins
• Windows.Security.Cryptography.Core Namespace is needed for crypto in UWP, which is what Xamarin uses on windows.
• Exception thrown in Agent.UWP.exe: WinRT originate error - 0x80070057 : 'FormsCommandBarStyle.xaml is not a valid absolute URI.

  After some investigation, I discovered that if XAML is being used the app needs to be debugged in a container, which presumably VS starts automatically when launching an app the usual way from the VS IDE (e.g. using F5). To get the same result when debugging notifications, services etc., don't use the code shown at the top of this post. Instead open the Properties page for the UWP project, select the Debug pane, and then check the option "Do not launch, but debug my code when it starts". Like magic, debugging of notifications, services etc. works effortlessly. For ref., see https://docs.microsoft.com/en-us/visualstudio/debugger/start-a-debugging-session-for-a-store-app-in-visual-studio-vb-csharp-cpp-and-xaml?view=vs-2017

Testing with IIS Express

By default IIS Express serves only localhost requests. To serve external requests edit applicationhost.config file The rules changed by vw 2017 see https://stackoverflow.com/questions/45986621/visual-studio-2017-giving-remote-users-access-to-website-in-iis-express/50312316

References and Coordination

• The Microsoft web site has a description of the Namespaces in ASP.NET Core that can be used as an alternate identity schema. It was the precursor for the schema used here.

Issues and Comments

• Any comments, suggestions or issues with the best practices or code can be tracked at this site.
• General comments about this web page can be made on the "Discussion" tab at the top of the page.