Mobile Authentication API version 2

This section describes the API for mobile authentication. It's divided into the following subsections:

• API access
• Endpoints
  • Check if authentication is available for user
  • Check available authentication options for user
  • Authentication request
  • Sms code verification
  • Resending verification sms
  • Fetch Authentication result
  • Authentication response (callback)
  • Error codes

API access

Only authorized API client can access this API. Its credentials need to be provided via HTTP Basic Authentication header. The required credentials are the client id and client secret configured in the Admin console of the Token Server.

Note: Please look in the OAuth config section on how to configure an API client. In order to allow an API client to access mobile authentication endpoints add onegini_api_mobile_authentication to the Valid for Token Server API’s list in the API client configuration.

In case provided client credentials are invalid or client is not authorized to access the API, the errors according to OAuth specification Error Response will be returned.

Example request with invalid Basic Authentication header (invalid client id and client secret):

POST /oauth/api/v2/authenticate/user HTTP/1.1
Host: onegini.example.com
Authorization: Basic aW52YWxpZDppbnZhbGlk
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&user_id=myUserId

Example failure result

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

{
    "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method).",
    "error": "invalid_client"
}

Endpoints

Check if authentication is available for user

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

In all scenarios a 200 OK response is returned by the server. The response contains a json message indicating if authentication is enabled or not 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. The function does not check if the optionally configured fallback is available.

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 authentication options for user

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

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 for a user. When there are no authentication options for a user or the user is unknown the endpoint will return an empty list. The function does not check if the optionally configured fallback is available.

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/api/v2/authenticate/user

The request should contain a body which is application/x-www-form-urlencoded;charset=UTF-8 encoded. Containing these parameters:

Example request

POST /oauth/api/v2/authenticate/user HTTP/1.1
Host: onegini.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded


user_id=myUserId&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 an UUID. Based on this transaction id the portal can correlate the incoming authentication results. The returned object also contains an information about authentication method which was actually used (PUSH or SMS) plus the time to live for the transaction (in milliseconds). Information may be useful in situations where for some reason PUSH authentication failed, but in the initial request portal also provided user's phone number so 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/api/v2/authenticate/user/{user_id}/sms

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

Example request:

POST oauth/api/v2/authenticate/user/myUserId/sms HTTP/1.1
Host: onegini.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
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/api/v2/authenticate/user/{user_id}/sms/resend

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

Example request:

POST oauth/api/v2/authenticate/user/myUserId/sms/resend HTTP/1.1
Host: onegini.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
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:

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/api/v2/authenticate/transaction/{transaction_id}

Example request:

GET oauth/api/v2/authenticate/transaction/cf51a27a-df80-42ad-bdd7-936c476b2c87 HTTP/1.1
Host: onegini.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
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,
  "authentication_method": "push_with_pin",
  "used_authentication_attempts": 1
}

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",
}

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

Error codes