Mobile authentication API version 3

This section describes the API for mobile authentication, version 3. The latest version of the Mobile Authentication API is version 4.

New in this API version

• A user can enroll for mobile push authentication for multiple applications at the same time.

API access

Note: To access the API, mobile authentication has to be enabled on system level.

Only authorized API clients can access this API. Its credentials need to be provided via HTTP Basic Authentication header or via url encoded form. The required credentials are the client id and client secret configured in the Admin console of Onegini Access.

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 Mobile authentication to the Valid for APIs list in the API client configuration.

In case the provided client credentials are invalid or the 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/v3/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&app_id=myApp

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": "invalid_client",
    "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)."
}

Availability

Onegini Access provides two endpoints to check the availability of mobile authentication types for specific users.

Check if authentication is available for user and application

Endpoint: GET /oauth/api/v3/authenticate/user/{user_id}/application/{app_id}/enabled

In all scenarios a 200 OK response is returned by the server if mobile authentication is enabled on system level. The response contains a JSON message with a list of available authentication types.

When there are no authentication options for a user/application pair or the user/application is unknown, the endpoint will return an empty list.

Note: A mobile authentication type is available when either 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"
  ]
}

Check available authentication options for user

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

In all scenarios a 200 OK response is returned by the server if mobile authentication is enabled on system level. The response contains a JSON message with a list of available authentication options for a user. Each option contains the mobile authentication types as defined via the admin console. Only the applications for which the user has enrolled push authentication can handle this method. These applications are listed in apps_enrolled_for_push. Mobile authentication that is based on SMS or OTP is not restricted to specific applications. Push based authentication types can have sms fallback configured. This is also reflected in the JSON with the sms_fallback_allowed attribute.

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": [
    {
      "type": "authorize_with_push",
      "method": "PUSH",
      "sms_fallback_allowed": true,
      "apps_enrolled_for_push": [
        {
          "id": "myApp",
          "name": "My application"
        },
        {
          "id": "myOtherApp",
          "name": "My other application"
        }
      ]
    },
    {
      "type": "authorize_with_pin",
      "method": "PUSH_WITH_PIN",
      "sms_fallback_allowed": false,
      "apps_enrolled_for_push": [
        {
          "id": "myApp",
          "name": "My application"
        },
        {
          "id": "myOtherApp",
          "name": "My other application"
        }
      ]
    },
    {
      "type": "authorize_with_fingerprint",
      "method": "PUSH_WITH_FINGERPRINT",
      "sms_fallback_allowed": false,
      "apps_enrolled_for_push": [
        {
          "id": "myApp",
          "name": "My application"
        },
        {
          "id": "myOtherApp",
          "name": "My other application"
        }
      ]
    },
    {
      "type": "authorize_with_otp",
      "method": "OTP"
    },
    {
      "type": "authorize_with_sms",
      "method": "SMS"
    }
  ]
}

Mobile authentication initialization

Mobile authentication can be initialized by an asynchronous API call to Onegini Access. For most mobile authentication types (push, OTP) the portal will be informed of the authentication result via a callback.

Request

Endpoint: POST /oauth/api/v3/authenticate/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.

Example push request:

POST /oauth/api/v3/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&app_id=myApp

Example OTP request:

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

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

Response

When the mobile authentication server was able to successfully initialize the mobile authentication request, a 200 OK response is received containing several parameters, depending on the type of authentication initialized.

Example push 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,
  "device": {
    "name": "Lisa's Android device",
    "platform": "android"
  }
}

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 Onegini Access was able to fallback on the SMS authentication method.

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": "not_found",
  "error_description": "No authentication possibilities for user/application or user not found."
}

Mobile authentication result

Once the user has completed authentication, the portal must be informed of the results. This is done via a callback from Onegini Access to the portal, and a subsequent request to fetch the mobile authentication results.

Note: This section does not apply to SMS mobile authentication types. Please refer to the SMS endpoints section for completing an SMS mobile authentication request.

Callback

Once authentication has occurred (or failed), Onegini Access calls the endpoint provided by the portal during the mobile authentication initialization step ( specifically, the callback_uri field).

Endpoint: POST <callback_uri>

Example request:

POST /callback HTTP/1.1
Host: www.myportal.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.

Fetch authentication result

When the callback has been received by the portal, this means that the mobile authentication request has been completed and the results can be retrieved.

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

Example request:

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

The response will contain a JSON object with the following parameters:

The following table shows possible not authenticated reasons:

Example authenticated 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,
  "signature": "CpjXBItoNacFfr1OmqQMW4phDinOulptu9OizQVKnqm49JPoUlg=",
  "user_public_key": "-----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAt2SQBWzrMN8BEI2Q7Bv1
    cHif/Zq64XvcHRQ+Rh9oQRftBeWTKKAHEZK4MFAB+Z/xypP+pzJz4qixxaOlOph9
    g210m6fS6l+DoX1Q3gb+rA5TEIDDtLGTO8nEJoclbf8c9B6E1nnPa5T8Mwpu1S3N
    otrix4dY5bkyI6/MX5amFvp3BN8eZWrzJvtmO8ERb7YROz96t/VQp7wczqnlx42U
    +D2WjNqWEmy7iuB33iqKp3cevlVY33ZS8oTMSc9nLhfh95so+Ioi2943WjDPNTgk
    Ftf36bIShB4IksF2F1nlszavZ2WTaIeiqCsoPg9Bx0d6y2HG4mA4nJhWlk2A9Jyu
    EwIDAQAB
    -----END PUBLIC KEY-----",
  "signature_verified":true
}

Example not authenticated 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":false,
  "used_authentication_attempts": 1,
  "not_authenticated_reason":{
    "reason":"invalid_answer",
    "description":"Invalid push answer"
  }
}

In the event of an error, one of these error codes will be returned.

SMS endpoints

While mobile authentication with SMS is initialized using the same endpoint as other types, the completion of the request differs in that the user must submit their SMS code to the portal. Onegini Access therefore provides two endpoints for this purpose.

Verify SMS code

The portal can verify a user's SMS code using the following endpoint.

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

The request body must be application/x-www-form-urlencoded;charset=UTF-8 encoded and contain the following parameters:

Example request:

POST oauth/api/v3/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 success response:

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 error response:

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

Resend verification SMS

The following endpoint can be used to resend an SMS verification code in case the previous one was not delivered.

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

The request body must be application/x-www-form-urlencoded;charset=UTF-8 encoded and contain the following parameters:

Example request:

POST oauth/api/v3/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

A 204 No Content is returned when the SMS was successfully resent.

Error codes

Error codes