Prompts API support

[KostyaZgara]

Do you planing add supporting to enable new login experience? I see API already exists https://auth0.com/docs/api/management/v2/#!/Prompts/get_prompts but there no interface for using this API in deploy cli.

Thank you in advance for your response!

[seancribbs]

I've tried this multiple times, and the tool prints that it is attempting to fetch the data, but nothing is written to disk:

2020-06-30T22:51:10.566Z - info: Retrieving prompts data from Auth0

However, the code here returns early if the prompts property is not on the client: https://github.com/auth0-extensions/auth0-source-control-extension-tools/blob/master/src/auth0/handlers/prompts.js#L14-L17

I checked the node-auth0 client, and it indeed has a manager for prompts, but it is not exposed on the client in the prompts property: https://github.com/auth0/node-auth0/blob/master/src/management/index.js#L160-L337

It looks like the prompts property addition was merged and then later reverted. Is there a reason why it was reverted?

[smcl]

Weirdly the README.md says you should ensure that the client you use has read:prompts and update:prompts scopes, so it'd be easy to incorrectly assume this is supported. If prompts isn't supported could we at least update the README.md?

[mendhak]

Any info on this? This would be a useful feature to have, and lets us keep our configuration managed and in source control. Based on what @seancribbs said it feels like some of the building blocks are already in place?

[smcl]

It would be really nice to have this - we have a repository that manages our Auth0 tenants using this tool and it's really nice, but having to maintain the prompts separately is bit of a pain :(

[willvedd]

Thanks for opening this ticket. I believe that prompts have made their way into the deploy CLI, or at the very least there are relevant handlers for them in the codebase. I can't track down exactly when or where they were added due to some hazy git history, but it does appear that the functionality exists. I'm going to close this issue but please feel free to open a new issue if the current prompts implementation is unsatisfactory.

[atambo]

@willvedd I don't think prompts support has been implemented yet. I don't see any code in this codebase related to prompts at all.

[willvedd]

@atambo You're correct, my mistake. It appears that there is a prompts API handler, but no correlating JSON or YAML handlers. Parity with the Management API, including prompts, is an initiative that we want to address soon. I can't make any firm commitments but keep a look out for it in the future. In the meantime, I'm happy to reopen.

[rejeep]

I don't understand why the authentication profile is reset on "import" then? We have selected "Identifier First" in the UI, but as soon as we import, it changes back to "Identifier + Password". That means we can't use this tool as we would (very quickly) have to manually go in and change it back on each import (in all tenants). If it wasn't updated on import it would at least have been at reasonable solution until support is implemented.

[willvedd]

Folks, I've had a chance to look into supporting prompts but would like some feedback before I proceed too much further.

Firstly, in terms of entities and endpoints, are most people here interested in managing the "Prompts Settings" or the "Custom text for a prompt"?

The "prompts settings" is a small collection of properties pertaining to the authentication flow. Example:

{
  "universal_login_experience": "",
  "identifier_first": false,
  "webauthn_platform_first_factor": false
}

The "custom text for prompts" is the set of text that maps to various screens and languages. Example for signup password screen in English:

