Airlock IAM Loginapp REST API

• authentication flows
• user self-registration
• password change or reset
• self-services (e.g. registering new tokens)

Further services will be continuously added in upcoming releases.

General information (for all IAM REST APIs)

Introduction to the Airlock IAM REST API

The main purpose of the REST API is the machine-to-machine communication where web UIs are not applicable. Usage scenarios include:

• user management by third-party back-end applications (admin)
• password- and token management (admin)
• authentication (login)
• user self-registration (login)

Scope

Implementation and Integration

JSON:API format

• a top-level JSON:API document contains at least one resource object, a collection of resource objects or a certain amount of error objects. Optionally, it contains also:
• links
• a meta data object
• embedded, referenced resource objects. This prevents the need for extra requests to these resources.
• every resource object has a symbolic type and an id. Optionally, it contains also:
• an attribute object
• a relationship object with references to other resources
• links (e.g. self-links or links to sub resources)

POST https://www.airlock.com/auth-admin/rest/users/{userId}/lock/
POST https://www.airlock.com/auth-login/rest/public/users/register/
POST https://www.airlock.com/auth-login/rest/public/users/{userId}/registration/verify/

URIs

https://someHost:8080/
contextPath
/users/user123/secret-questions/answers/missing

• Domain and port
  : domain name and optional port should be configurable in the client
• Context path
  : This prefix depends on the name of the IAM instance. If run behind Airlock WAF, it's determined by a mapping name. Allow this part to consist of multiple path segments such as auth-login/rest.
• Resource path
  : This part of the URI is independent of deployment and considered stable.

Date and time format

date-fullyear   = 4DIGIT
date-month      = 2DIGIT  ; 01-12
date-mday       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31 based on
                             ; month/year
time-hour       = 2DIGIT  ; 00-23
time-minute     = 2DIGIT  ; 00-59
time-second     = 2DIGIT  ; 00-58, 00-59, 00-60 based on leap second
                             ; rules
time-secfrac    = "." 1*DIGIT
time-numoffset  = ("+" / "-") time-hour ":" time-minute
time-offset     = "Z" / time-numoffset

partial-time    = time-hour ":" time-minute ":" time-second
                     [time-secfrac]
full-date       = date-fullyear "-" date-month "-" date-mday
full-time       = partial-time time-offset

date-time       = full-date "T" full-time

2011-12-03T10:15:30.000+01:00
2018-02-06T15:58:53.661Z

yyyy-MM-dd'T'HH:mm:ss.SSSXXX

The IAM REST API accepts timestamps in several formats, but they must always contain a time and timezone component. It is recommended to format timestamps as described above to avoid ambiguities.

2011-12-03

yyyy-MM-dd

API changes and versioning

GET /api/user/foo
Accept: application/vnd.api+json; iam-variants="extension-a,extension-b,extension-c"

200 OK
Content-Type: application/vnd.api+json; iam-variants=extension-b

Incubating features

Charset and Encoding

Locale

Clients may set the Accept-Language header as specified by RFC 2616. If set, IAM will determine the best matching language based on the configured language settings. If the header is a) not set, b) malformed or c) does not match any configured language, the configured default language is used. The language is relevant if messages like SMS or email are sent to a user upon a REST call.

CSRF protection

We briefly explain how this mechanism protects against CSRF attacks.

Cross-Site requests can either be 'simple' or 'non-simple', as explained in CORS. Simple requests are sent to the server (IAM) in any case and can thus be employed to execute CSRF attacks. In case of 'non-simple' requests, browsers first send a preflight request to the server. The actual request is only executed if the server explicitly allows it by white-listing the request's origin. Forcing cross-site requests to be 'non-simple' therefore protects against CSRF attacks, as only white-listed cross-site requests are executed.

IAM forces all requests to have the custom header X-Same-Domain which makes them 'non-simple'. This establishes the CSRF protection as explained above. Allowed origins to be accepted can be white-listed in IAM's CORS settings. By default, this white-list is empty and all cross-origin requests are denied.

For backward compatibility with older clients, this check can be disabled in the Loginapp- and Adminapp REST configuration. The operation with disabled CSRF protection is strongly discouraged.

