Optional Configurations
Additional Parameters
For step 3 of the OIDC Playground, you can leave this section as-is or modify for customization of your testing.
Configurable Parameters:
Recommended value: code
OAuth supports several different authorization grant types. As a best practice, Hosted Login supports the Authorization code grant. With this grant type, the authorization endpoint returns a special one-time code back to your site or application. This code can then be exchanged for an access token, a refresh token, and an identity token. For more information, see An introduction to OAuth 2.0 and OpenID Connect.
The Authorization code grant must be specified in the OpenID Connect request by setting the response_type parameter to code.
Although other response types are supported for certain use cases and compatibility needs, only the code type should be used with this Getting Started Guide and the OIDC Playground.
Other supported response types:
- id_token - Returns an identity token directly back to your site or application, skipping the code-for-token exchange. Care must be taken when using this response type in case the token contains PII (Personally Identifiable Information).
- token - Returns an access token directly back to your site or application, skipping the code-for-token exchange. This is considered insecure and is a deprecated flow in the OAuth 2.1 draft spec. Use of this response type should be strictly limited to legacy applications that are unable to use the code flow.
Must include: openid
The scope parameter is used to specify what user information you’d like to retrieve immediately when a user logs in. You can request more than one scope in this parameter.
Possible scope values:
- openid - Special scope that identifies your request as an OpenID Connect request, and must be included for Hosted Login to work properly
- profile - Requests the following user data: full name, surname (last name), given name (first name), middle name, preferred username, gender, birthdate, and date of last profile update
- email - Requests the user’s email address and whether or not the user verified their email address (true or false)
- address - Requests the user’s mailing address
- phone - Requests the user’s mobile phone number and whether or not the user verified their mobile phone number (true or false)
Would you like to request user data that is not contained within the above scopes? You can use custom claims for this - see the Additional Claims section below.
For more information on scopes, see Scopes and claims.
Overrides the default behavior when a user takes an action on your site or app that requires authentication. Example user actions are loading a page or clicking a button.
If this parameter is omitted, the default behavior will be preserved: Hosted Login will look for an existing valid session and, if found, the user is automatically authenticated and can seamlessly continue. If a valid session is NOT found, the user will be prompted to sign in.
Possible prompt values:
- none - Hosted Login will look for an existing valid session and, if found, the user is automatically authenticated and can seamlessly continue. If a valid session is NOT found, instead of prompting the user to sign in, a login_required error is returned. In other words, this option suppresses the display of Hosted Login screens to the user.
-
Scenario ou want to provide a hidden Single Sign-On (SSO) experience to your end users when they navigate between your sites. In such case, you can call Hosted Login with prompt=noneto secretly check for a valid Hosted Login session when they navigate to one of your sites. If a valid session is found, you can automatically log them in. If a valid session is NOT found, you can do nothing and allow them to sign in per usual if they so choose. |
-
- login - The user will be prompted to sign in, regardless of having an existing session from a previous login or not.
- This option is better suited where it’s most important to you to increase security around the action being taken.
-
Scenario et’s say user A logs into your site at a shared computer and forgets to log out, then user B hops on the same computer. If user B is malicious, they could take actions in user A’s account with the existing session. However, if certain sensitive actions call Hosted Login with prompt=login, user B will be unable to continue those actions without proving ownership of the account. |
- create - The user will be prompted to create an account, rather than shown the sign-in screen.
- This option is better suited where you have a call-to-action specifically for creating an account, and do not want to provide the option to sign in.
-
Scenario ou have a promotion that only applies to new customers. You provide a “Sign up to get 20% off my first purchase” button. Clicking the button calls Hosted Login with prompt=createto present the registration screen to the user, and does not give the option for an existing user to sign in. |
Can be used to override the default display behavior of Hosted Login with a popup.
If this parameter is omitted, the default behavior will be preserved: The Hosted Login screens will be displayed as full pages within the same browser window as your site or app.
Possible display values:
- page - Same as the default behavior. You can either omit the display parameter or set
display=pageto get the exact same result: The Hosted Login screens will be displayed as full pages within the same browser window as your site or app. - popup - Instead of the default “page” display behavior, the Hosted Login screens will be displayed in a smaller, separate browser window that overlays your site or app’s browser window, giving the effect of a popup.
NOTE! The rendering of the popup is NOT automatically done for you by Hosted Login. In this case the OIDC Playground reads the display parameter and renders the Hosted Login screens in a popup if specified. If you want the same functionality in your own site or app, you will need to add code to your site or app to do the same.
Overrides the default language used in Hosted Login screens. This value must match (or at least partially match) a locale defined in your Registration Flow configuration.
If this parameter is omitted, Hosted Login will use the browser’s language setting. If the browser’s language setting does not match a locale defined in your Registration Flow configuration, then the default locale will be used: en-US (American English)
If you’d like to present the Hosted Login screens to the user in a different language, you must follow a 2-step configuration process:
- Modify your Registration Flow configuration to add the new locale and translations. For instructions, see Add a locale to a flow.
- Include the
ui_localesparameter in your call(s) to Hosted Login with the new locale as the value. Example:ui_locales=fr-CA(Canadian French)- Alternatively, you can omit the
ui_localesparameter and Hosted Login will use the browser’s language setting.
- Alternatively, you can omit the
For more information on the ui_locales parameter, see UI Locales.
Overrides the default max age (specified in seconds).
Specifying the max age in your call to Hosted Login is your way of saying “the user is only allowed to take this action if they’ve signed in within the last X amount of time.” If the max age has been reached, a user attempting the action will be prompted to sign in again in order to continue.
If this parameter is omitted, the user will be prompted to sign in if 30 days has passed since their last login.
The actual value being used by default is 2592000, which is 30 days specified in seconds.
Good to know:
- If you want to override the max age globally (for your Registration application), use the
authorization.rules.auth_ttlsetting in Global Settings - If you want to override the max age per property (per customer-facing site or app), use the
authorization.rules.auth_ttlsetting in Settings for the applicable property or properties - If you want to override the max age per transaction (per specific API call to Hosted Login), use this
max_ageparameter
For more information on the authorization.rules.auth_ttl setting, see Authorization rules.
| Scenario |
|---|
Let’s say user A logs into your site at a shared computer and forgets to log out, then user B hops on the same computer. If user B is malicious, they could take actions in user A’s account with the existing session. However, if certain sensitive actions call Hosted Login with max_age=1800 (30 minutes), the window of opportunity for user B to continue with those actions is greatly decreased. Note: You can alternatively use prompt=login for sensitive actions, which behaves the same as max_age=0. |
Optionally used for added security.
A “nonce” in this context is a random, case-sensitive string that you pass to Hosted Login, and in turn Hosted Login will pass back an ID Token containing the same string. This allows for verification of the returned ID Token and prevents replay attacks.
For more information, see Nonce.
Click NEXT.
Additional Claims
For step 4 of the OIDC Playground, you can leave this section as-is or modify for customization of your testing.
Standard claims can optionally be used if you’d like to request individual fields of standard data instead of (or in addition to) asking for groups of standard data via the scope parameter.
Custom claims can optionally be used to request user data other than the standard fields. For example, if you add a custom attribute to the schema to store the user’s favorite color, you can use Custom Claims to request access to that additional data.
For more information on claims, see Scopes and claims.
Click FINISH.