Sample OAuth Integration ¶

It is often useful to see what OAuth configuration is available. The following url is helpful. https://<AAserver>/osp/a/<TENANT>/auth/oauth2/.well-known/openid-configuration.

You can specify TOP for the <TENANT> parameter, if the Multitenancy mode is disabled, or you are not in Advanced Authentication as a Service (SaaS).

Client initiated OAuth (3 legged OAuth) ¶

See the OAuth 2.0 Integration section of the Administrator Guide

Server to Server Authentication (2 legged OAuth) ¶

• An OAuth event with either Resource owner password credentials or client credentials must be enabled.

• If Resource owner credentials is selected then a chain with a password method must be associated with the event.

• If a user has been associated with the ‘Service Accounts’ role then that user will have an OAuth application automatically created for authentication using the client credential grant.

• Use of an identity with a username and password is encouraged, rather than a API key or token with no user. Having an identity allows better logging and auditing, a least privilege user, and a location for credential updating.

Sample python pseudocode using the authlib framework to make OAuth calls:

# Retrieve metadata type information about the OAuth implementation
response = get(HOST, f'/osp/a/{args.tenant.upper()}/auth/oauth2/.well-known/openid-configuration',
               None, debug=args.verbose)
metadata = response.json()

# Get jwks information for validations
response = get(metadata['jwks_uri'], '', None, debug=args.verbose)

# Retrieve tokens
client = OAuth2Session(args.cid, args.secret, scope=args.scope)
token = client.fetch_token(metadata['token_endpoint'], username=args.user, password=password, verify=not args.insecure)

# validate token using the introspection_endpoint
introspection = client.introspect_token(metadata['introspection_endpoint'], token=token["access_token"])

# Gather user information
headers = {'Authorization': f'Bearer {token["access_token"]}'}
response = get(metadata['userinfo_endpoint'], '', None, headers=headers, debug=args.verbose)

# discard the token
client.revoke_token(metadata['revocation_endpoint'], token=token["refresh_token"])

Sample SCIM user which is added to the service account role and therefor allows for OAuth client credential authentication.

{
  "active": true,
  "emails": [
    {
      "primary": true,
      "type": "work",
      "value": "name4@frog.com"
    }
  ],
  "externalId": "999999999",
  "meta": {
    "resourceType": "User"
  },
  "name": {
    "familyName": "User",
    "formatted": "Test User",
    "givenName": "Test"
  },
  "password": "a90ak43b;4&*)0dakc9",
  "roles": [
    {
      "display": "SERVICE ACCOUNTS"
    }
  ],
  "schemas": [
    "urn:ietf:params:scim:schemas:core:2.0:User"
  ],
  "urn:scim:schemas:extension:aa:1.0": {
    "oauth2_aud_base": "https://frog.com/\\nhttps://wild.frog.com\\nhttps://www.frog.com/",
    "oauth2_aud_exact": "https://froglogin.com/auth",
    "oauth2_redir_uris": "https://frog.com/finished-auth",
    "openid_scopes": [
      {
        "mandatory": false,
        "name": "aa:AdminUI",
        "openid": false,
        "require_owner_permission": false,
        "title": "Admin UI Allowed"
      }
    ]
  },
  "userName": "username4"
}

Results from using the sample code with the sample user above.

# python3 ./2leggedoauth.py --host test.frog.com --id 654321 --secret "12345678aA-" --insecure --verbose --scope "openid email user_roles tenantname tenantid client" --tenant TEST
 
Response: token={'access_token': 'eyJ0eXAiOiJhdCtqd3QiLCJhbGciOiJSUzI1NiIsImtpZCI6IkVkX2RqVWRwYjg4VGJBdFJoUW9uWjJSWG9zVSJ9.eyJpc3MiOiJodHRwczovL3Rlc3QuZnJvZy5jb20vb3NwL2EvVEVTVC9hdXRoL29hdXRoMiIsImV4cCI6MTY5NjI3MTc1MSwibmJmIjoxNjk2MjcxNjMxLCJpYXQiOjE2OTYyNzE2MzEsImp0aSI6Ikc5TldpTjlnUUhTUzkwcGF4VUFsUkEiLCJjbGllbnRfaWQiOiI2NTQzMjEiLCJzdWIiOiJvYXV0aDItNjU0MzIxIiwidHhuIjoiRG5YRGI4LTZRN3kzcHhhUmpvUFROUSIsInNjb3BlIjpbIm9wZW5pZCIsInRlbmFudGlkIiwidGVuYW50bmFtZSIsInVzZXJfcm9sZXMiLCJlbWFpbCJdLCJhdWQiOlsiNjU0MzIxIiwiTm9uZSJdLCJhdXRoX3RpbWUiOjAsIl9wdnQiOiJBQ01BRVFMbEFEY0hCalkxTkRNeU1YWUFQQUN2QUEifQ.SXWGwEoAdnXpu6R3mA17_4Lj0_10QVWyAhl2LH7VhYa3yvaIo5fttMlyojTTP0UGbWnJh7EeTK6HqFgZrAeeeOz0jdz7c1IdGebS6RRX40LOAV6n7svG84L1EKZO5HATOLwL9kIyRTa7iW7_0VdlI2vzVu80lzCnhVCkPvT7OTbCLQe0GHhqhn7FGxARpLHIKBoqTpP5X9DpKEsRgdGVFvZscTAsF5MR86Lg6dttay1_MxkOR351XHf3CJDKjJ5pa8BPx6PvvMiYsxzHokvq2QAS1GhN6yF95qlg6-nFheBndn6lbo8AN6_yjjt7RP2w1HWawLTnG2g-d07-RZ43QQ', 'token_type': 'Bearer', 'expires_in': 120, 'scope': 'openid tenantid tenantname user_roles email', 'expires_at': 1696271751}
Introspection:
( { 'active': True,
    'aud': ['654321', 'None'],
    'client_id': '654321',
    'exp': 1696271751,
    'iat': 1696271631,
    'iss': 'https://test.frog.com/osp/a/TEST/auth/oauth2',
    'nbf': 1696271631,
    'scope': 'openid tenantid tenantname user_roles email',
    'sub': 'oauth2-654321',
    'token_type': 'Bearer',
    'username': '654321'},)
('GET', 'https://test.frog.com/osp/a/TEST/auth/oauth2/userinfo', '', None)
('RESPONSE->', 200, {'auth_time': 1696271631, 'sub': 'oauth2-654321', 'tenantid': 'd32285665d5311ee8f7a0242ac110006', 'tenantname': 'TEST'})
User Info:
({'auth_time': 1696271631, 'sub': 'oauth2-654321', 'tenantid': 'd32285665d5311ee8f7a0242ac110006', 'tenantname': 'TEST'},)

Using the SCIM user above the OAuth clientId will be the “externalId” ie the value “999999999”. The secret will be the password of the user. Resetting the password resets the secret for the OAuth authentication. The access token returned from the OAuth call may be used as a bearer token Creating a user with a blank password "" results in a generated password being assigned to the user and returned to the caller.

Openid scopes maybe added to a service account. Adding aa:{Event Name} as the name of a scope allows the access token to be used in API calls to AA as though the session was authenticated to that event. For example if a user is associated with the roles for SERVICE ACCOUNTS and FULL ADMINS and the openid scope aa:AdminUI" then that token may be used for full API access to the AA system.

{
  "urn:scim:schemas:extension:aa:1.0": {
    "openid_scopes": [
      {
        "openid": false,
        "mandatory": false,
        "require_owner_permission": false,
        "name": "aa:AdminUI",
        "title": "Admin UI Allowed",
        "attributes": [
          {
            "localName": "tenantname",
            "clientName": "tenantname",
            "in_jwt": true
          },
          {
            "localName": "mobile",
            "clientName": "user_mobile_phone",
            "in_jwt": true
          },
          {
            "localName": "userFirstName",
            "clientName": "user_first_name",
            "in_jwt": true
          },
          {
            "localName": "userLastName",
            "clientName": "user_last_name",
            "in_jwt": true
          },
          {
            "localName": "mail",
            "clientName": "user_email",
            "in_jwt": true
          },
          {
            "localName": "roles",
            "clientName": "user_roles",
            "in_jwt": true
          },
          {
            "localName": "scim_user_id",
            "clientName": "user_scim_id",
            "in_jwt": true
          },
          {
            "localName": "external_user_id",
            "clientName": "user_external_id",
            "in_jwt": true
          }
        ]
      },
      {
        "openid": false,
        "mandatory": false,
        "require_owner_permission": false,
        "name": "aa:Helpdesk",
        "title": "Helpdesk Allowed"
      }
    ]
  }
}

Implementation of RFC 8707 to get a resource URI into the “aud” claim of an access token. This is incompatible with token sharing, either tokens are shared which imposes a list of audiences or the audiences are specified expliclty. Use oauth2_aud_exact for audiences that will do an exact match. Using oauth2_aud_base means that only the base portion of the audience must match for the audience to be considered valid. Multiple entries in either element should be seperated by \n.

{
  "urn:scim:schemas:extension:aa:1.0": {
    "oauth2_aud_base": "https://frog.com/\nhttps://wild.frog.com\nhttps://www.frog.com/",
    "oauth2_aud_exact": "https://froglogin.com/auth"
  }
}