* Endpoints that are designed in accordance with an external specification (such as a RFC) are excluded from requiring the X-Same-Domain header. Refer to the documentation of endpoint operations below to see where this applies and how CSRF protection is ensured instead.

Response format

Error Responses

Example

{
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-25T13:57:26.122+00:00"
  },
  "errors": [
    {
      "id": "6117:5385",
      "status": 400,
      "code": "INVALID_REQUEST_FORMAT"
    }
  ]
}

404 (NOT FOUND) response

• the requested URL contains a typo
• the requested URL contains an identifier but no entity with this identifier exists in the context of the current request.
  In cases where the entity that could not be found is a user, the error code USER_NOT_FOUND is set in the response.

415 (UNSUPPORTED MEDIA TYPE) response

Every endpoint declares the accepted Content-Type which is typically application/vnd.api+json and/or application/json.

503 (SERVICE UNAVAILABLE) response

Errors on updating relationships

Error responses in flows

In flows, the HTTP status code 400 - BAD REQUEST indicates that the previous request has been rejected and the client should try to resume the flow with the step indicated.

The HTTP status code 403 - FORBIDDEN means that the flow has been aborted by the engine and the client should not attempt to make any further calls for this flow, as they will not succeed. For instance, this may happen if the call is unexpected or if a user is locked. Such situations may require an intervention of the helpdesk for the user to continue with the process.

Error Codes

Error objects can contain an optional code that gives more detail about the error situation. Currently, the following generic error codes can occur:

• AUTHENTICATION_FAILED: the authentication failed for some unspecified reason.
• AUTH_METHOD_INACTIVE: the authentication failed since the current authentication method is inactive / disabled.
• CAPTCHA_CHECK_FAILED: the requested resource is protected by CAPTCHA but an invalid or no CAPTCHA was provided.
• CLIENT_CERTIFICATE_MISSING: a client certificate is required when calling the requested resource.
• CONCURRENT_ACCESS: concurrent calls within a user session have been detected (typically returned from an authentication flow).
• CSRF_HEADER_MISSING: the call is CSRF protected and requires the header X-Same-Domain. See CSRF Protection.
• FLOW_START_NOT_ALLOWED: the flow is not allowed because the user session already contains data, e.g. a user may be logged in. The user must log out first in order to start this flow.
• FLOW_SESSION_EXPIRED: the flow is no longer valid because some initial tags (which might have been used in preconditions or skip conditions during the execution of this flow) have expired.
• GOTO_FAILED: the requested goto is not possible. The target step is not allowed from the current step or it does not exist in the flow at all.
• INVALID_REQUEST_FORMAT: the request format is syntactically invalid (parse error).
• NO_VALID_TOKEN: no valid token could be found. E.g. two factor authentication with mTAN in progress, but no mTAN number registered.
• UNEXPECTED_CALL: the call to the requested resource is unexpected. Happens for instance in flows if the attempted call does not match the step that is expected next. In such cases, the current flow is generally aborted, but the user session remains intact. The user may subsequently restart the flow. Calls to endpoints that select and start flows (e.g. application access) are an exception to this, as they do not terminate an ongoing flow if called unexpectedly.
• USER_INVALID: the user is invalid.
• USER_LOCKED: the user is locked.
• USER_NOT_FOUND: the specified user could not be found.
• USER_NOT_UNIQUE: the specified user could not be uniquely identified.
• USER_ROLE_MISSING: the user does not have sufficient roles to perform an action (typically returned from an authentication flow).
• USER_TEMPORARILY_LOCKED: the requested operation cannot be performed because the user is temporarily locked. Note that this code is not returned by the operation which caused the temporary lock itself.
• VALIDATION_FAILED: the supplied attributes could not be validated successfully. See validation failures for detail codes.
• TECH_CLIENT_NOT_FOUND: the specified technical client could not be found.
• ALL_DEVICES_IN_COOLDOWN: the user does not have any Airlock 2FA device that is not in cooldown and is therefore not able to perform certain Airlock 2FA operations.

The listing below shows which generic errors can occur for the different application parts. Additional endpoint-specific error codes are documented in the individual endpoint documentation. Generic errors are not documented on individual endpoints. Callers must expect them as documented below.

