RP IDs and Facet IDs

fFirst, let’s establish some definitions to provide context for what you need to do.

• Relying Party: The organization responsible for registering and authenticating customers. Typically, the relying party has implemented one or more web or mobile apps for their customers to use. This is your organization.

• Web Origin: The source of a request. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it. The default port for the https scheme is 443.

• Facet ID: A unique identifier (URI) for a platform-specific implementation of your app (application used by your customers on their devices). For example, if you have a web-implementation and Android-implementation of your app, each of these must have a different facet ID.

• Web applications: The facet ID must be the web origin of the web page that triggers a FIDO operation.

• Android apps: The facet ID contains the Base64 encoding SHA-256 hash of the APK signing certificate and is of the form android:apk-key-hash:<hash-of-apk-signing-cert>.

• iOS apps: The facet ID contains the bundle ID of the app, written as ios:bundle-id:<ios-bundle-id-of-app>. A bundle ID uniquely identifies an app in Apple’s ecosystems.

In addition to letters and digits, only the following characters are allowed in a facet ID: hyphen (-), underscore (_), plus (+), colon (:), forward slash (/), period (.), equals (=), hash (#), and double backslash (\\). An attempt to enter any other special character results in an error message.

• RP ID: A domain, like acme.com. The RP ID does not include the scheme or port. It cannot contain any paths. It can include one or more subdomains, however, this limits key sharing to a subdomain.

How Facet IDs and RP ID Are Used

In the following explanation,

• Client app refers to the Web or mobile app that you implemented for your customers to use.

• Your website refers to the Website you implement.

• The Auth Server refers to the Digipass S3 Server. You configure the Auth Server with your RP ID and facet IDs for all your apps.

When a client app initiates registration or authentication with your Website, that request is routed to the Auth Server. The Auth Server sends a message to the client to start the operation.

When a web or hybrid-mobile client app receives the message from the Server, it compares the RP ID to the domain of the client app's origin. If the RP ID matches the client app's origin, the client app responds to the Server’s message by prompting the user to register or authenticate and then sending back the result.

When the client sends a request to finish registration or authentication, the Auth Server examines the message sent from the client and compares that app’s facet ID to its list of known facet IDs. If the facet ID matches, the Auth Server continues to process the message. If the facet ID is not in the list of known facet IDs, the Auth Server drops the message and the operation does not proceed.

A native Android app that you implement has a unique use for RP ID. When it is installed, it verifies that it is authorized to open any URL links that match your website’s domain (or RP ID). It does this by checking if its facet ID is listed in a publicly-accessible file called assetlinks.json which must be hosted at your website. For a complete description of how to create assetlinks.json and where to host it, see section Creating your digital asset links file.

The app constructs the URL for assetlinks.json by using the RP ID and convention that the file is located in the path /.well-known and the port is 443 For example, if the RP ID is acme.com, the URL for assetlinks.json is https://acme.com/.well-known/assetlinks.json.

The app accesses the file to check if its facet ID is present. If assetlinks.json contains the facet ID, then Android routes all URLs that match the RP ID to your app rather than opening the URL in a browser.

In conclusion, the RP ID and facet IDs are two halves of a whole. Web and hybrid-Android client apps use the RP ID to validate that they can respond to requests originating from a URL that contains the RP ID as its domain. Android uses the RP ID to verify that your native Android app can open URL links from a particular website and to identify URLs to route to your app. The Auth Server only processes requests from apps whose facet IDs are contained in the Auth Server’s known facet ID list.

The Relationship Between RP ID and Facet IDs of Web Apps

There can only be one RP ID for your organization, this has implications if several departments within your company plan to implement web apps. Each of those web apps must have a unique facet ID which is the web origin of their home page. Since those web apps are all hosted by your organization, the domain of those facet IDs must be identical to the RP ID. If the facet ID’s domain differs from the RP ID, the client app rejects communications from the web app.

The diagram below illustrates how the effective domain can be determined for four different facet IDs.

Figure 4 Determining the domain from a web facet ID

• https://x.y.z.acme.com: This facet ID works for an RP ID of acme.com. The subdomains (x.y.z) are ignored.

• https://example.com:1234: This facet ID works for an RP ID of example.com. The port number is ignored.

• https://omega.com:888/marketing: This facet ID works for RP ID omega.com. The path (/marketing) and port are ignored.

Example 1

Acme has 6 subsidiaries that plan to implement web applications. Their proposed facet IDs are listed below.

Planned RP ID: acme.com

You can’t change the RP ID because there is no single RP ID that works for the facet IDs listed above. The departments whose facet IDs don’t include acme.com need to change their facet ID to have the same domain or use https.

Example 2

You can make a domain more restrictive by specifying one or more subdomains.

Omega has 4 departments that plan to implement web applications. The department’s proposed facet IDs are listed below.

Planned RP ID: platform.omega.com

As long as platform.omega.com/marketing is changed to https://platform.omega.com/marketing, the RP ID works. Omega.com also works as the RP ID in this example.

Example 3

This example focuses on which websites and mobile apps can interact with Zeta’s mobile apps and Server, given a specific configuration.

Zeta’s app development department has implemented 2 web apps and 3 Android apps. They have set up their RP ID, facet IDs, and assetlinks.json as shown below. The Android apps will not work with RP ID agile.zeta.com, can you identify the reason?

Solution: The URL for assetlinks.json should be https://agile.zeta.com/.well-known/assetlinks.json because the RP ID is agile.zeta.com.

Assume that assetlinks.json is hosted at the correct location with the same configuration shown above. The table below lists the outcome when a mobile client app receives a request from a website to start a FIDO operation.

The table below lists the outcome when several web and mobile apps request that the Auth Server process a FIDO operation.