Service Account Best Practices ¶

• Practice the principle of least privilege, avoid using a single service account with multiple roles and scopes.

• Practice good secrets management

  • Store secrets securely.
  • Use long complex values as the secret (password if created via SCIM).
  • Frequently rotate the secret.
  • Do not reuse the same secret on multiple accounts or across tenants.

• Monitor activity logs for incorrect service account usage.

• Service Accounts which are not being used should be deleted not disabled.

• Prefer audiences over scopes.

Sample Authentication Flow ¶

This is the process to logon a user and get a login_session_id which is required for many other API calls. To log on a device or user to the AA Server:

• Requires an endpoint id and secret. A single Endpoint may be used to authenticate many users. The endpoint id and secret are returned as a result of creating an Endpoint through one of the following mechanisms

  • Created once via the Admin UI and the endpoint id and secret are securely cached.
  • Created programmatically via the REST API. Create endpoint

• Create an endpoint session. Create endpoint session

• Read all chains available for user and event combination. Read user chains

• Select a chain to attempt if multiple chains are returned.

• Start logon process Start logon process

• For each method in the chain perform the following actions:

  • Gather details about data and steps for specific methods. Methods
  • Call do_logon for specific method, the following may be returned:
    • OK: The authentication was successful and the login process has been completed. The returned * login_session_id* should be securely cached.
    • MORE_DATA: The specific method attempted requires additional data, see specific method descriptions for required data.
    • FAILED: The login attempt was not successful. Start a new logon process to try again.
    • NEXT: This method was successful.
    • STOP: The login attempt was not successful. Start a new logon process to try again.
  • After receiving the NEXT return from do_logon, continue chain processing for the following method in the chain by calling next. NEXT method

• After successfully calling do_logon and NEXT method for every method the caller should recieve **OK ** and a login_session_id

• Securely cache the returned login_session_id.

Sample Enrollment Flow ¶

Enrollment is the process of setting up the expected response for a particular authentication method. Internally the credential information gathered during enrollment is stored securely in authentication templates. User Templates For some methods the setup is automatic and no user action is required, other methods require that a user manually enroll. Enroll. Enrollment may accomplished by users using the enrollment ui after they authenticate or may be done programmatically via the following steps:

• Logon with Helpdesk or Authenticators Management events. Sample Authentication

• Start enroll process Start enroll process

• Gather details about data and steps for specific methods. Methods

• Call do_enroll the following status may be returned:

  • OK: Proceed to ‘Associate the enrollment with a user.’
  • FAILED: Process will need start over. Cleanup enroll process
  • NEXT: Provide requested data.

• Continue calling do_enroll until the status ‘OK’ or ‘FAILED’ is returned.

• Associate the enrollment with a user. Create template, fill it from enroll session and link to user The admin may assign the enrollement/template with any user. A user may assign the proccess user to themselves. It is also possible for one user to start the enrollment and hand the enroll_process_id to a second user who then assigns it to themselves.

• Cleanup if the enroll process is aborted. Cleanup enroll process

Error Handling ¶

Normally the server responds with HTTP status in the 200-299 range and a JSON body (as described in corresponding service). In the case of errors, the HTTP status may be in the 400-599 range. The JSON Response body will be structured as follows.

{
  "errors": [
    {
      "description": "Cannot connect to the LDAP servers",
      "location": "server",
      "msgid": "AUCORE-0047"
    }
  ],
  "reason": "LDAP_NO_CONNECT"
}

Do not use msgid or description for result status checking. msgid is generated and may vary in different software versions. description is a translated string and will not be identical for all users. Use reason and the HTTP Status code for result status checking.

See Common Do logon for common status codes. Logon methods have additional individual statuses.

AA specific HTTP Status Codes ¶

HTTP 433 - endpoint session not found or expired. It is possible to get this error in the middle of logon process. You may start new endpoint session, resend do_logon request and continue.

HTTP 434 - logon session not found or expired. Re-logon, get new login_session_id and then you may continue the operation.

HTTP 435 - enroll process not found or expired. Re-start the enroll process and then you may continue the operation.

HTTP 444 - logon process not found or expired. Start new logon.

HTTP 400 - wrong data (missed fields etc.) or method protocol violation e.g. voice method already did phone call and wait for PIN code, but you ask it to call user again. Fix your data and retry.

HTTP 454 - logon process not found or expired, returned when oob method can’t find the correct login process.

HTTP 500 - serious error, usually not possible to retry. Start your operation from the beginning (open new logon process, etc.)

Additional HTTP Response Status Code information may be found in RFC 7231

Additional HTTP Response Status Code information may be found in RFC 7231

Parameters in HTTP Headers, JSON body and query-string ¶

You may send parameters such as login_session_id, endpoint_session_id, logon_process_id, user_name, etc. in JSON body, or HTTP headers, or query-string. Query-string is not recommended for sending secrets, but you may use it for debug in order to temporary override the value - query-string has the priority. Common practice is to use JSON body for POST/PUT/PATCH and headers for GET/DELETE. Or simply use headers everywhere for login_session_id and endpoint_session_id. Important! This is due to HTTP protocol. For headers, replace “_” with “-” in parameter name, e.g

• login_session_id -> login-session-id

• tenant_name -> tenant-name

Secrets ¶

In addition to credential data, the following fields are all secrets which should be protected by industry standard best practices.

1. login_session_id

2. endpoint_session_id

3. endpoint secret stored on endpoint device, passed as endpoint_secret_hash

Disclosing any of the above fields may allow third parties to read privileged data, impersonate users, or perform other actions behalf of users or endpoints.

Glossary of Terms ¶

Authentication Method

These are the specific authentication methods that are supported by the framework. In order to use a method, it may need to be enrolled, and will need to be connected to a chain. A method without a chain cannot be used to authenticate.

Name	Key	Authentication by
BankID	BANKID:1	BankID PIN
Bluetooth	BLUETOOTH_ESEC:1	Bluetooth devices
Device	DEVICE_AUTH:1	Windows TPM (Trusted Platform Module) based virtual smart card
Emergency password	EMERG_PASSWORD:1	Alternate/Emergency password
Face	FACE:1	Microsoft Cognitive API server
FIDO U2F	U2F:1	FIDO U2F tokens
Finger	FINGER:1	Fingerprint Biometric
Flex OTP	FLEX_OTP:1	Flexible selection of TOTP, HOTP or Smartphone Offline OTP
Home Affairs National Identification System	HANIS:1	Fingerprint Biometric
Home Affairs National Identification System	HANIS_FACE:1	Face Biometric
LDAP password	LDAP_PASSWORD:1	LDAP password, system uses different LDAP users repository
Denmark National ID	NEMID:1	Denmark National ID Validation
OAuth 2.0	OAUTH2:1	OAuth 2.0
One-time password e-mail	EMAIL_OTP:1	OTP sending by e-mail
One-time password hash	HOTP:1	OTP with hash algorithm
One time password SMS	SMS_OTP:1	OTP sending by SMS
One-time password time	TOTP:1	OTP with time based algorithm
Out-of-band	OOB:1	OOB UI (at server/oob/ui)
PKI	PKI:1	PKI
RADIUS password	RADIUS:1	RADIUS server
Security question	SECQUEST:1	Security question
Smartphone authentication	SMARTPHONE:1	Smartphone application
Smart Cards	CARD:1	Smart Cards
TouchID	TOUCHID:1	Apple TouchID
Virtual password	PASSWORD:1	Password assigned to user
Voice call	VOICE:1	Voice call
Web Authentication	WEBAUTH:1	Web services
Windows Hello	WINHELLO:1	Windows Hello

For additional information on enrollment and logon to individual methods see here

Chain

An authentication chain is a combination of authentication methods. A user must pass all methods in the chain to be successfully authenticated. For example, if you create a chain with LDAP Password and SMS, a user must first specify the LDAP Password. If the password is correct, the system sends an SMS with a One-Time-Password (OTP) to the user’s mobile. The user must specify the correct OTP to be authenticated.

You can create chains with multiple methods that are applicable for highly secure environments. You can create authentication chains for specific group of users in the repositories.

Enroll

Enrollment is the process of setting up the expected response for a particular authentication method. Internally the credential information gathered during enrollment is stored securely in authentication templates.

Endpoint

Endpoints are used to describe applications, clients, or devices that consume the Advanced Authentication API and provide authentication to users. Common examples of endpoint are computers, smartphones, RADIUS or VPN servers, and web applications.

Endpoint Session

Endpoint should create endpoint session on the server to start working. The endpoint session has a lifetime, after this, the endpoint session will be deleted and the session will need to be renewed. All users can work with one endpoint session on one endpoint.

Event

Advanced Authentication provides authentication events for the supported applications or devices. You can configure an event to leverage the Advanced Authentication functionalities for an application or a device. The application or device triggers the respective authentication event when a user tries to access it.

Logon

The server provides strong user authentication by using the chain-login concept. Each chain is a challenge-response login. To get a successful authentication, the entire chain should be completed. A chain can consist of one or many authentication method(s).

Login session

