TrainingSupportCommunity

Optional authorization request parameters

Suggest Edits

In the article Test Hosted Login on the OpenID Connect Playground, we left a few details unexplored; that’s because we wanted to focus on the core activities that the OpenID Connect Playground can be used for and what those activities mean when it comes to user logins and registrations. Because of that, we focused on the parameters required to create an authentication request, and set aside additional parameters that, while useful, might have muddied the introductory waters. This article is focused exclusively on some of the authentication requests parameters we ignored in the other article, including:

  • Scope (scope)
  • Prompt (prompt)
  • Display (display)
  • UI Locales (ui_locales)
  • Max Age (max_age)
  • Nonce (nonce)

Two things we should note here. First, even this article doesn’t cover all the remaining authentication request parameters; for example, we have a separate article that details the use of the claims parameter.

Second, although this article focuses on using the OpenID Connect Playground, all the parameters discussed here are valid OpenID Connect (OIDC) parameters; these aren’t “custom” parameters available only if you’re using the Playground. The Playground is nice because it provides a graphical user interface handy for constructing authentication requests, and it offers a quick and easy way for you to experiment with different parameters and parameter values. But all the authentication requests you create in the Playground, including requests that use these heretofore-neglected parameters, can be copied and used elsewhere exactly as is. After all, that’s what the Copy button is for:

Now let’s get started.

Scope

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
 &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://oidc-playground.akamai.com/redirect_uri
 &code_challenge=x5p09BlxdF03wCKmc7G4xPL45cqKXwdWgIBwtDfW2CI
 &code_challenge_method=S256
 &prompt=login
 &display=popup
 &max_age=43200
 &response_type=code
 &scope=openid
 &ui_locales=da-DK
 &nonce=tyawebd37wndksdjk
 &state=Ono_YibWyCuAyDc6cipmWAodFUfPPgsY_j0_m290Txk

It probably doesn’t come as a major surprise that the Scope section is used to specify the OIDC scopes (for our purposes, the user profile information) that you want to have readily-accessible from the userinfo endpoint following a successful authentication. By default, the scope is set to openid, a scope that all OIDC authentication requests must include (at the OIDC playground, the openid scope is automatically added to each authorization, and cannot be removed.):

If you click the Scope dropdown, you’ll see that additional scopes available to you:

To add any of these “extra” scopes, just click the appropriate item. For example, here we’ve added the email and address scopes:

What if you change your mind and don’t want the email scope after all? That’s fine; just click the little X next to email and that scope will be removed:

That’s all there is to it.

Prompt

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
 &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://oidc-playground.akamai.com/redirect_uri
 &code_challenge=x5p09BlxdF03wCKmc7G4xPL45cqKXwdWgIBwtDfW2CI
 &code_challenge_method=S256
 &prompt=login
 &display=popup
 &max_age=43200
 &response_type=code
 &scope=openid
 &ui_locales=da-DK
 &nonce=tyawebd37wndksdjk
 &state=Ono_YibWyCuAyDc6cipmWAodFUfPPgsY_j0_m290Txk

The prompt parameter specifies which screen (if any) appears when a user makes an authentication request. By default, whenever a user makes an authorization request Hosted Login checks to see if the user currently has a valid session. If the user does have a valid session then he or she is logged on using the previously-suppled credentials. If the user doesn’t have a valid session then the standard Hosted Login sign-in screen is displayed:

That’s the default behavior, and, if you leave off the prompt parameter that’s what you’ll get. If you prefer, however, you can include the prompt parameter and set it to one of the following values:

  • none
  • login
  • create

And then what? Well, if you set the prompt parameter to login the sign-in screen is always displayed, even if the user already has a valid session. In other words, the user will always be required to authenticate regardless of their session status. For example, suppose a user is logged on to Site A. Without logging off, and from the same browser, tab the user visits Sites B, C, D, and E and then returns to Site A. Although the user still has a valid session for Site A, he or she will be asked to reauthenticate.

If the prompt parameter is set to create then the registration screen is always displayed, even if the user already has a valid session (and already has a valid account):

You need to be judicious about using the create prompt. Why? Well, for one thing, a user can’t log on from the Create a New Account screen. That just won’t work. And you can’t try to re-create your existing account; that also fails:

The create prompt is only for new users, not for existing users.

