Guide

Upgrade to Hosted Login v2

Suggest Edits

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:

Updated over 2 years ago