After a user logon, the system creates a login session, to access protected information from the server use this session. For example, reading event data requires a login session identifier.

User templates

The user’s templates contain authentication information associated with users. Each template is linked to a user and to an authentication method through the enrollment process. When users try to logon using a specific authentication method, the server finds the associated user template and provides authentication. Users cannot use authentication methods without associated user templates.

Localization ¶

It’s possible to choose a locale for server messages and warnings. Server detects a locale for request by the next properties ordered by priority:

1. HTTP parameter LOCALE for GET or DELETE requests.

2. JSON attribute LOCALE for POST, PUT and PATCH methods::

3. LOCALE cookie

4. Accept-Language HTTP header

• Request (application/json)

  {
      "login_session_id": "789",
      "method_id": "HOTP:1",
      "_LOCALE_": "ru-RU"
    }

Supported locale formats

1. Language with territory:

   en_US, nl_NL

2. Language with territory:

   ru-RU, fr-FR

3. Language only:

   ru, nl, fr

Message ID

Server issues an additional Message ID which can be used for message customization:

{
    "chains": [],
    "completed_methods": [],
    "current_method": "PASSWORD:1",
    "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
    "msgid": "AUCORE-1008",
    "msg": "Process has been started",
    "status": "MORE_DATA"
}

NOTE: Do not use msgid or msg for result status checking, use status instead. msg is a translated string and will not be identical for all users. msgid is generated and may vary in different software versions. If status is “FAILED” then use reason and the HTTP Status code for additional error handling.

Advanced Authentication API ¶

Authentication ¶

6.5 Changes ¶

Starting in version 6.5, the REST interface has been modified so that session and process IDs (Endpoint Session ID, Login Session ID, etc.) are no longer passed in the REST URL. Instead, this information is now included as additional HTTP header values or within the body of the relevant HTTP requests. In this REST documentation, each API is listed twice:

• The first definition represents the preferred method for version 6.5, where session IDs are passed via HTTP headers or the request body.

• The second definition, labeled LEGACY, applies to previous versions of AA where this information was included in the REST URL. This older definition is marked as “Legacy” for clarity. Unless otherwise noted authentication is required for all API calls. Acceptable authentication is either a login_session_id passed on each call or a bearer token passed in the http header as Authorization: Bearer {token}.

Login-Session-Id: r2P8TABStAxrbR9di7fXyOPZXf5fjjoE
Content-Type: application/json

[
  {
    "created": "2021-11-04T16:40:47.680880",
    "expired_after": "2022-11-05T16:40:47.679562",
    "guid": "4d010410057b3a54749385db5dfdc4da7712a4bb",
    "revoked": "None",
    "scopes": []
  },
  {
    "created": "2021-11-04T16:40:47.709524",
    "expired_after": "2022-11-05T16:40:47.708642",
    "guid": "3f9e37a880046eed363f42fbf86f103c4f463b9a",
    "revoked": "None",
    "scopes": []
  }
]

Content-Type: application/json

[
  {
    "created": "2021-11-04T16:40:47.680880",
    "expired_after": "2022-11-05T16:40:47.679562",
    "guid": "4d010410057b3a54749385db5dfdc4da7712a4bb",
    "revoked": "None",
    "scopes": []
  },
  {
    "created": "2021-11-04T16:40:47.709524",
    "expired_after": "2022-11-05T16:40:47.708642",
    "guid": "3f9e37a880046eed363f42fbf86f103c4f463b9a",
    "revoked": "None",
    "scopes": []
  }
]

Login-Session-Id: x8Pjdd5MOJigOdjGpnd9vLHdQZaCSVre
Content-Type: application/json

{
    "claims": {
        "rn": "IGBOOTSTRAPS",
    },
    "scopes": [],
    "ttl_days": 7
}

Login-Session-Id: x8Pjdd5MOJigOdjGpnd9vLHdQZaCSVre
Content-Type: application/json

{
  "bearer_token": "eyJhbGciOiJkaXIiLCJhdWQiOiJ0cyIsImVuYyI6IkExMjhDQkMtSFMyNTYiLCJpc3MiOiJ0cyIsInRlbiI6ImRlZjBkZWYwZGVmMGRlZjBkZWYwZGVmMGRlZjBkZWYwIn0..3gUu7fbR7Qfl_BbyeQ71PQ.t_wFI-NWhiFTPB9IYVH5RXyIzhjtIRNwhBnyU1yhacppvuZcuCYYSnlVbPSU-ZQGlwz-ooZKFEkQZwJnYCPU54Vs7qTrsAXIt5zMdGV7XHzf0Arqev-Oa7O3Nq0yHP_1v84YUL_WkrAqLuQ1zleU5ySvQUHjB8MPt58r24zBhPBQChcza4XeZcOIiLTrRqDPnXCT-rucyp7Bs9XtGsROIqEv5HP8yGBrq_Z6mN_8CQQrBtEwrMl_RvowLorfioYzEqJkCrZe_yw50wItiAyM3iSpOJ_gRTtCtyL3aUbxSIp7TKQGYE4IGwBBCdI1nq0xYRFGFSMOPlaimokfAzlVsA.MO0ONkAqVS084E4mxjTLqg",
  "details": {
    "created": "2021-11-04T14:01:21.278973",
    "expired_after": "2022-11-05T14:01:21.276665",
    "guid": "2ac6e4195cfb0ff83e55a0518e69d7d56e9ffcab",
    "revoked": "None",
    "scopes": []
  }
}

Content-Type: application/json

{
  "repo_name": "repo_1",
  "scopes": [],
  "ttl_days": 7
}

Content-Type: application/json

{
  "bearer_token": "eyJhbGciOiJkaXIiLCJhdWQiOiJ0cyIsImVuYyI6IkExMjhDQkMtSFMyNTYiLCJpc3MiOiJ0cyIsInRlbiI6ImRlZjBkZWYwZGVmMGRlZjBkZWYwZGVmMGRlZjBkZWYwIn0..3gUu7fbR7Qfl_BbyeQ71PQ.t_wFI-NWhiFTPB9IYVH5RXyIzhjtIRNwhBnyU1yhacppvuZcuCYYSnlVbPSU-ZQGlwz-ooZKFEkQZwJnYCPU54Vs7qTrsAXIt5zMdGV7XHzf0Arqev-Oa7O3Nq0yHP_1v84YUL_WkrAqLuQ1zleU5ySvQUHjB8MPt58r24zBhPBQChcza4XeZcOIiLTrRqDPnXCT-rucyp7Bs9XtGsROIqEv5HP8yGBrq_Z6mN_8CQQrBtEwrMl_RvowLorfioYzEqJkCrZe_yw50wItiAyM3iSpOJ_gRTtCtyL3aUbxSIp7TKQGYE4IGwBBCdI1nq0xYRFGFSMOPlaimokfAzlVsA.MO0ONkAqVS084E4mxjTLqg",
  "details": {
    "created": "2021-11-04T14:01:21.278973",
    "expired_after": "2022-11-05T14:01:21.276665",
    "guid": "2ac6e4195cfb0ff83e55a0518e69d7d56e9ffcab",
    "revoked": "None",
    "scopes": []
  }
}

Authorization: Bearer: {token}

Login-Session-Id: 3Ed2ah46mRbbdoBELfyeoGg9NsfFYnDZ
Content-Type: application/json

{
  "claims": {
    "rn": "IGBOOTSTRAPS"
  },
  "created": "2021-11-04T14:01:21.278973",
  "expired_after": "2022-11-05T14:01:21.276665",
  "guid": "2ac6e4195cfb0ff83e55a0518e69d7d56e9ffcab",
  "revoked": "None",
  "scopes": []
}

Content-Type: application/json

{
  "claims": {
    "rn": "IGBOOTSTRAPS"
  },
  "created": "2021-11-04T14:01:21.278973",
  "expired_after": "2022-11-05T14:01:21.276665",
  "guid": "2ac6e4195cfb0ff83e55a0518e69d7d56e9ffcab",
  "revoked": "None",
  "scopes": []
}

Authorization: Bearer {token}
Login-Session-Id: xDdsF6tEk4QFf7is0zXqoYMm4ndsGOqq

Authorization: Bearer {token}

Content-Type: application/json
Authorization: Bearer {token} (required, string) The token passed in the authorization header is revoked.

{
  "ttl_days": 30,
  "revoke": false
}

Content-Type: application/json

{
  "bearer_token": "eyJhbGciOiJkaXIiLCJhdWQiOiJ0cyIsImVuYyI6IkExMjhDQkMtSFMyNTYiLCJpc3MiOiJ0cyIsInRlbiI6ImRlZjBkZWYwZGVmMGRlZjBkZWYwZGVmMGRlZjBkZWYwIn0..3gUu7fbR7Qfl_BbyeQ71PQ.t_wFI-NWhiFTPB9IYVH5RXyIzhjtIRNwhBnyU1yhacppvuZcuCYYSnlVbPSU-ZQGlwz-ooZKFEkQZwJnYCPU54Vs7qTrsAXIt5zMdGV7XHzf0Arqev-Oa7O3Nq0yHP_1v84YUL_WkrAqLuQ1zleU5ySvQUHjB8MPt58r24zBhPBQChcza4XeZcOIiLTrRqDPnXCT-rucyp7Bs9XtGsROIqEv5HP8yGBrq_Z6mN_8CQQrBtEwrMl_RvowLorfioYzEqJkCrZe_yw50wItiAyM3iSpOJ_gRTtCtyL3aUbxSIp7TKQGYE4IGwBBCdI1nq0xYRFGFSMOPlaimokfAzlVsA.MO0ONkAqVS084E4mxjTLqg",
  "details": {
    "created": "2021-11-04T14:01:21.278973",
    "expired_after": "2022-11-05T14:01:21.276665",
    "guid": "2ac6e4195cfb0ff83e55a0518e69d7d56e9ffcab",
    "revoked": null,
    "scopes": []
  }
}

