Registration is straightforward. There are two ways to help members register a MydexID and PDS:
- 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. Or:
- 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).
Mydex's recommendation is to use the latter (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).
To register an individual only needs to
- choose their own username which we call a MydexID
- provide an email address
- create a password
The process of sending this information from your form to our API using your Dedicated Connection is described in Scenario 1 of the PDX API documentation.
See example of a registration form:
As part of the registration process we also set up the individual's Personal Data Store (PDS), which is their own vault for their personal information they chose to collect and store. As part of the set up they asked to create a Private Key.
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.
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 your API key, 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.
Should you wish to avoid handling (or your app is unable to handle) the registration step in your application, 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 instructions for getting started with OIDC.
The only difference with login vs registration, as part of the OIDC auth flow, involves sending an extra argument in the OIDC flow. Beginning a standard OIDC flow, with a query parameter
action=register appended to the auth URL, will result in a redirect from your application to a
registration form on our OIDC platform (rather than a login form, for existing members).
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 of the registration (and login) forms to present a consistent experience with your app is possible, but means Mydex needs to host the assets for that theme, in our OIDC platform. Please contact us to discuss further if you'd like to pursue that option.
That's it for registration of a MydexID. Should you wish to interact with the new member's 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.
See an example of a data sharing agreement presented to the individual to approve:
As soon as they approve this they are returned to your own application journey so they can continue as an authenticated user connected to your service.
If the individual already has a MydexID, They will simply login and approve the data sharing agreement for the first time they connect to your service.