{
  "signup-password": {
    "buttonText": "Continue",
    "description": "Set your password for ${companyName} to continue to ${clientName}",
    "editEmailText": "Edit",
    "editLinkScreenReadableText": "Edit email address",
    "emailPlaceholder": "Email address",
    "federatedConnectionButtonText": "Continue with ${connectionName}",
    "footerLinkText": "Log in",
    "footerText": "Already have an account?",
    "invitationDescription": "Sign Up to accept ${inviterName}'s invitation to join ${companyName} on ${clientName}.",
    "invitationTitle": "Accept your invitation to sign up | ${clientName}",
    "loginActionLinkText": "${footerLinkText}",
    "loginActionText": "${footerText}",
    "logoAltText": "${companyName}",
    "pageTitle": "Create a password to sign up | ${clientName}",
    "passwordPlaceholder": "Password",
    "passwordSecurityText": "Your password must contain:",
    "separatorText": "Or",
    "title": "Create Your Account",
    "usernamePlaceholder": "Username"
  }

If folks are primarily interested with managing the prompts settings, thats easy enough to support. However, I suspect that the main request is to manage the custom text instead; I can see the value in having these settings pull in bulk. The issue here is that the API requires the custom text to be fetched per-screen and per-language. There are 25 screens and roughly 30 supported languages, I don't think I'd advocate for iterating naively through both sets to fetch all custom text settings for every invocation of the tool. Certainly there are some optimizations that could be added like only fetching languages supported in the tenant locale setting, or perhaps having a manual override, but there will still be a large performance cost here.

TLDR: would be great to get answers to these questions:

• What prompts functionality is most useful: prompts settings, custom text for prompts, or both?
• If wanting to manage custom text for prompts, is it safe to assume that the tenant languages match the translations you wish to manage through prompts?
• How much of a performance hit are you willing to take to manage prompts? Would you prefer to opt-in?

[mendhak]

Hello, I'll share my answers. For my teams it would be "custom text for prompts". I think it's safe to assume by my tenant's language, but if specifying the language makes the implementation easier, happy to do that. Performance isn't really a concern since we're only deploying at most, few times a day.

[atambo]

My company would be more interested in the “custom text for prompts” feature to be able to customize all of the text on the new universal login experience. The assumption of tenant language matching the translations would work for us. As for performance, the importing/exporting of configuration is not something we care about being fast as it only happens in CI or testing and we don’t change it very often.

[rejeep]

Thanks @willvedd for taking the time to look at this!

What prompts functionality is most useful: prompts settings, custom text for prompts, or both?

Both, but "prompts settings" is much more important for us.

If wanting to manage custom text for prompts, is it safe to assume that the tenant languages match the translations you wish to manage through prompts?

Yes

How much of a performance hit are you willing to take to manage prompts? Would you prefer to opt-in?

Performance is not a big issue

[smcl]

What prompts functionality is most useful: prompts settings, custom text for prompts, or both?

I work for an org where we keep a script that updates the "custom text for prompts" when our CI runs a0deploy. I'd really appreciate if a0deploy handled this and was able to manage anything the Auth0 Mgmt API uses (it's the weekend so maybe my memory is fuzzy, but iirc we have a couple additional things we have scripts for to workaround missing a0deploy things)

If wanting to manage custom text for prompts, is it safe to assume that the tenant languages match the translations you wish to manage through prompts?

Yes

How much of a performance hit are you willing to take to manage prompts? Would you prefer to opt-in?

I can't speak for people who don't use the prompts API, but since we already hit the APIs individually with our script (inc. some small backoff so we don't breach rate limits) we are ok with a little perf hit ourselves.

[willvedd]

@smcl Thanks for the feedback! We opened #530 which should deliver adequate functionality for managing custom text and prompts settings. Since you have experience in this part of the management API, might be useful to review and see if it captures your use cases.

we have a couple additional things we have scripts for to workaround missing a0deploy thing

As an aside to the topic of prompts, can you explain what additional things are lacking?

[smcl]

@willvedd Certainly, I just checked and there are two branding-related things that we set after auth0deploy:

1. we call the PATCH api/v2/branding endpoint to set our favicon_url, it won't change often but it'd be good to control this at tenant-level since we have a handful of tenants in various locales

2. similarly we hit the PUT api/v2/branding/templates/universal-login one in our CI too, so we can make any updates to our login template

If I should raise something for these specific issues (or a more broad one for branding generally), let me know. Thanks for getting back to us on this, by the way :)

[willvedd]

Good news folks, prompts support has been added to the v7.12.0 release. This includes both updating of prompts settings and custom text for prompts.

The exported config looks something like this:

prompts:
  identifier_first: true
  universal_login_experience: classic
  customText:
    en:
      login:
        description: some description in english
        title: some title in english
        buttonText: some button text in english
      signup-password:
        buttonText: some button text in english
        description: some description in english
        editEmailText: Edit
    fr:
      login:
        description: some description in french
        title: some title in french
        buttonText: some button text in french