Content-Type: application/json
Authorization: Bearer: {token} (optional, string) The authorization token, if not passed then login_session_id must be part of the body.

{
  "login_session_id": "x1y2z3JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX",
  "fullRequests": true,
  "fullResponses": true,
  "failOnErrors": 3,
  "bulkids": {'oauth2_redir_uris': 'https://example.com'},
  "Operations": [
    {
      "method": "GET",
      "bulkId": "find-chain",
      "path": "/rest/admin/api/search/chains?q=SECOPEMAILCHAIN"
    },
    {
      "method": "POST",
      "bulkId": "create-email-chain",
      "path": "/rest/admin/api/chains",
      "data": {
        "name": "SECOPEMAILCHAIN",
        "is_enabled": true,
        "methods": [
          "EMAIL_OTP:1"
        ],
        "roles": [
          {
            "name": "ALL USERS",
            "idx": 0
          }
        ],
        "repos": [
          {
            "name": "LOCAL",
            "idx": 0
          }
        ]
      }
    },
    {
      "method": "GET",
      "bulkId": "get-app-id",
      "path": "/rest/admin/bulk"
    },
    {
      "method": "GET",
      "bulkId": "get-app-secret",
      "path": "/rest/admin/bulk"
    },
    {
      "method": "GET",
      "bulkId": "find-chain",
      "path": "/rest/admin/api/search/chains?q=SECOPEMAILCHAIN"
    },
    {
      "method": "POST",
      "bulkId": "create-event",
      "path": "/rest/admin/api/events",
      "data": {
        "name": "SECOPSEMAIL",
        "type": "OAuth2",
        "category_id": null,
        "is_enabled": true,
        "json_data": {
          "oauth2_appid": "ig-bulkId:get-app-id-cx",
          "oauth2_appsecret": "bulkId:get-app-secret",
          "oauth2_redir_uris": "https://www.google.com"
        },
        "chains": [
          {
            "id": "bulkId:find-chain"
          }
        ],
        "endpoints": []
      }
    },
    {
      "method": "POST",
      "bulkId": "wf-appmark",
      "bulkIdPath": "appmarks[*].id",
      "path": "/fedsso/api/v1/admin/applications",
      "data": {
        "name": [
          {
            "locale": "en",
            "value": "Workflow"
          }
        ],
        "description": [
          {
          "locale": "en",
          "value": "Workflow Service is a web-based service for creating workflows. It allows you to create, execute, and manage workflows, ranging from simple approval processes to custom workflows that exchange data with REST service"
          }
        ],
        "icon_id": "access",
        "enabled": true,
        "extensions_idp": {
          "saml": [],
          "oauth": [],
          "wsfed": []
        },
        "extensions_sp": {
          "saml": [],
          "oauth": [],
          "wsfed": []
        },
        "catalog_ref": [],
        "appmarks": [
          {
            "name": [
              {
                "locale": "en",
                "value": "Identity Governance Workflow"
              }
            ],
            "description": [
              {
                "locale": "en",
                "value": "Workflow Service is a web-based service for creating workflows. It allows you to create, execute, and manage workflows, ranging from simple approval processes to custom workflows that exchange data with REST service"
              }
            ],
            "icon_id": "access",
            "uri": "https://bulkId:aa_tenant_name.iga.bulkId:aa_tenant_base/wfconsole",
            "category": "applications",
            "launch_mode": "existing"
          }
        ],
        "authorizations": {
          "chains": [],
          "allow_chain_choice": 1
        }
      }
    }
  ]
}

Content-Type: application/json

{
  "Operations": [
    {
      "bulkId": "find-chain",
      "data": {
        "datums": [],
        "errors": []
      },
      "method": "GET",
      "request": {
        "login_session_id": "Qq3AudODLsLnwxKVmJedf0PwY1HKzBYW"
      },
      "status": "200"
    },
    {
      "bulkId": "create-email-chain",
      "create-email-chain": "47f8488ac08c11ee93980242ac110004",
      "data": {
        "apply_for_ep_owner": false,
        "forced": false,
        "grace_period": null,
        "groups": [],
        "id": "47f8488ac08c11ee93980242ac110004",
        "image_name": "EMAIL_OTP_1.png",
        "is_enabled": true,
        "is_image_custom": false,
        "is_trusted": null,
        "json_data": {
          "mfa_tags": [],
          "risk_level": "NONE"
        },
        "methods": [
          "EMAIL_OTP:1"
        ],
        "name": "SECOPEMAILCHAIN",
        "repos": [
          {
            "class_name": "LocalRepo",
            "config": {
              "fast_sync_enabled": true,
              "sync_data": {
                "last_fast_sync_error": "",
                "last_fast_sync_result": "",
                "last_full_sync_error": "",
                "last_full_sync_result": ""
              }
            },
            "id": "479824e6c08c11ee93980242ac110004",
            "name": "LOCAL"
          }
        ],
        "required_chain_id": null,
        "risk_level": "NONE",
        "roles": [
          {
            "desc": "All Users",
            "id": "479ed192c08c11ee93980242ac110004",
            "name": "ALL USERS"
          }
        ],
        "short_name": null
      },
      "location": "https://127.0.0.1/rest/admin/api/chains/47f8488ac08c11ee93980242ac110004",
      "method": "POST",
      "request": "{"name": "SECOPEMAILCHAIN", "is_enabled": true, "methods": ["EMAIL_OTP:1"], "roles": [{"name": "ALL USERS", "idx": 0}], "repos": [{"name": "LOCAL", "idx": 0}], "login_session_id": "Qq3AudODLsLnwxKVmJedf0PwY1HKzBYW"}",
      "status": "200"
    },
    {
      "bulkId": "get-app-id",
      "get-app-id": "9tUjRH5QYDcH13H90E7FOJ3zBNwS9yDa",
      "method": "GET",
      "status": "200"
    },
    {
      "bulkId": "get-app-secret",
      "get-app-secret": "8lmoNn1fhDyAGnEvFip2gHXbOktO3CKM",
      "method": "GET",
      "status": "200"
    },
    {
      "bulkId": "find-chain",
      "data": {
        "datums": [
          {
            "id": "47f8488ac08c11ee93980242ac110004",
            "name": "SECOPEMAILCHAIN"
          }
        ],
        "errors": []
      },
      "find-chain": "47f8488ac08c11ee93980242ac110004",
      "method": "GET",
      "request": {
        "login_session_id": "Qq3AudODLsLnwxKVmJedf0PwY1HKzBYW"
      },
      "status": "200"
    },
    {
      "bulkId": "create-event",
      "create-event": "48082318c08c11ee93980242ac110004",
      "data": {
        "all_categories": true,
        "category_id": null,
        "chains": [
          {
            "apply_for_ep_owner": false,
            "forced": false,
            "grace_period": null,
            "id": "47f8488ac08c11ee93980242ac110004",
            "image_name": "EMAIL_OTP_1.png",
            "is_enabled": true,
            "is_image_custom": false,
            "is_trusted": null,
            "json_data": {
              "mfa_tags": [],
              "risk_level": "NONE"
            },
            "methods": [
              "EMAIL_OTP:1"
            ],
            "name": "SECOPEMAILCHAIN",
            "repos": [
              {
                "class_name": "LocalRepo",
                "config": {
                  "fast_sync_enabled": true,
                  "sync_data": {
                    "last_fast_sync_error": "",
                    "last_fast_sync_result": "",
                    "last_full_sync_error": "",
                    "last_full_sync_result": ""
                  }
                },
                "id": "479824e6c08c11ee93980242ac110004",
                "name": "LOCAL"
              }
            ],
            "required_chain_id": null,
            "risk_level": "NONE",
            "short_name": ""
          }
        ],
        "endpoints": [
          {
            "desc": "OSP Endpoint",
            "device_id": "",
            "id": "43434343434343434343434343434343",
            "is_enabled": true,
            "is_local": true,
            "is_trusted": true,
            "name": "OSP",
            "owner": null,
            "software_type": "BuiltinOSP",
            "typ": 1
          }
        ],
        "expired_password_behavior": "allow",
        "forced": false,
        "geo_zones": [],
        "groups_to_return": [],
        "id": "48082318c08c11ee93980242ac110004",
        "is_enabled": true,
        "is_geo_fencing_enabled": false,
        "is_standard": false,
        "json_data": {
          "allow_logon_by_shared_template": true,
          "expired_password_behavior": "allow",
          "multiple_use_token": false,
          "oauth2_appid": "ig-9tUjRH5QYDcH13H90E7FOJ3zBNwS9yDa-cx",
          "oauth2_redir_uris": "https://www.google.com"
        },
        "multiple_use_token": false,
        "name": "SECOPSEMAIL",
        "return_groups_on_logon": false,
        "risk_policy_id": null,
        "type": "OAuth2"
      },
      "location": "https://127.0.0.1/rest/admin/api/events/48082318c08c11ee93980242ac110004",
      "method": "POST",
      "request": "{"name": "SECOPSEMAIL", "type": "OAuth2", "category_id": null, "is_enabled": true, "json_data": {"oauth2_appid": "ig-9tUjRH5QYDcH13H90E7FOJ3zBNwS9yDa-cx", "oauth2_appsecret": "8lmoNn1fhDyAGnEvFip2gHXbOktO3CKM", "oauth2_redir_uris": "https://www.google.com"}, "chains": [{"id": "47f8488ac08c11ee93980242ac110004"}], "endpoints": [], "login_session_id": "Qq3AudODLsLnwxKVmJedf0PwY1HKzBYW"}",
      "status": "200"
    }
  ],
  "status": "200"
}

