Mobile Authentication API version 1 (deprecated)

This section describes the API version 1 for mobile authentication which is deprecated. It's divided into the following subsections:

API access

Since this API is deprecated, it can be used if and only it is enabled on system level and by a following Docker Compose environment variable:

Variable Default value
TOKEN_​SERVER_​ENGINE_​MOBILE_​AUTHENTICATION_​DEPRECATED_​API_​ENABLED false

By default this property is set to false. In order to enable access to deprecated mobile authentication API set this property to true.

Endpoints

Check whether mobile authentication is available for user

Endpoint: GET /oauth/authenticate/user/{user_id}/enabled/{type}

Parameter Description
user_id Identifier of the user
type The Name of the Mobile authentication type as defined via the admin panel. Example: no_pin, pin, ...

In all scenarios a 200 OK response is returned by the server. The response contains a JSON message indicating whether authentication is enabled for a user. When the specified type is available the value will be true. When this type is not enabled or the user is unknown the value will be false.

Note: A mobile authentication type is available only if its original method or its fallback method is available to authenticate with.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "enabled": true
}

Check available mobile authentication options for user

Endpoint: GET /oauth/authenticate/user/{user_id}/enabled

Parameter Description
user_id Identifier of the user

In all scenarios a 200 OK response is returned by the server. The response contains a json message with a list of available authentication options (mobile authentication types names as defined via admin panel) for a user. When there are no authentication options for a user or the user is unknown the endpoint will return an empty list.

Note: A mobile authentication type is available only if its original method or its fallback method is available to authenticate with.

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "enabled":[
    "login_with_push",
    "login_with_pin",
    "authorize_with_pin", 
    "sms"
  ]
}

Authentication request

Authentication of a user can be initialized by an async API call to the mobile authentication server. The portal will be informed about the authentication result via a callback.

Endpoint: POST /oauth/authenticate/user/{user_id}

Note: If the user_id parameter is an email address, the / should be added at the end of the url.

Parameter Description
user_id Identifier of the user

The request must contain a body which is application/x-www-form-urlencoded;charset=UTF-8 encoded. The parameters required depend on the type of authentication requested. Note that if a fallback is used for the mobile authentication type, and this fallback is of a different type, then its required parameters should also be present.

Parameter Required Description
callback_uri no, only when push authentication is used Uri on which the portal wants to receive the result of the authentication. When a callback uri whitelist is used, the callback uri should be on the whitelist.
message yes, unless a default message in configured The message to display in the authentication request. NOTE: Max allowed length is 155 by default, if provided message will be longer endpoint will return 400 with error_code:1005
secure_message no Sensitive message which will be encrypted and delivered to the device with HTTPS
type yes The name of the mobile authentication type as defined via admin panel. Example: no_pin, pin, etc. Each push based mobile authentication type may contain a fallback strategy which is used when the original authentication method is not available for a user.
phone_number no, only when sms is used Phone number to be used in SMS authentication process.
language_code no When no message is specified, the language code is used to determine which message to use from the configured default messages. When no default message is found for the language code the English message is used. Examples of language codes: nl, fr, en, de (lowercase).

Example request

POST /oauth/authenticate/user/myUserId HTTP/1.1
Host: onegini.example.com
Content-Type: application/x-www-form-urlencoded

callback_uri=https%3A%2F%2Fwww.myportal.com%2Fcallback&message=Please%20authenticate%20for%20mine.acme.com&type=push_with_pin

When the mobile authentication server was able to successfully send out an authentication request to the user a 200 OK response is received containing a transaction id which is a UUID. Based on this transaction id the portal can correlate the incoming authentication results. The returned object also contains information about the authentication method that was requested (push, sms or otp) plus the time to live for the transaction (in milliseconds). This information may be useful in situations where e.g. push based authentication could not be initiated. But, SMS was specified as a fallback and in the initial request the portal also provided the user's phone number. Hence, the Token Server was able to fallback on the SMS authentication method.

Example success result

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "transaction_id": "5927555c-d40c-408d-8149-b3db671e14cc",
  "auth_method": "push",
  "time_to_live": 60000
}

When the mobile authentication server was unable to send out an authentication request to the user an error response is received containing an error code and a description.

Example failure result

HTTP/1.1 404 NOT FOUND
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "error_code": "1001",
  "description": "No authentication possibilities for user or user not found"
}