{
    "meta": {
        "type": "jsonapi.metadata.document",
        "timestamp": "2017-12-12T09:29:01.259+01:00"
    },
    "errors": [
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/newPhoneNumber"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "MAX_LENGTH",
                "parameters": {
                    "actualLength": 26,
                    "maxLength": 12
                }
            }
        },
        {
            "code": "VALIDATION_FAILED",
            "source": {
                "pointer": "/label"
            },
            "meta": {
                "type": "jsonapi.metadata.validation.error",
                "detail": "REQUIRED"
            }
        }
    ]
}

Request Query Parameters

Paging

Query parameters

page[limit]
page[offset]

Limit/Size

Offset

Example (without URL encoding):

Filtering

Query parameter

filter

Syntax

• name - The name of the dimension to filter on
• operator - defines the type of filter match to use
• expression - states the values included in the results

Operators:

== (exact match)
=@ (contains substring)

Combining filters:

OR logic - defined using commas (,) inside a filter expression
AND logic - achieved by providing multiple filter parameters for a request

Example (without URL encoding):

Sorting

Query parameter

sort

Syntax

SortCriteria = [ Criterion { ',' Criterion} ]
Criterion = [ '-' ] identifier

• Identifier - The field to sort on, e.g. user context data
• Criterion - An expression stating the field to sort on and the direction (ascending or descending). Sorting descending is done by declaring a '-' before the identifier. The default is to sort ascending.
• SortCriteria - One or multiple criteria separated by a comma ','. Sort criteria are applied in the order they are declared. The next sort criterion in a list of criteria is only applied if two entries are equal by the former sort criterion.

Example (without URL encoding):

Configuration Contexts

For multi-step use cases (such as email- or mTAN self-services) or flows, this behavior is undesired. Any configuration change during a multi-step use case could lead to unexpected behavior. IAM therefore checks that configuration contexts remain constant during multi-step use cases. If a context change is detected, the associated use case is terminated. Context extractors must be designed / configured in a way that no configuration contexts changes occur during multi-step use cases.

Flow control and flow status

Fundamentals

Starting flows

Ending flows

Interpretation of responses from flow endpoints

Flow-driving endpoints

Example

{
  ...
  "data": {
    "type": "authentication.session",
    "id": "1234",
    "attributes": {
      "nextAuthStep": "MTAN_OTP_REQUIRED",
      "resendPossible": true,
      "phoneNumber": "+41791234567"
    }
  }
}

Response status codes

Data retrieval endpoints

Example

{
  ...
  "data": {
    "type": "authentication.mtan.token",
    "id": "1234",
    "attributes": {
      "number": "+41791234567",
      "label": "My phone",
      "defaultNumber": true
    }
  }
}

Authentication API

Authentication flow model

Successful response

{
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-26T07:41:05.697+00:00"
  },
  "data": {
    "type": "authentication.session",
    "id": "1234",
    "attributes": {
      "nextAuthStep": "MTAN_OTP_REQUIRED",
      "resendPossible": true,
      "phoneNumber": "+41791234567"
    },
    "links": {
      "self": "https://www.airlock.com/auth-login/rest/public/authentication/password/check"
    }
  }
}

Failing response

Client error response

{
  "meta": {
    "type": "jsonapi.metadata.document",
    "timestamp": "2016-04-26T07:47:23.578+00:00",
    "temporaryLockExpiry": "2016-04-26T07:47:27.578+00:00",
    "nextAuthStep": "PASSWORD_REQUIRED"
  },
  "errors": [
    {
      "id": "3565:9954",
      "status": 400,
      "code": "USERNAME_PASSWORD_WRONG"
    }
  ]
}

Next Auth Step Codes

For each nextAuthStep code, one or more follow-up calls are possible. These are as follows:

Additional attributes in authentication flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type authentication.session or to the meta data of error responses. The possible attributes depend on the content of the response:

Session Handling

Flow start

An authentication flow can be started explicitly by either calling the /public/authentication/applications/[applicationId]/access/ endpoint (if the application ID is known) or the /public/authentication/location/access endpoint (if the URL of the target application is known). If neither the application ID nor the target application URL is known, the default flow can be started by calling the /public/authentication/default-application/access/ endpoint. If no flow has been started in this manner, the first request to a flow endpoint automatically starts the default flow. This can be prevented (e.g. to avoid unintentially starting the wrong flow after a session timeout) by adding the request header X-Continue-Flow (with any value). If a request contains this header and no flow is currently active, an error response with status 403 and code NO_FLOW_TO_CONTINUE is returned.