Content-Type: image/png

Content-Type: application/json

{
  "login_session_id": "B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o"
}

Content-Type: application/json

{
  "server_id": null,
  "cookie_value": "300e82d5d1f31108cd064155728c1dda"
}

Content-Type: application/json

{
        "user_id": "4f34e2882991440ddd0fd515e0d0236c",
        "user_name": "LOCAL\ADMIN",
        "sid": "GKWrJUBaeBA20KHzHAcmzihNrOgdXooh",
        "repo_id": "3c9c1fd8061e11e6b224080027983191",
        "repo_obj_id": "3caa08a0061e11e6b224080027983191",
        "event_name": "",
        "data_id": ""
    }

Login-Session-Id: XKIXfZwtXo8pN7FrGVS89eFvygsBODCR
Content-Type: application/json

{
  "login_session_data": "296e9f9d8c19d7f9f....2a674855e3f574cb9e272bf68"
}

Content-Type: application/json

{
  "login_session_data": "296e9f9d8c19d7f9f....2a674855e3f574cb9e272bf68"
}

Endpoint-Session-Id: 4uURgbMTGfgUIvi2WMnTaIvXrpytmp3q
Content-Type: application/json

{
  "items": [
    {
      "category": "messages",
      "custom": "",
      "default": "ACCESS DENIED",
      "key": "errors.access_denied",
      "locale": "en"
    },
    {
      "category": "messages",
      "custom": "",
      "default": "Logon failed",
      "key": "errors.logon_failed",
      "locale": "en"
    },
    {
      "category": "messages",
      "custom": "",
      "default": "User not found",
      "key": "errors.user_not_found",
      "locale": "en"
    }
  ]
}

Content-Type: application/json

{
  "items": [
    {
      "category": "messages",
      "custom": "",
      "default": "ACCESS DENIED",
      "key": "errors.access_denied",
      "locale": "en"
    },
    {
      "category": "messages",
      "custom": "",
      "default": "Logon failed",
      "key": "errors.logon_failed",
      "locale": "en"
    },
    {
      "category": "messages",
      "custom": "",
      "default": "User not found",
      "key": "errors.user_not_found",
      "locale": "en"
    }
  ]
}

Endpoint-Session-Id: EkFPKRjqJRHfQ30EzC7Vx0TP0qgzaWfy
Content-Type: application/json

{
  "category": "messages",
  "custom": "",
  "default": "Logon failed",
  "key": "errors.logon_failed",
  "locale": "en"
}

Content-Type: application/json

{
  "category": "messages",
  "custom": "",
  "default": "Logon failed",
  "key": "errors.logon_failed",
  "locale": "en"
}

Content-Type: application/json

{
  "login_session_id": "B3XBHzwAHuPfHwMHfSjf3eVdV3glCa0o",
  "method_id": "HOTP:1"
}

Content-Type: application/json

{
  "enroll_process_id": "JfgSCsAr89tR3tu92mKV3MWy4LWSmroU"
}

Enroll-Process-Id: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Content-Type: application/json

{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "counter": 10,
    "secret": "0000000000000100"
  }
}

Enroll-Process-Id: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Content-Type: application/json

{
  "method_id": "HOTP:1",
  "msg": "",
  "reason": "",
  "status": "OK"
}

Content-Type: application/json

{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "counter": 10,
    "secret": "0000000000000100"
  }
}

Content-Type: application/json

{
  "method_id": "HOTP:1",
  "msg": "",
  "reason": "",
  "status": "OK"
}

Content-Type: application/json

{
  "login_session_id": "rBT79CAz8AWh1o920OrHumx32iaToCU9",
  "response": {
    "password": "0000000000000100"
  }
}

Content-Type: application/json

{
  "msg": "Secret and counter are required",
  "msgid": "AUCORE-3028",
  "reason": "",
  "status": "FAILED"
}

[DELETE /api/v1/enroll/{enroll_process_id:[a-zA-Z0-9]{32}}]

Enroll-Process-Id: S0SpCAkf33siyJKw9p5xlNZuTiOTnQn7
Content-Type: application/json

null

Content-Type: application/json

null

Login-Session-Id: rBT79CAz8AWh1o920OrHumx32iaToCU9
Content-Type: application/json

null

Login-Session-Id: rBT79CAz8AWh1o920OrHumx32iaToCU9
Content-Type: application/json

{
  "chains": {
    "CAT1": [
      {
        "apply_for_ep_owner": false,
        "grace_period": "None",
        "id_hex": "3c927b4a061e11e6b224080027983191",
        "image_name": "default",
        "is_enabled": true,
        "is_trusted": "None",
        "methods": [
          {
            "id": "BANKID:1",
            "is_enrolled": false
          },
          {
            "id": "EMAIL_OTP:1",
            "is_enrolled": true
          }
        ],
        "mfa_tags": [],
        "name": "Bankid+Email-otp",
        "position": 0,
        "required_chain_id_hex": "None",
        "short_name": ""
      },
      {
        "apply_for_ep_owner": false,
        "grace_period": "None",
        "id_hex": "3c927b4a061e11e6b224080027983191",
        "image_name": "SMS_OTP_1.png",
        "is_enabled": true,
        "is_trusted": "None",
        "methods": [
          {
            "id": "SMS_OTP:1",
            "is_enrolled": true
          }
        ],
        "mfa_tags": [],
        "name": "sms",
        "position": 1,
        "required_chain_id_hex": "None",
        "short_name": ""
      }
    ]
  },
  "": [ // empty refers to Default category
    {
      "apply_for_ep_owner": false,
      "grace_period": "None",
      "id_hex": "3c927b4a061e11e6b224080027983191",
      "image_name": "PASSWORD_1.png",
      "is_enabled": true,
      "is_trusted": "None",
      "methods": [
        {
          "id'": "PASSWORD:1",
          "is_enrolled": true
        }
      ],
      "mfa_tags": [],
      "name": "Password Only",
      "position": 0,
      "required_chain_id_hex": "None",
      "short_name": ""
    }
  ]
}

Content-Type: application/json

{
  "login_session_id":"rBT79CAz8AWh1o920OrHumx32iaToCU9",
}

Content-Type: application/json

{
  "chains": {
    "CAT1": [
      {
        "apply_for_ep_owner": false,
        "grace_period": "None",
        "id_hex": "3c927b4a061e11e6b224080027983191",
        "image_name": "default",
        "is_enabled": true,
        "is_trusted": "None",
        "methods": [
          {
            "id": "BANKID:1",
            "is_enrolled": false
          },
          {
            "id": "EMAIL_OTP:1",
            "is_enrolled": true
          }
        ],
        "mfa_tags": [],
        "name": "Bankid+Email-otp",
        "position": 0,
        "required_chain_id_hex": "None",
        "short_name": ""
      },
      {
        "apply_for_ep_owner": false,
        "grace_period": "None",
        "id_hex": "3c927b4a061e11e6b224080027983191",
        "image_name": "SMS_OTP_1.png",
        "is_enabled": true,
        "is_trusted": "None",
        "methods": [
          {
            "id": "SMS_OTP:1",
            "is_enrolled": true
          }
        ],
        "mfa_tags": [],
        "name": "sms",
        "position": 1,
        "required_chain_id_hex": "None",
        "short_name": ""
      }
    ]
  },
  "": [ // empty refers to Default category
    {
      "apply_for_ep_owner": false,
      "grace_period": "None",
      "id_hex": "3c927b4a061e11e6b224080027983191",
      "image_name": "PASSWORD_1.png",
      "is_enabled": true,
      "is_trusted": "None",
      "methods": [
        {
          "id'": "PASSWORD:1",
          "is_enrolled": true
        }
      ],
      "mfa_tags": [],
      "name": "Password Only",
      "position": 0,
      "required_chain_id_hex": "None",
      "short_name": ""
    }
  ]
}

Content-Type: application/json

{
  "password": "12345",
  "user_name": "user1",
  "category_name": "test",
  "comment": "MY_LAPTOP",
  "tenant_name": "HOME"
}

