SMS-MT-OTP and SMTP-OTP grant

SMS-MT- or SMTP-OTP grant use cases are extensions to OAuth2. Both use unregistered authentication method, either for SMS or for SMTP.

Client wants to get an access- or id token, and to have that SSO needs to be called twice. First to initiate the authentication process, client needs to obtain the reference to the one time password sent to the user by SMS or email, and second time to validate the otp the user has entered/sent to client.

Note that message (sms or smtp) title and body can be set as request parameters, or if omitted, use default configuration (uas.properties, or localized uas.properties file).

Contents

Sequence diagram of Sms-mt-otp and smtp-otp grant


Token Request, initiate

POST /uas/oauth2/token

Required parameters

  • grant_type = http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp

Not allowed by default. Set the grant_types data into SSO Application metadata.
Example: {"grant_types":["http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp","http://globalsign.com/iam/sso/oauth2/grant-type/smtp-otp"]}

  • scope = openid
  • client_id & client_secret

OAuth Client Identifier and Secret of the native application

  • username msisdn or email of the end-user


Optional parameters

  • x_globalsign_iam_otp_title

Optional parameter containing message title for emails

  • x_globalsign_iam_otp_body

Optional parameter containing message body. Parameter {0} is expanded to the one time password generated by SSO

  • ui_locales

Optional parameter. When no title or body is sent, and system configuration parameters are used, this is mandatory

Sample initate contact confirm token request
POST https://sso.example.com/uas/oauth2/tokenAuthorization: Basic MTc2MjQxNDM3NDoqKio= Content-Type: application/x-www-form-urlencoded
grant_type= http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp &scope=openid&username=040555555& x_globalsign_iam_otp_title=title& x_globalsign_iam_otp_body=your otp is{0}

Token Response, Initiate

Sample initiate contact confirm token response
HTTP/1.1 200 OKContent-Type: application/json 
{"x_globalsign_iam_sms_mt_otp_challenge":{"reference":"dflkfkkDknkngN.eyiodkkdodlkgflkfg_YUAtgg=="}}

Access Token Request, Validation

POST /uas/oauth2/token

Required parameters

  • grant_type = http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp|smtp-otp
  • scope = openid
  • client_id & client_secret

OAuth Client Identifier and Secret of the native application

  • username

Msisdn or email of the end-user

  • x_globalsign_iam_reference_id

Reference sent to client earlier. Note that this is always the newest reference – if you need to resend the token request (in caes of wrong or timeouted otp, you should use the reference from the latest token request response.

  • x_globalsign_iam_otp_code

End user's otp

Sample initiate contact confirm token response
POST https://sso.example.com/uas/oauth2/tokenAuthorization: Basic MTc2MjQxNDM3NDoqKio= Content-Type: application/x-www-form-urlencoded
Grant_type=http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp& scope=openid&username=040555555& x_globalsign_iam_reference_id=dflkfkkDknkngN.eyiodkkdodlkgflkfg_YUAtgg==& x_globalsign_iam_otp_code=1234 5678

Access Token Response, Validate

Successful response

See chapter Access Token Response on page Authorization code grant and web single sign-on.

Failure response

Sample initiate contact confirm token response, failure
{"x_globalsign_iam_challenge": {"reference": 
".eyJzdWIiOiIxMjMiLCJpYXQiOjE0Nzk5OTYzMzA5MDgsImN0bXMiOjg4Njg4NzYzNzY2MjAzNCwibWFjIjoibGlxSWRtdHdlakVuSmxoRm1yd0Y4Y0
N4N0pNUzM4Vm05WW51LXhRUExscGc4ckduMFJOSktPSE55Uk9sU3NvS2RWdkpoUT09In0.Usdl9RhGnlH6KJATWFfakYEFTyo1bl7jDv-Z5SydWT4"},
"error": "invalid_grant", "error_description": "OTP Expired"}

Sms-mt- and smtp-otp grant add error_description field in case otp was incorrect or in case of otp timeout. OTP timeout, in minutes, is set in sms- or smtp-unregistered authentication method).