And if prompt is set to none? Well, in that case neither the sign-in screen or the registration screen is displayed. Instead, Hosted Login checks to see if the user already has a valid session. If they do, then the user is automatically authenticated. If they don’t, an error is returned:

Display

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
 &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://oidc-playground.akamai.com/redirect_uri
 &code_challenge=x5p09BlxdF03wCKmc7G4xPL45cqKXwdWgIBwtDfW2CI
 &code_challenge_method=S256
 &prompt=login
 &display=popup
 &max_age=43200
 &response_type=code
 &scope=openid
 &ui_locales=da-DK
 &nonce=tyawebd37wndksdjk
 &state=Ono_YibWyCuAyDc6cipmWAodFUfPPgsY_j0_m290Txk

The display parameter defines the location of the sign-in dialog box. If you select page, then, when you submit your authentication request, you’ll be redirected to a separate page that contains the sign-screen (and nothing but the sign-in screen):

After you’ve successfully logged on you’ll be redirected to the page specified in the redirect_uri parameter. This is the default behavior: if you omit the display parameter the sign-in screen will appear on its own page, separate and distinct from the page you started on.

So what happens if you get redirected to a login page but then click Cancel Request? In the case of the OpenID Connect Playground, you’ll see the following message:

And though it probably goes without saying, clicking Start Over enables you to start over.

By comparison, setting the display parameter to popup does not redirect you to a standalone login page. Instead, the login page appears in a pop-up window, no redirection required:

If you enter your email address and password and then click Sign In, you’ll be logged on, the popup window will disappear, and you’ll be redirected to the appropriate page:

It’s just an alternate way of displaying the sign-in screen.

UI Locales

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
 &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://oidc-playground.akamai.com/redirect_uri
 &code_challenge=x5p09BlxdF03wCKmc7G4xPL45cqKXwdWgIBwtDfW2CI
 &code_challenge_method=S256
 &prompt=login
 &display=popup
 &max_age=43200
 &response_type=code
 &scope=openid
 &ui_locales=da-DK
 &nonce=tyawebd37wndksdjk
 &state=Ono_YibWyCuAyDc6cipmWAodFUfPPgsY_j0_m290Txk

The UI Locales (ui_locales) parameter specifies the language and locale used to render your Hosted Login screens. Set ui_locales to English (en-EN) and your screens will be displayed in English. Set ui_locales to French and your screens will be displayed in French. Pretty straightforward, right? Right.

Well, OK, that’s mostly right. As straightforward as that seems, however, there are a couple of things you need to be aware of.

For starters, keep in mind that Akamai only provides screen text in English; if you want to display your screens using French or Italian or Arabic or Mandarin or whatever, you’ll have to create those translations and add them to your flow yourself.

📘

How hard is that going to be? Well, it can be a little time-consuming, but it’s really not all that hard. See the article Localize screen text for a guide to localizing your Hosted Login screens.

So that’s one thing to remember: you can’t just say, “Display my Hosted Login screens in Swahili” and expect those screens to magically appear in Swahili. It doesn’t work that way.

