User login with the hosted screens is one of the most straightforward workflows when working on your Next Identity Hosted Journeys integration.

In this journey, the user will be presented with an input screen asking for a primary identifier (email address or mobile phone number, depending on your specific configuration) and will be asked to input a password if applicable.

This flow begins with your application directing users to the hosted /authorize endpoint.

Endpoint URL

The login request consists of the base domain + the endpoint (/authorize) + parameters. Available parameters are listed below the example.

https://id.eu.nextreason.com/
authorize?
redirect_uri=https%3A%2F%2Fappauth-js.dev.nextreason.cloud%2Fapp%2Fredirect.html
&client_id=pnxf3up7tae8mbhzb9dbpbcmfbx32qjp
&response_type=code
&state=SWMsxiZSaa
&scope=openid
&nonce=ztUpfEKkX7HcpASapzJDSFsBoFBbvRkNdDGEVj5TDrG58e7MwS
&ui_locales=en-US
&code_challenge=Pr5KkBc1CqsjVH5Izsx-CXu1HEOrtNLBPJU20-MMGWw
&code_challenge_method=S256

Required Parameters

The following parameters must be included on every /authorize request.

Parameter	Description
`redirect_uri`	Configures the URL the user is redirected after a successful authentication. Important note*: this URL must be included in the safe list configuration. Contact your Next Reason integration consultant to add URLs to this list.
`client_id`	The ID used to authenticate the API call. This client ID is tied to your specific configurations and rules. Contact your Next Reason integration consultant if you do not know your client ID.
`response_type`	Value that determines the authorization processing flow to be used, including what parameters are returned from the endpoints. The only acceptable parameter is: `code`.
`state`	This `state` parameter is constructed by your application and included in the call to the hosted Next Identity service. It will remain unchanged and will be passed back to your application when the screen is redirected back. It is intended for use by your application to track user state. It should be an opaque value used to maintain state between the request and the callback. Typically for applications, Cross-Site Request Forgery (CSRF, XSRF) mitigation is done by cryptographically binding the value of this parameter with a browser cookie. This value is required on every call, but the hosted service does not use this value in any way, it is solely for use by the application. Doing so, the application can check and evaluate the value of the state parameter if it is correct or meets a specified criteria then perform expected actions or user journeys on the application-side.
`scope`	OpenID Connect requests must contain the OpenID `scope` value. If the OpenID `scope` value is not present, the behavior is entirely unspecified. Other scope values may be present. Scope values used that are not understood by an implementation should be ignored. The "`openid`" default value will be used if no specific scope value is known. Other scope values can be added. For multiple scopes, separate them with spaces: `scope1 scope2`. When requesting the `/authorize` endpoint, you can specify the desired scopes using the `scope` parameter. To pass multiple scopes, separate them with spaces, like so: `scope1 scope2`. When making this request in a browser, spaces will be URL-encoded, resulting in a format like `scope1%20scope2`.

Optional Parameters

The following parameters are optional.

Parameter	Description
`prompt`	Space delimited, case sensitive list of ASCII string values that specifies whether the Authorization Server prompts the End-User for reauthentication and consent. The defined values are: `none` The Authorization Server must not display any authentication or consent user interface pages. An error is returned if an user is not already authenticated or the client does not have pre-configured consent for the requested claims or does not fulfill other conditions for processing the request. This can be used as a method to check for existing authentication and/or consent. `login` The Authorization Server should prompt the user for reauthentication. If it cannot reauthenticate the user, it must return an error, typically `login_required`.
`nonce`	String value used to associate a client session with an ID token and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy must be present in the `nonce` values used to prevent attackers from guessing values.
`ui_locales`	Set the language to be displayed in the screen. Session cookie will save the locale setting sent for the first time, if this parameter is not present the latest language saved will be used to display the screen. It allows multiple locales and in case there's no configuration for the first one, it searches for the second one and so on. Since the `ui_locales` parameter is optional and will use the `default_locale` on settings if no value is present. See Localization for list of supported locales and the accepted values. The default country flag during mobile login or when changing the mobile number will be determined by the `ui_locales` in the query string parameters, if the `mobile_query_default_flag` is set in the configuration settings. If not, it will fall back to the `mobile_default_country`, then to the first value in the `mobile_flag_countries` setting, and finally to the `default_locale`.
`code_challenge`	Used in PKCE protocol.
`code_challenge_method`	Used in PKCE protocol.
`login_hint`	If this parameter value is passed with the call to the `/authorize` or `/register` endpoints, the username field on the hosted screen will be pre-filled. This applies for email address or mobile phone number.

Response Handling

The login begins with your application directing users to the hosted /authorize endpoint.

Without an active session in the browser

If the end user does not have an existing browser-based session, the login screen will be displayed. On this login screen, if your application has been configured to allow self-registration, the user will be shown the option to create a new account.

To log in to the application, the user inputs the email address or mobile number and password, depending on the application’s configuration. Based on the settings, the user may then be prompted for two-step verification or two-factor authentication. After entering the verification code, the user will then be redirected to the redirect_uri that was configured in the authorize URL. The Next Identity service will return the authorization code that the application can use to call the /token endpoint.

With an active session in the browser

When the end user requests Next Identity Journeys via the /authorize endpoint, the hosted screen will not present the registration screen if the user already has an active session in the browser. Instead, the end user will be immediately redirected back to the application with an authorization code.

Configuration Options

Configuration Option	Description
Self-registration	Allows to show the self-registration option so user can sign-up on their own.
Authentication Method	Select either email or mobile
Password Option	Show or hide the password option (Password is available for Email/Mobile + Password workflow but it is not available for Email/Mobile + OTP)
Custom Branding	Client has the option to add a brand logo, header logo, background image, favicon, button color and font style in the Authorize Page
Social Login	If configured on the client, social login options will show in the authorize page like Google or Facebook login
Passwordless Authentication button	If configured on the client, passwordless button will show in the authorize page

Error Handling

Code	Error	Cause
No code, error message only	We are unable to process your request right now. Please try again later	Redirect uri is not added in allowlist
No code, error message only	We are unable to process your request right now. Please try again later	The scope, state parameter, or response type is missing in the authorize page
No code, error message only	Incorrect username or password. Please try again	Username or password is incorrect
No code, error message only	You are not authorized to access this application. Please contact the administrator	The client has resource access restrictions, and the user attempting to log in does not have the required permissions
No code, error message only	There was a security error with the form submission	The authorize page is left idle for 2 minutes
No code, error message only	Corrupt image	The assets, such as the logo or image, are pointing to a location that does not exist

Security Considerations

While the state parameter is not directly used within the register endpoint itself, it plays a critical role in ensuring the secure handling of the authorization process that leads to accessing the authorized page endpoint.

Integration

In the application, integrate the /authorize endpoint to a login button or link that when the users click, it will redirect to the Authorization page.
After successful login, user should be redirected to the URL passed in the redirect URL parameter