Upgrade to Hosted Login v2
Upgrading to Hosted Login v2
Interested in upgrading to Hosted Login v2 and two-factor authentication but donβt have time to read all that documentation? Well, we recommend that you do read the documentation, and sooner rather than later. But, until then, hereβs what you need to do.
Step 1: Pick an OIDC login client to use with Hosted Login
Itβs probably best if you use the /{customerId}/config/loginPolicies operation and create a new OIDC login client to use with Hosted Login, You can use an existing client if you want: just remember that anyone who uses that client will end up using Hosted Login v2. You might want to test the new version a little before exposing it to a large portion of your end users.
Step 2: Modify the login policy associated with the OIDC login client
Again, our recommendation is that you copy an existing login policy and then use the copy as a template for creating a new Hosted Login v2 policy. However, you can alternatively modify an existing login policy for use with Hosted Login v2. If you go that route, keep in mind that all OIDC clients that use this login policy will run Hosted Login v2. And that could be β¦ interesting β¦ seeing as how login policies can be used by multiple OIDC clients.
Regardless of whether you create a new login policy or modify an existing policy, to upgrade to Hosted Login v2 you need to change the value of the policyβs loginURL property. For example, suppose your current loginURL property is set to this value:
https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/ login
To upgrade to Hosted Login v2, simply insert v2 into the URL:
https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/v2/login
Thatβs all you need to: as soon as you save the modified login policy anyone using a login client associated with this policy will get the Hosted Login v2 login and registration experience.
Incidentally, if you run into problems and no longer want to use Hosted Login v2 you can either assign the OIDC client a new login policy or simply remove v2 from the loginURL property:
https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/auth-ui/login
Step 3: Determine the application client associated with the OIDC login client
Steps 1 and 2 upgrade you from Hosted Login v1 to Hosted Login v2, but these steps donβt enable two-factor authentication. If you want to use 2FA youβll first need to identify the application client used by your OIDC login client. Thatβs done by looking at the login clientβs property values:
"application\_client": {
"href": "/config/79y4mqf2rt3bxs378kw5479xdu/clients/hrhtj4p8dz9wqhwtpuvg2k8ndet748vs"
}
Step 4: Add the authentication.second_factor setting to the application client
In Console (or using the /config/{appId}/clients/{apiClientId}/settings OPERATION) add the authentication.second_factor setting to your application client and then set the value to true. Save your changes and, from that point on, everyone logging on with the application clientβs OIDC client will be required to use two-factor authentication for logins and registrations.
If you encounter problems or you just donβt like two-factor authentication, you can disable 2FA any time you want by setting the value of authentication.second_factor to false.
Step 5: Modify the socialRegistrationForm and the traditionalRegistrationForm forms
In order to provide the optimal user experience, you need to remove the next property (and its value) from the socialRegistrationForm and the traditionalRegistrationForm forms; this can be done by using the PUT method and the /config/{appId}/flows/{flow}/forms/{form} OPERATION. See Modify 2FA registration forms for complete information on what needs to be removed, and how to remove it. In brief, youβll need to remove the following from the socialRegistrationForm form:
"next": {
"else": {
"sendMail": {
"mail": "registrationConfirmation"
}
},
"if": {
"compare": "emailVerified",
"to": null,
"withOperator": "=="
},
"then": {
"sendMail": {
"mail": "registrationVerification"
}
},
"type": "server"
},
Youβll also need to remove these lines from the traditionalRegistrationForm form:
"next": {
"if": {
"compare": "emailVerified",
"to": null,
"withOperator": "=="
},
"then": {
"sendMail": {
"mail": "registrationVerification"
}
},
"type": "server"
},
Step 6: Read the documentation
It never hurts, and almost always helps:
-
Version history. A new page that tracks changes to Hosted Login.
-
Upgrade to Hosted Login v2. A more-detailed guide to Hosted Login v2 and what it means to upgrade.
-
Introduction to 2FA. Enabling and using two-factor authentication for logins and registrations.
-
Introduction to trusted devices.Β Explains the concept of trusted devices and how they affect two-factor authentication.
-
Manage email addresses and mobile device numbers in Hosted Login v2. New security protections have been added to the email and mobileNumber attributes.
-
Use email address verification without 2FA. Making users verify their email addresses even if you decide not to use two-factor authentication.
Updated 8 months ago