Another thing to remember is this: your ability to specify a UI locale other than English depends on the UI locales defined in your flow. (In the Hosted Login world, each OIDC login client must be associated with an application client, and each application must be associated with a specific version of a specific flow (a JSON file that, among other things, tells you which locales are available for use.)

So what does that actually mean? Well, if you enter an invalid locale (either because you used the wrong language code or because that locale isn’t specified in your flow) Hosted Login simply ignores the ui_locales parameter. For example, suppose you set ui_locales to Dutch (nl-NL), but Dutch isn’t one of the locales defined in your flow. In that case, the ui_locales parameter is ignored and Hosted Login displays your screens in English:

Now here’s a variation on that theme. Suppose Dutch is a valid locale (i.e., it’s in your flow) but you haven’t added any translations: there isn’t a single word of Dutch to be found anywhere in your flow. So what happens if you set ui_locales to Dutch? This happens:

That might look like some sort of Hosted Login malfunction, but, remember, Hosted Login is only doing what you asked it to: you asked it to display a screen using Dutch translation values and that’s what it did. It’s not Hosted Login’s fault that you don’t actually have any Dutch translation values. The moral of the story? Add all your translation values to the flow and then change the UI locale. Don’t do it the other way around.

By the way, you can include multiple languages in the ui_locales parameter. For example:

Why would you do that? Well, in the preceding example, we’re telling Hosted Login to display our screens using Spanish as spoken in Mexico. And what if Mexican Spanish isn’t available? That’s fine; in that case, using Spanish as spoken in Spain. And then if that’s not available, default to English.

A Note About UI Locales and the Identity Cloud OpenID Connect Playground

If you use the OpenID Connect Playground to configure UI locales, you might find yourself wondering why the locales aren’t sorted in alphabetical order. For example, here we see that German comes before Divehi and that Greek comes before English:

As it turns out, however, the locales are sorted in alphabetical order; it’s just that they’re sorted by language code rather than name. Thus German (de) does come before Divehi (dv) and Greek (el) does come before English (en). That’s something to keep in mind when selecting a locale. For example, if you look in the Cs you won’t Chinese listed; that’s because the language code for China is zh. Because of that, Chinese actually comes near the bottom of the list rather than near the top of the list.

Max Age

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
 &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://oidc-playground.akamai.com/redirect_uri
 &code_challenge=x5p09BlxdF03wCKmc7G4xPL45cqKXwdWgIBwtDfW2CI
 &code_challenge_method=S256
 &prompt=login
 &display=popup
 &max_age=43200
 &response_type=code
 &scope=openid
 &ui_locales=da-DK
 &nonce=tyawebd37wndksdjk
 &state=Ono_YibWyCuAyDc6cipmWAodFUfPPgsY_j0_m290Txk

To begin with, we should make it clear that the max_age parameter has nothing to do with the age of the user. Instead, max_age revolves around how long it’s been since the user last authenticated. By using the max_age parameter you can require a user to reauthenticate after a specified amount of time, regardless of whether or not the user still has a valid session.

Here’s (roughly) how the max_age parameter works. Suppose a user makes an authorization request and then logs onto a website at 1:00 PM, and suppose that his or her authorization request didn’t include the max_age parameter. That user then leaves the site without logging off. Because there was no logoff, the user’s session continues to run.

At 1:30 PM the user returns to the website and requests authorization, again making that request without the use of the max_age parameter. Because the user still has a valid session running, he or she will be automatically authenticated, without having to log on. The user hangs around for a while, then leaves the site without logging off. Because there was no logoff, the user’s session continues to run.

At 3:00 PM the user returns and requests authorization again. However, at 2:45 PM the max_age parameter was added to the authorization request, and was set to 3600 seconds (1 hour). Because of that, when the authorization request is received the system checks to see when the user last logged on. The last login, as we know, was at 1:00 PM, 2 hours ago (remember, the user didn’t have to log on at 1:30 PM). Because 2 hours is more than the max_age value of 1 hour, the sign-in dialog box appears and the user has to log on.

Note that the max_age value is only enforced during authentication. Suppose you’re logged on and an administrator changes the max_age parameter to 1 minute. Are you going to be forced to reauthenticate a minute from now? No, at least not as long as you stay on the site. However, if you leave the site and then come back 2 minutes later then, yes, you will need to reauthenticate.

Nonce

https://v1.api.us.janrain.com/e0a70b4f-1eef-4856-bcdb-f050fee66aae/login/authorize?
 &client_id=a123ef65-83dc-4094-a09a-76e1bec424e7
 &redirect_uri= https://oidc-playground.akamai.com/redirect_uri
 &code_challenge=x5p09BlxdF03wCKmc7G4xPL45cqKXwdWgIBwtDfW2CI
 &code_challenge_method=S256
 &prompt=login
 &display=popup
 &max_age=43200
 &response_type=code
 &scope=openid
 &ui_locales=da-DK
 &nonce=tyawebd37wndksdjk
 &state=Ono_YibWyCuAyDc6cipmWAodFUfPPgsY_j0_m290Txk

The nonce helps ensure that the identity token you receive is the same identity token that you requested (in other words, that you got back a token sent in direct response to your authentication request). To use the nonce parameter, simply enter a random string in the Nonce field.

Now, make your authentication request and examine the decoded identity token. You should see a nonce property, and the value should be the same as the value you entered in your authentication request:

If you see the nonce property and if its value matches your original value you can assume that the token you received is legitimate.

Updated 12 months ago