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
.
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 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 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/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 should contain a body which is application/x-www-form-urlencoded;charset=UTF-8 encoded. Containing these parameters:
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, ... Each Mobile authentication type may contain a fallback strategy which is used when an error occurs. |
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 or when a fallback is performed and the format of the original message is not sufficient, for example fallback to sms with a message without the code pattern, 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 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/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 |