Lock Authentication Parameters

You can send parameters when starting a login by adding them to the options object. The example below adds a state parameter with a value equal to 'foo'.

var options = {
  auth: {
    params: {state: 'foo'},
  }
};

The above example would be analogous to triggering the login with https://{yourDomain}/authorize?state=foo&....

The following parameters are supported: scope, device, nonce and state.

Supported parameters

scope

var options = {
  auth: {
    params: {scope: 'openid email user_metadata app_metadata picture'},
  }
};

There are different values supported for scope. Keep in mind that JWTs are sent on every API request, so it is desirable to keep them as small as possible.

The default scope value in Lock is openid profile email. This minimum scope value is required to make the Last time you logged in with feature work correctly.

Running Lock locally

If you don’t manually specify at least the default scope of openid profile email when initializing Lock, and you are running your website from http://localhost or http://127.0.0.1, you will get the following error in the browser console:

Consent required. When using getSSOData, the user has to be authenticated with the following scope: openid profile email

That will not happen when you run your application in production or if you specify the openid profile email scope. You can read more about this in the User consent and third-party applications document.

For more information about scopes, see the scopes documentation page.

Example: retrieve a token

In Lock, if you wish to receive a token with the ability to fetch the user’s profile data, you should add the scope parameter.

var options = {
  auth: {
    params: {
        scope: 'openid profile'
    }
  }
};

There is also a connectionScopes configuration option for Lock, which allows you to specify scopes on any specific connection. This will be useful if you want to initially start with a set of scopes (defined on the dashboard), but later on request additional permissions or attributes from a specific connection. Read more about it on the Lock Configuration Options page.

state

The state parameter is an arbitrary state value that will be maintained across redirects. It is useful to mitigate XSRF attacks and for any contextual information, such as a return url that you might need after the authentication process is finished. If a custom state parameter is not provided, Lock will automatically generate one. For more information, see State Parameter.

nonce

The nonce parameter is used to help prevent replay attacks, and will be automatically generated by Lock if a custom value is not provided.

device

The device parameter sets the name of the device or browser requesting authentication.