Registration Services

There are two ways to help members register a MydexID and PDS:

Option 1: Your application acts as an OpenIDConnect (OIDC) 'Relying Party' (RP) and initiates an OIDC auth flow with our OIDC server using an extra argument in the flow to present our registration form rather than the login form. The member is then returned to your app to complete First Time Connection (if applicable). Or:
Option 2: You can integrate it into your own applications and create the core experience yourself with a custom registration form, so it is seamlessly integrated into your application.

Mydex's recommendation is to use the former (OIDC) flow, which saves you time and effort (you don't need to make your own registration form, and you don't need to worry about the added security burden of having to collect the member's password in a form payload, even though you wouldn't be storing it anyway).

Using the OIDC approach means you completely offload processing or validation of any credentials whatsoever. It is also a faster, more streamlined experience for the member, because they can create their Personal Data Store's Private Key in the same form, as well as set up Multi-Factor Authentication devices if they wish.

Option 1: Delegating the registration process off to Mydex via OpenIDConnect 🔗︎ click to copy

Delegating the registration process off to Mydex is possible (and highly recommended) by using the OpenIDConnect protocol. This means that your application will act as a Relying Party (RP) in an OIDC authentication flow with our OIDC server.

Please visit our overview of OpenID Connect to understand the protocol.

Below is the flow diagram showing how registration via OIDC works. In this diagram, the 'Mydex LaCa' is the Login and Consent App, where a member is taken to either register or login with their credentials.

Registration via OIDC web sequence diagram

Loading the registration form 🔗︎ click to copy

By initiating an OpenIDConnect authentication flow with the custom query parameter action=register appended to the auth URL, will make the Mydex LaCa render a registration form instead of a login form, as shown below.

If you are collecting an e-mail address from your members in your application as a step prior to initiating the registration flow to Mydex's OIDC, you may also append the query parameter email, for example you@example.com. This will pre-fill the email fields in the registration form to save time for the member filling out their registration details. Note that if the e-mail address is already in use in our system, the member will still need to enter a different e-mail address in order to register.

This means your app need never process the MydexID, password or email address in a form hosted on your application at all. Processing registration in this way also carries the benefit of automatically establishing an OIDC session (the member is considered 'logged in' once they return to your app - you won't have to invoke a login flow after registration).

Theming the registration form 🔗︎ click to copy

Theming of the registration (and login) forms to present a consistent experience with your own application's style guide is possible. Mydex hosts the assets for that theme in the LaCa. It is the responsibility of the Subscriber to provide the assets to Mydex. Please contact us to discuss further if you'd like to explore this option.

Sample application to perform registration 🔗︎ click to copy

To view a sample Python Flask application that uses OpenIDConnect with the Mydex Sandbox, please click here to see our Developer API Example git repository. If you uncomment the "action": "register" in the request's parameters in the python script, it will load the registration form instead of the login form.

Option 2: Using your own registration form 🔗︎ click to copy

🔗︎ click to copy

To register via your application, an individual needs to:

choose their own username which we call a MydexID
provide an email address
create a password

The technical instructions for sending this information from your form to our API using your Dedicated Connection is described in Scenario 1 of the PDX API documentation.

As part of the registration process, the member is taken to the Mydex Identity Services platform to set up their Private Key. The Private Key is used to encrypt their Personal Data Store (PDS), which is their vault for their personal information they choose to collect and store.

The Private Key is something only they will know, it is how they access the PDS itself and control who can send or collect data from.

Unlike the password for their MydexID, Mydex cannot reset or recover the private key as it is only known to the individual.

The Private Key form is not one that the Subscriber application renders. Instead it happens on the Mydex Identity Services platform following submission of the member details on your form. The link to the Private Key form is returned in the response after submitting the member details and the Subscriber should redirect the member's browser to that link to complete the registration process.

Validation of the MydexID and other attributes 🔗︎ click to copy

When using your own registration form to register a new MydexID and PDS per our documentation, our Identity Services Platform will check the supplied payloads for registering a MydexID, to ensure it meets the following conditions:

That all the required parameters provided by the member are present (mydexid, email, password)
That the MydexID is not empty and not already in use
That the MydexID is alphanumeric in nature
That the MydexID is not made up exclusively of numbers
That the MydexID is a minimum of 3 characters and no more than 60 characters in length
That the email address is not empty and not already in use
That the password is not empty and not the same as the MydexID
That the password is 8 characters or longer.

We recommend that your application also perform its own validation of items 1 through 8 before proceeding to submit the request to our API to process the registration. Although we account for any whitespace by trimming it in our API, we also recommend, and believe it to be good practice, that your registration form trims any whitespace from its input fields.

Don't forget that your POST payload must also contain other attributes not-specific to the member, such as the OAuth2.0 'Authorization' Bearer access token, Connection NID, Connection Token Hash and return_to URL, as per the documentation in the link above.

Mydex will then redirect the member to the Identity Services app to create their Private Key. This form is not part of your own app, but is processed directly at Mydex.

The Private Key form will validate:

That the private key is not empty and not the same as the MydexID
That the private key is not the same as the password
That the private key is not less than 8 characters and not longer than 128 characters
That the terms of service have been accepted.

Assuming that all validation passes, the member will be registered, their PDS created, and the member's browser will be redirected back to your return_to URL.

Next steps after registration 🔗︎ click to copy

That's it for registration of a MydexID. To login and logout with a MydexID, please see the authentication documentation.

Should you wish to interact with the newly-registered member's Personal Data Store (PDS) using your Dedicated Connection, you can then initiate the First Time Connection journey, upon which the newly-registered member will be taken to the Data Sharing Agreement page to approve the connection of their PDS to your application.

As soon as they approve the Data Sharing Agreement, they are returned to your own application journey so they can continue as an authenticated user connected to your service, and your application also receives a POST payload from the PDX API containing special cryptographic information for reading or writing to the member's PDS.

Back: Getting Set Up Next: Authenticating with MydexID