Optional authorization request parameters
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 over 1 year ago