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 |