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"

Browser not supported