Please note:

• No deletion support – At this moment, only creates and updates are applied to custom text. The diff'ing engine doesn't evaluate and determine deletions. I don't believe this to be an issue because the existence of unused custom text settings should be inconsequential.
• Performance – Managing the custom text settings requires many network requests. As an optimization, for exports, the tool will only retrieve custom text settings for languages that are enabled on the tenant level. For imports, the tool will only apply changes that are defined in your configuration files.

I encourage everyone to update and give it a go. Really appreciate everyone's patience and feedback with this one!

[rejeep]

@willvedd I tested this feature now but it didn't work. I updated prompts/prompts.json to include this (export from another tenant):

{
  "universal_login_experience": "new",
  "identifier_first": true,
  "webauthn_platform_first_factor": false
}

But it didn't update the "Authentication Profile". The logs says "Updated [prompts]: Prompts settings and prompts custom text".

Anyone else with the same issue?

[andrewclaus]

I am attempting to update the custom prompts with a0deploy 7.12.2, but I am getting this error:

error: Problem running command import during stage processChanges when processing type prompts
error: Screen "title" must be a non-empty object.

My yaml file looks like:

prompts:
  universal_login_experience: new
  identifier_first: true
  webauthn_platform_first_factor: true
  customText:
    en:
      login-id:
        title: "Hello!"
        pageTitle: "Log in"

I tried without quotes, and with a couple different properties. The error always shows up on the first property

[andrewclaus]

I am attempting to update the custom prompts with a0deploy 7.12.2, but I am getting this error:

error: Problem running command import during stage processChanges when processing type prompts
error: Screen "title" must be a non-empty object.

I was able to fix this after reading this pull request: https://github.com/auth0/auth0-deploy-cli/pull/541

I was missing the "screen" object, which is under the "prompt" object, see:

prompts:
  universal_login_experience: new
  identifier_first: true
  webauthn_platform_first_factor: true
  customText:
    en:
      login-id:
        login-id:
          title: "Hello!"
          pageTitle: "Log in"

[smcl]

Thanks for implementing this @willvedd - I only just got round to trying it out now.

@rejeep did you get this working in the end? I've added a file prompts/prompts.json to our config, and it looks a little like the below:

{
    "universal_login_experience": "new",
    "identifier_first": true,
    "webauthn_platform_first_factor": false,
    "customText": {
        "en": {
            "login": {
                "login": {
                    "pageTitle":"TEST",
                }
            }
        }
    }
}

But I get the same as you - when we run a0deploy (a0deploy import -c config-dev.json -i . in my case) all the other things (resource servers, clients, etc) are still updated fine, and the below text is printed ...

...
Updated [guardianFactorTemplates]: {"name":"sms"}
Updated [prompts]: Prompts settings and prompts custom text
Updated [databases]: {"name":"****","id":"****"}
...

... but the prompts don't get updated. I'm on version 7.14.1 of the a0deploy tool. Trying to figure out what's going on here and I'm a bit puzzled.

[artstupels]

You will need to split your file into two files: prompts.json and custom-text.json

prompts/prompts.json

{
  "universal_login_experience": "new",
  "identifier_first": true,
  "webauthn_platform_first_factor": false
}

prompts/custom-text.json

{
  "en": {
    "login": {
        "login": {
            "pageTitle":"TEST"
        }
    }
  }
}

[smcl]

This worked for me. Cheers!

[rejeep]

@rejeep did you get this working in the end?

No, unfortunately not

[smcl]

@rejeep did you get this working in the end?

No, unfortunately not

You try out the suggestion in the reply I got a little further up. We’re meant to separate the prompts and custom text JSON files. Once I did that it worked nicely.

[rejeep]

@rejeep did you get this working in the end?

No, unfortunately not

You try out the suggestion in the reply I got a little further up. We’re meant to separate the prompts and custom text JSON files. Once I did that it worked nicely.

Yes I did that. I used the export task and then they were already split up like that.