Content-Type: application/json

{
  "category_id": "f1be127607dc11e69bae080027983191",
  "hash": "sha1",
  "id": "72fe734607db11e69bae080027983191",
  "is_base32_secret": false,
  "otp_format": "dec6",
  "period": 30,
  "secret": "5ea77p94xbdfmoqy67n3c76sz64n0o31",
  "serial": null,
  "status": "OK"
}

Content-Type: application/json

{
  "msg": "Invalid credentials",
  "reason": "LDAP_PASSWORD_WRONG",
  "status": "FAILED"
}

Content-Type: application/json

{
  "template_id": "user1",
  "secret_hash": "df2e2418e60c421ac7b1455fc63c4dd3d798f07be526a44dd4b546d73bd5a22e"
}

Content-Type: application/json

{
  "status": "OK"
}

Content-Type: application/json

{
  "msg": "Wrong secret hash was provided",
  "reason": "WRONG_SECRET_HASH",
  "status": "FAILED"
}

Content-Type: application/json

{
    "name": "workstation1.domain.local",  // pass hostname here
    "software_type": "Windows Client",    // PAM Module/AD filter/etc
    "software_ver": "6.0.111",
    "desc": "New NAM endpoint",
    "tenant_name": "MARIA_GROUP",
    "os": {
        // recognized fields
        "type": "Windows",  // Linux, MacOS etc.
        "display_name": "Windows 10 Version 1607",  // Ubuntu 14.04.3 LTS
        "platform": "x64",  // x86 ARM8 etc
        "version": "10.0.14393",  // "14.04.03"
        // Windows machine GUID/SID, Linux machine-id etc.
        // please send GUID as "7c0da94b-ded2-4eb3-9c90-22a568f8d30a",
        // not as "{7c0da94b-ded2-4eb3-9c90-22a568f8d30a}" to slightly improve indexing performance
        "device_id": "<str, unique computer/device ID>",
    // other fields possible - OS specific info
    "build": "14393",
    "tz": "+07:00",
    "win10_version": "1607",
    "RAM": "32768",
    "domain": "WORKGROUP",
    "linux_distr": "Ubuntu",
    "windows_family": "Desktop"
},
    "extra": {
        // any extra fields possible
    },
    "_force": true  // delete conflicting endpoint if any
}

Content-Type: application/json

{
  "secret": "cctdgkMc4pyKw0jAduP5CetGtaGKniPL",
  "id": "76d1d94607da11e69bae080027983191"
}

Content-Type: application/json

{
  "name": "nam.new.trusted.endpoint",
  "typ": 3,
  "desc": "New trusted NAM endpoint2",
  "is_trusted": true,
  "tenant_name": "MARIA_GROUP",
  "auth_data": {
    "method_id": "PASSWORD:1",
    "user_name": "LOCAL\\admin",
    "password": "password"
  }
}

Content-Type: application/json

{
  "secret": "cJd8UjfftveHW4JXrphTupMDACoF06xZ",
  "id": "72fe734607db11e69bae080027983191"
}

Content-Type: application/json

{
    "name": "nam.new.trusted.endpoint3",
    "typ": 1,
    "desc": "New trusted NAM endpoint",
    "is_enabled": true,
    "id": "d5f5881e07df11e69bae080027983191",
    "is_trusted": true
    // os information is not returned for security reason - this call is world-accessible
}

Content-Type: application/json

{
    "errors": [
            {
            "location": "server",
            "name": "AuError",
            "msgid": "AUCORE-1022",
            "description": "Endpoint could not be found"
            },
        "reason": "RESOURCE_NOT_FOUND"
    ],
    "status": "FAILED"
}

Content-Type: application/json

{
  "auth_data": {
    "method_id": "PASSWORD:1",
    "user_name": "LOCAL\\admin",
    "password": "admin"
  }
}

Content-Type: application/json

null

Content-Type: application/json

{
  "secret": "M2QjVLgxVKOYrpVtYKafsGtKrBRx1aTU"
}

Content-Type: application/json

null

Content-Type: application/json

{
    "name":"sara.domain.local",
    "auth_data": {
                    "method_id": "PASSWORD:1",
                    "user_name": "LOCAL\admin",
                    "password": "admin"
    },
    // optional
    "os": {
        // ... Entire dictionary will be changed
    }
    "software_type": "Windows Client",
    "software_ver": "6.2",
}

Content-Type: application/json

null

Content-Type: application/json

{
  "tenant_name": "MARIA_GROUP",
  "name": "nam.new.trusted.endpoint3",
  "auth_data": {
    "method_id": "PASSWORD:1",
    "user_name": "LOCAL\\admin",
    "password": "admin"
  }
}

Content-Type: application/json

{
  "endpoints": [
    {
      "name": "nam.new.trusted.endpoint3",
      "typ": 1,
      "desc": "New trusted NAM endpoint",
      "is_enabled": true,
      "id": "d5f5881e07df11e69bae080027983191",
      "is_trusted": true
    }
  ]
}

Content-Type: application/json

{
  "endpoint_secret_hash": "d8065693d119fd3d3b0ea54b31d0bf66cc6b56879de302c94cf0e464fef67124",
  "name": "new.endpoint.name",  // rename endpoint (e.g if hostname has been changed)
  // Optional - update os and client software information
  "os": {
    // Entire dictionary will be changed
    // Always pass full info or don't pass any
    "display_name": "Ubuntu 14.04.3 LTS",
    "platform": "x64",
    "version": "14.04.03"
  },
  "salt": "i_am_salt",
  "session_data": {
    "any": {
      "data": [
        "you",
        "want to store",
        "in session"
      ]
    }
  },
  "software_type": "Windows Client",  // optional
  "software_ver": "6.2"  // optional
}

Content-Type: application/json

{
  "endpoint_session_id": "0TbKHn9MsZKJYhfQ0FZ0W2y0RHVwxTOY"
}

Content-Type: application/json

{
  "salt": "i_am_salt",
  "endpoint_secret_hash": "d8065693d119fd3d3b0ea54b31d0bf66cc6b56879de302c94cf0e464fef67127",
  //incorrect secret hash
  "session_data": {"any": { "data": ["you", "want to store", "in session"] } }
}

Content-Type: application/json

{
  "errors": [
   {
     "location": "server",
     "name": "AuError",
     "msgid": "AUCORE-1065",
     "description": "Incorrect credentials (endpoint secret)"
   },
  "reason": "ACCESS_DENIED"
  ],
  "status": "FAILED"
}

def get_endpoint_secret_hash(endpoint, salt):
    # Calculates endpoint secret hash as SHA256(endpoint.secret, SHA256(endpoint.id_hex + salt))
    # salt is random string of length >= 1

    salted_endpoint_id = (endpoint.id_hex + salt).encode('utf-8')
    endpoint_id_hash = sha256(salted_endpoint_id).hexdigest()
    salted_enpoint_secret = (endpoint.secret + endpoint_id_hash).encode('utf-8')

    return sha256(salted_enpoint_secret).hexdigest()

Endpoint-Session-Id: 3bATmmruQP7wJfnux80kdlhXKSFtFPt0
Content-Type: application/json

{
  "endpoint_id": "377ac5fe07e011e69bae080027983191",
  "session_data": {
    "any": {
      "data": [
        "you",
        "want to store",
        "in the session"
      ]
    }
  },
  "sid": "daTpDaWAd5BP0QzBNcIulLuFYCJ32Aak"
}

Content-Type: application/json

{
    "endpoint_id": "377ac5fe07e011e69bae080027983191",
    "session_data": {
        "any": {
            "data": [
                "you",
                "want to store",
                "in the session"
            ]
        }
    },
    "sid": "daTpDaWAd5BP0QzBNcIulLuFYCJ32Aak"
}

[POST /api/v1/endpoints/{endpoint_id:[0-9a-fA-F]{32}}/sessions]

Endpoint-Session-Id: TpVghlkpH1GLXqWQxNzeXjyuoxhah6Rh
Content-Type: application/json

null

Content-Type: application/json

null

Login-Session-Id: wDwelf8dfOYKVQR1e5LdijA26r1cBmbH
Content-Type: application/json

{
  "events": [
    {
      "category_id": null,
      "chains": [
        {
          "apply_for_ep_owner": false,
          "forced": false,
          "grace_period": null,
          "id": "4c9f4524608911e7ae720800276d2239",
          "image_name": "ANY.png",
          "is_enabled": true,
          "is_image_custom": false,
          "is_trusted": null,
          "methods": [
            "ANY"
          ],
          "name": "Test-chain",
          "required_chain_id": null,
          "short_name": ""
        }
      ],
      "endpoints": [],
      "forced": false,
      "geo_zones": [],
      "id": "4c9e8508608911e7ae720800276d2239",
      "is_enabled": true,
      "is_geo_fencing_enabled": false,
      "is_standard": false,
      "json_data": {},
      "name": "TEST",
      "type": "Generic"
    }
  ]
}

Content-Type: application/json