Both "access" endpoints can be called with an SSO ticket attached to the request (as header or cookie, depending on the "SSO Ticket Extractor" configuration). This ticket will be available to all steps that are executed during this same request (typically the first step or all steps until the first interactive step). If the SSO or representation ticket step fails, the following error codes are possible:

• SSO_TOKEN_MISSING: an SSO ticket is expected but could not be extracted from the request.
• SSO_TOKEN_UNEXPECTED: an SSO ticket is not expected but was sent with this request.
• SSO_TOKEN_VERIFICATION_FAILED: an SSO ticket could be extracted but was rejected (see logs for detailed reason).

If a Kerberos authentication step is configured in a flow, the "access" endpoint requests a WWW-Authenticate: Negotiate response header. In a Kerberos-enabled environment the browser repeats the request with the Authorization: Negotiate <Base64 encoded ticket> request header. If the Kerberos authentication step fails, the following error code is possible:

• KERBEROS_TICKET_VERIFICATION_FAILED: the Kerberos ticket verification failed (see logs for detailed reason).

CAPTCHA

Selected flow steps can be protected with a CAPTCHA. The REST endpoints for these steps are marked in the documentation with the CAPTCHA tag. When a CAPTCHA is required to be solved, a CAPTCHA challenge is present in the attributes of the REST response immediately preceeding the protected step:

• If the first step in the flow is CAPTCHA-protected, this is typically the POST/protected/self-service/flows/{flowId}/select/ or POST/public/user-self-registration/flows/{flowId}/select/ endpoint.
• If the CAPTCHA challenge doesn't have to be solved in the first step, the challenge will be in the additional attributes of the request from the previous step.

{
      "meta": {...},
      "data": {
        ...
        "attributes": {
          "captcha": {
            "type": ...
            // CAPTCHA challenge
            }
          ...
        }
      }
    }

The CAPTCHA solution is expected to be present in the X-Captcha-Solution header of the next REST request to a flow endpoint. If no solution header is present or the provided solution is wrong or has already been used or has timed out, an error response with status code 400 (Bad Request) and error code CAPTCHA_CHECK_FAILED is returned (as described in Client error response). If a CAPTCHA check fails, the user has more attempts and no failed attempts counter is incremented.

Two types of CAPTCHA challenges are currently supported: reCAPTCHA v2 ("I'm not a robot" Checkbox) and hCaptcha. For both types the challenge is represented by the site key. Please refer to the reCAPTCHA or the hCaptcha documentation for information on how to use the site key to solve a challenge.

Non-Browser implementations for reCAPTCHA (like the SafetyNet implementation) are not supported. In these use-cases, a browser window/viewer can be used to display the CAPTCHA challenge.

Maintenance Message

• DELETE/protected/self-service/flow/
• DELETE/public/authentication/
• DELETE/public/authentication/flow/
• DELETE/public/self-service/flow/
• DELETE/public/user-self-registration/flow/

User Self-Registration API

Next Self-Registration Step Codes

For each nextStep code, one or more follow-up calls are possible. These are as follows:

Additional attributes in user self-registration flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type user-self-registration.session and to the meta data of error responses. The possible attributes often depend on the nextStep code:

Public Self-Service API

Next Public Self-Service Step Codes

For each nextStep code, one or more follow-up calls are possible. These are as follows:

Additional attributes in public self-service flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type public-self-service.session and to the meta data of error responses. The possible attributes often depend on the nextStep code:

Self-Service Flow API

Next Self-Service Step Codes

For each nextStep code, one or more follow-up calls are possible. These are as follows:

Additional attributes in self-service flow responses

Some flow responses contain additional attributes to include more information for the client. These attributes are added to responses of type self-service.session and to the meta data of error responses. The possible attributes often depend on the nextStep code:

Technical Client Registration API

Next Technical Client Registration Step Codes

For each nextStep code, one or more follow-up calls are possible. These are as follows:

OAuth 2.0 API

Loginapp REST call documentation