Sms code verification

Verification of SMS code can be done through:

Endpoint: POST /oauth/authenticate/user/{user_id}/sms

Parameter Description
user_id Identifier of the user

The expected body request is application/x-www-form-urlencoded;charset=UTF-8 encoded and contains parameters:

Parameter Description
transaction_id transaction identifier returned in authentication init step
sms_code verification code provided by user

Example request:

POST oauth/authenticate/user/myUserId/sms HTTP/1.1
Host: onegini.example.com
Content-Type: application/x-www-form-urlencoded

sms_code=123456&transaction_id=5927555c-d40c-408d-8149-b3db671e14cc

Example response after successful SMS code verification:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "transaction_id": "5927555c-d40c-408d-8149-b3db671e14cc"
}

Example response after unsuccessful SMS code verification:

HTTP/1.1 404 NOT FOUND
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "error_code": "3003",
  "description": "Failed to authenticate, verification code invalid"
}

Resending verification sms

The endpoint can be used to send again a verification code by SMS in case the old one was not delivered.

Endpoint POST /oauth/authenticate/user/{user_id}/sms/resend

Parameter Description
user_id Identifier of the user

The expected body request is application/x-www-form-urlencoded;charset=UTF-8 encoded and contains parameters:

path variable Description
transaction_id The identifier of the authentication transaction.

Example request:

POST oauth/authenticate/user/myUserId/sms/resend HTTP/1.1
Host: onegini.example.com
Content-Type: application/x-www-form-urlencoded

transaction_id=5927555c-d40c-408d-8149-b3db671e14cc

Http status "204 No Content" is returned when SMS was resent, otherwise one of the following errors:

Error code Http status code Description
3002 503 Failed to initiate authentication, failed to send sms
3004 404 Failed to authenticate, invalid transaction id
3005 404 Failed to authenticate, invalid user id
3006 403 Resend limit reached.

Fetch Authentication result

When the authentication response has been received this means that the authentication was completed and the portal can retrieve the authentication result.

Endpoint GET /oauth/authenticate/transaction/{transaction_id}

Parameter Description
transaction_id transaction identifier returned in authentication init step

Example request:

GET oauth/authenticate/transaction/cf51a27a-df80-42ad-bdd7-936c476b2c87 HTTP/1.1
Host: onegini.example.com
Content-Type: application/x-www-form-urlencoded

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache

{
  "callback_uri":"https://www.myportal.com/callback",
  "transaction_id":"cf51a27a-df80-42ad-bdd7-936c476b2c87",
  "timestamp":1402390451564,
  "user_id":"myDummyUser",
  "is_authenticated":true
}
Parameter Description
callback_uri The callback uri used in the authentication request and where this callback is sent to.
transaction_id The identifier of the authentication transaction.
timestamp Timestamp of the moment the authentication request was sent.
user_id The identifier for the user that has answered the authentication request.
is_authenticated The authentication result, when true the user is authenticated if false the user is not authenticated.

Authentication response (callback)

As an authentication response the portal will receive a callback from the mobile authentication server. As an endpoint the callback uri from the authentication request is used.

Endpoint: POST < callback_uri >

Example request

POST /myportal/authenticate/callback HTTP/1.1
Host: onegini.example.com
Content-Type: application/json;charset=UTF-8

{
  "callback_uri":"https://www.myportal.com/callback",
  "transaction_id":"cf51a27a-df80-42ad-bdd7-936c476b2c87",
}
Parameter Description
callback_uri The callback uri used in the authentication request and where this callback is sent to.
transaction_id The identifier of the authentication transaction.

The portal should send a "204 No Content" response on the callback.

Error codes

Error code Http status code Description
1000 404 Mobile authentication disabled
1001 404 No authentication possibilities for user or user not found
1002 503 Failed to initiate authentication at authentication provider
1003 400 One of the requests parameters is invalid or missing
1005 400 Failed to initiate authentication, message content too long
1006 404 Failed to fetch authentication message
3000 404 SMS authentication disabled
3001 400 Invalid input params, phone number is missing
3002 503 Failed to initiate authentication, failed to send SMS
3003 404 Failed to authenticate, verification code invalid
3004 404 Failed to authenticate, invalid transaction id
3005 404 Failed to initiate authentication, Mobile authentication type not found