{
  "events": [
    {
      "category_id": null,
      "chains": [
        {
          "apply_for_ep_owner": false,
          "forced": false,
          "grace_period": null,
          "id": "4c9f4524608911e7ae720800276d2239",
          "image_name": "ANY.png",
          "is_enabled": true,
          "is_image_custom": false,
          "is_trusted": null,
          "methods": [
            "ANY"
          ],
          "name": "Test-chain",
          "required_chain_id": null,
          "short_name": ""
        }
      ],
      "endpoints": [],
      "forced": false,
      "geo_zones": [],
      "id": "4c9e8508608911e7ae720800276d2239",
      "is_enabled": true,
      "is_geo_fencing_enabled": false,
      "is_standard": false,
      "json_data": {},
      "name": "TEST",
      "type": "Generic"
    }
  ]
}

Login-Session-Id: 6Rxll3dXqdxbKBnSw5b0bxI8E9zmRBtt
Content-Type: application/json

{
  "name": "Hello, world!",
  "type": "Hello, world!",
  "is_enabled": true,
  "is_geo_fencing_enabled": true,
  "category_id": "Hello, world!",
  "geo_zones": [],
  "chains": [],
  "endpoints": []
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The name of the event."
    },
    "type": {
      "type": "string",
      "description": "The type of event. one of [\"Generic\",\"OSLogon\",\"PasswordStore\",\"OAuth2\", \"SAML2\"]"
    },
    "is_enabled": {
      "type": "boolean",
      "description": "Whether to enable the event."
    },
    "is_geo_fencing_enabled": {
      "type": "boolean",
      "description": "Whether to enable the geofencing."
    },
    "category_id": {
      "type": "string",
      "description": "The ID of the category."
    },
    "geo_zones": {
      "description": "The list of the geo zones."
    },
    "chains": {
      "description": "The list of chains."
    },
    "endpoints": {
      "description": "The list of the endpoints."
    }
  }
}

Login-Session-Id: 6Rxll3dXqdxbKBnSw5b0bxI8E9zmRBtt
Content-Type: application/json

{
  "forced": false,
  "type": "Generic",
  "endpoints": [
    {
      "is_local": false,
      "device_id": "",
      "software_type": "",
      "name": "TEST_ENDPOINT",
      "desc": "",
      "typ": null,
      "owner": null,
      "is_trusted": false,
      "is_enabled": true,
      "id": "56ff565c608a11e7afe10800276d2239"
    }
  ],
  "is_standard": false,
  "is_enabled": false,
  "category_id": null,
  "is_geo_fencing_enabled": false,
  "name": "TEST_EVENT2",
  "chains": [
    {
      "apply_for_ep_owner": false,
      "image_name": "default",
      "required_chain_id": null,
      "is_enabled": true,
      "forced": false,
      "name": "chain",
      "grace_period": null,
      "short_name": "",
      "id": "56ff8384608a11e7afe10800276d2239",
      "is_image_custom": false,
      "methods": [
        "OTP:1",
        "PASSWORD:1"
      ],
      "is_trusted": null
    }
  ],
  "json_data": {},
  "geo_zones": [],
  "id": "59704798608a11e7afe10800276d2239"
}

Login-Session-Id: 6Rxll3dXqdxbKBnSw5b0bxI8E9zmRBtt
Content-Type: application/json
Login-Session-Id: 6Rxll3dXqdxbKBnSw5b0bxI8E9zmRBtt

{
  "name":"OAUTH_EVENT",
  "type":"OAuth2",
  "chains":[...],
  "category_id":null,
  "endpoints":[...],
  "json_data":{
    "oauth2_appid":"id-5wHqLd41D3Z9WUXKcHKjEPk02GHhRJAb",
    "oauth2_appsecret":"secret-QnrJFOw32IFHDW1bYWR8TJCl1psDEOkr",
    "oauth2_redir_uris":"https://test1\nhttps://test2",
    "ignore_user_lockout":true,
    "is_recaptcha_enabled":false,
    "oauth2_public_client":false,
    "oauth2_supports_authorization_code":true,
    "oauth2_supports_client_credentials":true,
    "oauth2_supports_implicit":true,
    "oauth2_use_token_revocation":true,
    "oauth2_use_session_token_revocation":true,
    "oauth2_auth_code_ttl":180,
    "oauth2_access_token_ttl":180,
    "oauth2_refresh_token_ttl":180,
    "oauth2_public_refresh_token_ttl":180,
    "oauth2_session_token_revocation_ttl":180,
    "oauth2_token_sharing":false,
    "oidc_enabled":false,
    "oidc_all_claims_in_id_token":false
  }
}

Login-Session-Id: 6Rxll3dXqdxbKBnSw5b0bxI8E9zmRBtt
Content-Type: application/json

{
  "forced":false,
  "id":"f38595d2616511e7ae230800276d2239",
  "name":"OAUTH_EVENT",
  "category_id":null,
  "is_geo_fencing_enabled":false,
  "is_standard":false,
  "geo_zones": [...],
  "endpoints": [
    {
      "owner":null,
      "is_trusted":true,
      "typ":null,
      "device_id":"",
      "desc":"OSP Endpoint",
      "id":"43434343434343434343434343434343",
      "name":"OSP",
      "is_local":true,
      "is_enabled":true,
      "software_type":"BuiltinOSP"
    }
  ],
  "chains": [...],
  "is_enabled":false,
  "type":"OAuth2",
  "json_data":{
    "oauth2_redir_uris":"https://test1",
    "oauth2_appsecret":"secret-QnrJFOw32IFHDW1bYWR8TJCl1psDEOkr",
    "oauth2_appid":"id-5wHqLd41D3Z9WUXKcHKjEPk02GHhRJAb"
  }
}

Content-Type: application/json

{
  "name": "Hello, world!",
  "type": "Hello, world!",
  "is_enabled": true,
  "is_geo_fencing_enabled": true,
  "category_id": "Hello, world!",
  "geo_zones": [],
  "chains": [],
  "endpoints": []
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "event name"
    },
    "type": {
      "type": "string",
      "description": "type of event, one of [\"Generic\",\"OSLogon\",\"PasswordStore\",\"OAuth2\", \"SAML2\"]"
    },
    "is_enabled": {
      "type": "boolean",
      "description": "is event enabled"
    },
    "is_geo_fencing_enabled": {
      "type": "boolean",
      "description": "is geofencing enabled"
    },
    "category_id": {
      "type": "string",
      "description": "category id"
    },
    "geo_zones": {
      "description": "list of geo zones"
    },
    "chains": {
      "description": "list of chains"
    },
    "endpoints": {
      "description": "list of endpoints"
    }
  }
}

Content-Type: application/json

{
     "forced":false,
     "type":"Generic",
     "endpoints":[
       {
         "is_local":false,
         "device_id":"",
         "software_type":"",
         "name":"TEST_ENDPOINT",
         "desc":"",
         "typ":null,
         "owner":null,
         "is_trusted":false,
         "is_enabled":true,
         "id":"56ff565c608a11e7afe10800276d2239"
       }
     ],
     "is_standard":false,
     "is_enabled":false,
     "category_id":null,
     "is_geo_fencing_enabled":false,
     "name":"TEST_EVENT2",
     "chains":[
       {
         "apply_for_ep_owner":false,
         "image_name":"default",
         "required_chain_id":null,
         "is_enabled":true,
         "forced":false,
         "name":"chain",
         "grace_period":null,
         "short_name":"",
         "id":"56ff8384608a11e7afe10800276d2239",
         "is_image_custom":false,
         "methods":[
            "OTP:1",
            "PASSWORD:1"
         ],
         "is_trusted":null
       }
     ],
     "json_data":{...},
     "geo_zones":[...],
     "id":"59704798608a11e7afe10800276d2239"
   }

Content-Type: application/json

{
     "name":"OAUTH_EVENT",
     "type":"OAuth2",
     "chains":[...],
     "category_id":null,
     "endpoints":[...],
     "json_data":{
       "oauth2_appid":"id-5wHqLd41D3Z9WUXKcHKjEPk02GHhRJAb",
       "oauth2_appsecret":"secret-QnrJFOw32IFHDW1bYWR8TJCl1psDEOkr",
       "oauth2_redir_uris":"https://test1\\nhttps://test2",
       "ignore_user_lockout":true,
       "is_recaptcha_enabled":false,
       "oauth2_public_client":false,
       "oauth2_supports_authorization_code":true,
       "oauth2_supports_client_credentials":true,
       "oauth2_supports_implicit":true,
       "oauth2_use_token_revocation":true,
       "oauth2_use_session_token_revocation":true,
       "oauth2_auth_code_ttl":180,
       "oauth2_access_token_ttl":180,
       "oauth2_refresh_token_ttl":180,
       "oauth2_public_refresh_token_ttl":180,
       "oauth2_session_token_revocation_ttl":180,
       "oauth2_token_sharing":false,
       "oidc_enabled":false,
       "oidc_all_claims_in_id_token":false
     }
   }

Content-Type: application/json

