SMS-MT-OTP and SMTP-OTP grant - SSO

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 or 
    grant_type = http://globalsign.com/iam/sso/oauth2/grant-type/smtp-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"]}

Note: The grant types "http://globalsign.com/iam/sso/oauth2/grant-type/sms-mt-otp" and "http://globalsign.com/iam/sso/oauth2/grant-type/smtp-otp" are OAuth2 extensions implemented by Ubisecure. Use these grant type identifiers as is, don't replace them with your Ubisecure deployment address.

  • 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/token
Authorization: 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%20otp%20is%20{0}

Token Response, Initiate

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

Access Token Request, Validate

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

  • One of the following is required
    • 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 top. Spaces within the otp value are ignored.

Sample initiate contact confirm token response
POST https://sso.example.com/uas/oauth2/token
Authorization: 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

Sample initiate contact confirm token response, success
{
    "access_token": "eyJjdHkiOiJKV1QiLCJhbGciOiJkaXIiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiemlwIjoiREVGIiwiaXNzIjoiMGQ4OTUxODEtYmU3My00OWE0LTg0NWYtMTcxNDk3MDZkOWIxIn0..1EEmB8xOUEEi_oyQEqhlDA.gktMrmGoT084sx7wyMys7W2DYqA3yhn7oU74ehWliudsj3HssfR71bWyg2PnZHnEhUKx9ZdP2Ne9k73_29r5OSYpeiUQShRTw9T7aIx3G7lF6v6H_4a1QLL4kE2zzf_Vyy4lFpVTia17WMaaQ1THbmPDi0a5KCv6ZDLxJ-5vZkemsBKC7F4P40c1szHkMBqXwHel_pab1ApuHBRKZyiCGwsW1zpRzrnMZR0MIm4IMPaj_kD-25x7ndci-v8i4-YdU2C76h4hCxchTWDrXY4ZBdIVEN3nGuODJdXz2GNlTAzK6zjTltWMewAPfJednvuKkWWoq8piixxOYP35_JmpC3zpyqtyjSyBFOxvauSU7Ez4b6ggJKIMLT3igMXsQ5sl.RK9GctwZI8d43eL_uXqEqA",
    "scope": "openid",
    "id_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6IjVnMk9lMlhUalNjbFdfUTM5QkoybFltVV9sRSJ9.eyJzdWIiOiJycGVAaWtpLmZpIiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi51YmlkZW1vLmNvbTo4NDQzL3VhcyIsImF1ZCI6WyIwZDg5NTE4MS1iZTczLTQ5YTQtODQ1Zi0xNzE0OTcwNmQ5YjEiXSwiZXhwIjoxNjgyMzI2OTM1LCJpYXQiOjE2ODIzMjMzMzUsImF1dGhfdGltZSI6MTY4MjMyMzMzNSwiYW1yIjpbImh0dHBzOi8vbG9naW4udWJpZGVtby5jb206ODQ0My91YXMvc2FtbDIvbmFtZXMvYWMvc210cC1vdHAudW5yZWdpc3RlcmVkLjEiXSwiYXpwIjoiMGQ4OTUxODEtYmU3My00OWE0LTg0NWYtMTcxNDk3MDZkOWIxIiwic2Vzc2lvbl9pbmRleCI6Il8wZWM3ZTM4YjYzOGI1ZDQ4YjExMWMwYjU2YjFhOWFjODNlZjUyNDA3Iiwic210cC1vdHAudW5yZWdpc3RlcmVkLjEuZ3JhbnRfdHlwZSI6WyJodHRwOi8vZ2xvYmFsc2lnbi5jb20vaWFtL3Nzby9vYXV0aDIvZ3JhbnQtdHlwZS9zbXRwLW90cCJdfQ.OtUVsMtY1YFQ038nhLYxAoVBSMZrFWVQ9t3DSNWAPyJnqSWYd5j9htUa-BYRK26zwwU2htru12l1YtFRv9gu7JdDayQn7iqYGMhS4vfops8vgVh4OZACU2xuaSK1YY4gDJ_LOwzGqW0Ace-jgvAObcjvZKrHLRPxMDiorT87uKds_RwxE2UKNqnrEcGThD-B0sl9WpGwy2uwQaJQ_-qjEXIgVuvwG9mD--Qe1pRL7rKTOpTuHZRNjL7iosjYXQx63hpbSEk94EU5hiSCVTVNGgN5JOGtpzsllUVmxec2D-ZpUkKZ4Jstbp4rM4jthJAXsq2811f6RxgfCJItkoV4Pg",
    "token_type": "Bearer",
    "expires_in": 3600
}

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

Failure response

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

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). Possible error_description field values are:

  • "Expired OTP"
  • "Incorrect OTP"