{
     "forced":false,
     "id":"f38595d2616511e7ae230800276d2239",
     "name":"OAUTH_EVENT",
     "category_id":null,
     "is_geo_fencing_enabled":false,
     "is_standard":false,
     "geo_zones": [...],
     "endpoints": [
       {
         "owner":null,
         "is_trusted":true,
         "typ":null,
         "device_id":"",
         "desc":"OSP Endpoint",
         "id":"43434343434343434343434343434343",
         "name":"OSP",
         "is_local":true,
         "is_enabled":true,
         "software_type":"BuiltinOSP"
       }
     ],
     "chains": [...],
     "is_enabled":false,
     "type":"OAuth2",
     "json_data":{
       "oauth2_redir_uris":"https://test1",
       "oauth2_appsecret":"secret-QnrJFOw32IFHDW1bYWR8TJCl1psDEOkr",
       "oauth2_appid":"id-5wHqLd41D3Z9WUXKcHKjEPk02GHhRJAb"
     }
   }

Login-Session-Id: g2E4Mqcv7CrpS6N2jIu9gbQ8Fd2PZHrB
Content-Type: application/json

{
  "type": "Generic",
  "endpoints": [],
  "chains": [
    {
      "short_name": "",
      "is_enabled": true,
      "methods": [
        "ANY"
      ],
      "is_trusted": null,
      "is_image_custom": false,
      "grace_period": null,
      "name": "Test-chain",
      "id": "4c9f4524608911e7ae720800276d2239",
      "apply_for_ep_owner": false,
      "image_name": "ANY.png",
      "required_chain_id": null,
      "forced": false
    }
  ],
  "is_enabled": true,
  "json_data": {},
  "is_standard": false,
  "is_geo_fencing_enabled": false,
  "category_id": null,
  "geo_zones": [],
  "id": "4c9e8508608911e7ae720800276d2239",
  "name": "TEST",
  "forced": false
}

Content-Type: application/json

{
  "type":"Generic",
  "endpoints":[...],
  "chains":[
    {
      "short_name":"",
      "is_enabled":true,
      "methods":[
         "ANY"
      ],
      "is_trusted":null,
      "is_image_custom":false,
      "grace_period":null,
      "name":"Test-chain",
      "id":"4c9f4524608911e7ae720800276d2239",
      "apply_for_ep_owner":false,
      "image_name":"ANY.png",
      "required_chain_id":null,
      "forced":false
    }
  ],
  "is_enabled":true,
  "json_data":{...},
  "is_standard":false,
  "is_geo_fencing_enabled":false,
  "category_id":null,
  "geo_zones":[],
  "id":"4c9e8508608911e7ae720800276d2239",
  "name":"TEST",
  "forced":false
}

Login-Session-Id: TLjPukeooidWR1OFz2MyLWPW2avCSRKn
Content-Type: application/json

{
  "chains":[...],
  "category_id":null,
  "name":"TEST2",
  "type":"Generic",
  "endpoints":[
    {
      "id":"a135281e608a11e7a1810800276d2239"
    }
  ]
}

Login-Session-Id: TLjPukeooidWR1OFz2MyLWPW2avCSRKn
Content-Type: application/json

{
  "is_geo_fencing_enabled": false,
  "forced": false,
  "type": "Generic",
  "json_data": {},
  "id": "a131020c608a11e7a1810800276d2239",
  "geo_zones": [],
  "chains": [],
  "category_id": null,
  "is_enabled": false,
  "name": "TEST2",
  "is_standard": false,
  "endpoints": [
    {
      "is_local": false,
      "software_type": "",
      "is_trusted": false,
      "desc": "",
      "typ": null,
      "is_enabled": true,
      "device_id": "",
      "name": "TEST_ENDPOINT",
      "owner": null,
      "id": "a135281e608a11e7a1810800276d2239"
    }
  ]
}

Content-Type: application/json

{
  "name": "Hello, world!",
  "type": "Hello, world!",
  "is_enabled": true,
  "is_geo_fencing_enabled": true,
  "category_id": "Hello, world!",
  "geo_zones": [],
  "chains": [],
  "endpoints": []
}

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "event name"
    },
    "type": {
      "type": "string",
      "description": "type of event, one of [\"Generic\",\"OSLogon\",\"PasswordStore\",\"OAuth2\", \"SAML2\"]"
    },
    "is_enabled": {
      "type": "boolean",
      "description": "is event enabled"
    },
    "is_geo_fencing_enabled": {
      "type": "boolean",
      "description": "is geo fencing enabled"
    },
    "category_id": {
      "type": "string",
      "description": "category id"
    },
    "geo_zones": {
      "description": "list of geo zones"
    },
    "chains": {
      "description": "list of chains"
    },
    "endpoints": {
      "description": "list of endpoints"
    }
  }
}

Content-Type: application/json

{
  "is_geo_fencing_enabled":false,
  "forced":false,
  "type":"Generic",
  "json_data":{...},
  "id":"a131020c608a11e7a1810800276d2239",
  "geo_zones":[...],
  "chains":[...],
  "category_id":null,
  "is_enabled":false,
  "name":"TEST2",
  "is_standard":false,
  "endpoints":[
    {
      "is_local":false,
      "software_type":"",
      "is_trusted":false,
      "desc":"",
      "typ":null,
      "is_enabled":true,
      "device_id":"",
      "name":"TEST_ENDPOINT",
      "owner":null,
      "id":"a135281e608a11e7a1810800276d2239"
    }
  ]
}

Login-Session-Id: JHAHdZiRKdaYcPhQUHcPYgYSElFcMBVX
Content-Type: application/json

null

POST /api/v1/logon
    {
        "method_id": "PASSWORD:1",
        "user_name": "REPONAME\\USERNAME",
        "is_1N": true/false,   // optional, default false
        "unit_id": "xxx",   // for 1N login
        "event": "xxx"   // can be empty string for testing (allow any method)
    }

{
    "chains": [],
    "completed_methods": [],
    "current_method": "PASSWORD:1",
    "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
    "msg": "Process has been started",
    "status": "MORE_DATA"
}

POST /api/v1/logon/do_logon
    {
      "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
      "response": "method-specific dictionary, maybe omitted if method does not requires data on 1st do_login"
    }

Return
    {
        # method-specific data such as
        "challenge": {"rounds": 100, "salt": "cdf123Dx"},
        "status": "MORE_DATA"
    }

POST /api/v1/logon/do_logon
    {
      "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
      "response": {"answer" : "my-password" # method-specific dict in "response" field}
                                            # this is "response" to "challenge" which server sent in previous do_logon
    }

{ 
    "chains": [],
    "completed_methods": ["PASSWORD:1"],
    "login_session_id": "YTxTmMW6RPv051RmeCiyBn7txzE0JoM2",
    "msg": "Welcome",
    "repo_id": "703f7c641beb11e48c69000c294fde0e",
    "user_id": "7044631e1beb11e48c69000c294fde0e",
    "user_name": "LOCAL\\\\user1",
    "event_name": "Windows logon",
    "event_data_id": "OSLogon",
    "status": "OK",
    "completed_chain": {
        "name": "Admin Password",
        "position": 0,
        "id_hex": "3c8c306e061e11e6b224080027983191",
        "apply_for_ep_owner": false,
        "required_chain_id_hex": null,
        "methods": ["PASSWORD:1"],
        "short_name": "",
        "image_name": "PASSWORD_1.png",
        "is_trusted": null,
        "is_enabled": true,
        "grace_period": null,
        "mfa_tags" : []
    }
}

{ 
    "msg": "Incorrect password",
    "status": "FAILED",
    "reason": "ACCESS_DENIED",
}

GET  /api/v1/logon/chains?event=Windows%20logon&is_trusted=true

   decide what chain to complete and...

Content-Type: application/json

{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "event": "NAM",
  "method_id": "PASSWORD:1",
  "user_name": "LOCAL\USER1"
}

Content-Type: application/json

{
  "chains": [
    {
      "apply_for_ep_owner": false,
      "grace_period": null,
      "id_hex": "3c927b4a061e11e6b224080027983191",
      "image_name": "PASSWORD_1.png",
      "is_enabled": true,
      "is_trusted": null,
      "methods": [
        "PASSWORD:1"
      ],
      "name": "Authenticators Management - Password",
      "position": 1,
      "required_chain_id_hex": null,
      "short_name": ""
    }
  ],
  "completed_methods": [],
  "current_method": "PASSWORD:1",
  "event_data_id": "OSLogon",
  "event_name": "NAM",
  "logon_process_id": "TTPeglOJxUZ3R8IV3e5vwUgUQACs8fBS",
  "msg": "Process has been started",
  "msgid": "AUCORE-1008",
  "plugins": [],
  "reason": "PROCESS_STARTED",
  "status": "MORE_DATA"
}

Content-Type: application/json

{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "event": "NAM",
  "is_1N": true,
  "method_id": "PASSWORD:1",
  "unit_id": "test"
}

Content-Type: application/json

{
  "chains": [],
  "completed_methods": [],
  "current_method": "PASSWORD:1",
  "logon_process_id": "Ww323YxvYv6IVj3J3EaLNlkVM2aoHfLa",
  "msg": "Process has been started",
  "status": "MORE_DATA"
}

Logon-Process-Id: jBaYkc08vxmI9LslCJcCTZ3JUgqYn6CH
Content-Type: application/json

{
  "endpoint_session_id": "P7p3JJuenqo0SnyJ4HnbRbbJIqDhtt0u",
  "response": {
    "answer": "my-password"
  }
}