Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
The GUI automation API consist of a set of JavaScript functions which enables programmatic access to some features normally controlled by a user in the GUI. These functions are grouped in a global window.Exivity
object.
session
Control the current user session.
.login
function(string username, string password): void
Attempts to login given the username and password.
.logout
function(): void
Logs out the current user, and cleans up local storage used by the current session.
.refreshToken
function(string token): void
Attempts to use the given token to login (always refreshes the given token).
.apiRoot
function(string root): void
Set the domain (e.g. https://example.com:8002
) for the Exivity API.
navigate
Navigate the GUI.
.home
function(): void
Navigate to the root URL of the Exivity instance, which is the Dashboard if a user is currently logged in, or the login page otherwise.
.to
function(string path): void
Navigates to the given URL fragment.
report
Control the report filters and more.
.byId
function(int id): void
Select a report definition.
.depth
function(int depth): void
Select a reporting depth.
.daterangeStart
function(string start): void
Select a the reporting start date, in YYYYMMDD format.
.daterangeEnd
function(string end): void
Select a the reporting end date, in YYYYMMDD format.
.filterAccount
function(int id): void
Filter the report by showing only this account.
.showSingleAccount
function(bool show = true): void
On the summary report, show only the single account set with filterAccount
.
.showAllSummaries
function(bool show = true): void
Show all summaries if on the /reports/summary
page.
.showConsolidatedSummaries
function(bool show = true): void
Show consolidated summary on the /reports/summary
page.
.showSummaryAccounts
function(bool show = true): void
Show accounts on summary report.
.showSummaryServices
function(bool show = true): void
Show services on summary report.
.showSummaryInstances
function(bool show = true): void
Show instances on summary report.
.summaryGroupInstanceBy
function(string key): void
Group the instances on the summary report by this key. The key
argument should be one of: instances
, services
.
wait
Functions returning a Promise to make it easier to determine the state of the GUI.
.ms
function(int|float ms): Promise
Wait for ms and then resolve the returned promise.
.networkIdle
function(int waitBefore = 100, int waitAfter = 100, int timeout = 60000): Promise
Wait for the network stack to become idle, optionally specifying:
A timeout before starting to detect network traffic
A timeout after detecting that the network became idle
A timeout after which the promise will reject. Set to 0
to disable.
.syncComplete
function(): Promise
Wait for data synchronisation to complete.
Setting up Azure Active Directory is pretty straight-forward, but it helps to know the exact steps to follow, as configuraing SAML can be a bit daunting.
To add Exivity to your Azure AD applications, follow these steps:
In your Azure portal, go to the Azure Active Directory service:
In the sidebar, click Enterprise applications:
Click the New application button:
Click the Non-gallery application button:
Enter a name for the new application (i.e. My Exivity instance) and click the Add button.
Click the Configure single sign-on (required) button:
From the Single Sign-On Mode dropdown list, select SAML-based Sign-on:
Now enter the following details on this page:
The resulting page could look something like this:
Click the Configure [your application name] button:
A new pane will open with instructions. Navigate to the Exivity SAML configuration (see configuration) and copy the following options from the pane in your Azure portal:
The Exivity configuration page could look something like this:
Now unfold the Advanced menu at the bottom of the screen, and paste the following JSON data:
Then in Exivity, click the Update button
And in your Azure Portal, click the Save button:
As the last step, enable Single Sign-On in Exivity by navigating to Administration > Configuration and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:
SSO is now configured and enabled, and you can now use Azure AD to login to your Exivity instance. The login screen will look something like this:
And by clicking on the Login button, you'll be taken to the Azure AD login screen. Exivity will receive the Azure AD e-mail address and create a new user with a minimal set of permissions if no existing user is found.
Quick guide to setup ADFS access protocol in Exivity.
On ADFS side, go to Trust Relationships -> Relying Party Trusts, click on Add Relying Party Trust
Select Data Source: Enter data about the relying party manually
Specify Display Name: Exivity
Choose Profile: AD FS Profile
Configure Certificate: Leave blank
Configure URL: Leave blank
Configure Identifier: https://EXIVITY-URL /v1/auth/saml/metadata
Configure Multi-factor authentication now?: Choose I do not want to configure multi-factor authentication settings for this relying party trust at this time.
Choose Issuance Authorization Rules: Permit all users to access this relying party
Ready to Add trust: --
Click on Finish.
Right click the newly added trust: Properties
Go to Endpoints – Add SAML:
Endpoint type: SAML Assertion Consumer
Binding: POST
Trusted URL: https://EXIVITY-URL/v1/auth/saml/acs
Click on Save.
Right click the newly added trust: Edit Claim Rules
Go to Issuance Transform Rules – Add Rule
Choose Rule Type: Send Claims using a Custom Rule
Configure Claim Rule:
Claim Rule Name – Exivity
Custom Rule:
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn"]
=> issue(Type = "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = c.Value, ValueType = c.ValueType, Properties["http://schemas.xmlsoap.org/ws/2005/05/identity/claimproperties/format"] = "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress");
Finally, click on Save.
Make sure to perform the following steps with an Exivity user with enough rights (admin user)
First, go to Administration - Settings - Single sign-on and choose the SAML tab:
In a separate browser tab, open the Exivity SAML configuration and fill the following settings:
As the last step, enable Single Sign-On in Exivity by navigating to Administration > Settings and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:
SSO is now configured and enabled, and you can now use ADFS to login to your Exivity instance. The login screen will look something like this:
And by clicking on the Login button, you'll be taken to the ADFS login screen.
First, we need to add Exivity to your Auth0 applications. Follow these steps:
On the Auth0 dashboard, click the Applications menu item, and then the Create application button:
Choose a descriptive name for your application, click the Single Page Web App button, and finally the Create button:
On the application overview page, click the Settings tab:
On this page, fill out the following details and click on the Save changes button:
Click on the SAML2 addon button. On the Settings tab, fill out the following details and click the Save button:
Replace the text[Exivity Single Logout Service endpoint]
with the Single Logout Service endpoint of your Exivity instance (see endpoints)
Click on the Usage tab.
In a separate browser tab, open the Exivity SAML configuration (see configuration) and copy over the following settings:
As the last step, enable Single Sign-On in Exivity by navigating to Administration > Settings and then clicking on the System tab. Make sure the Single Sign-On option is set to Enabled, and click the Update button:
SSO is now configured and enabled, and you can now use Auth0 to login to your Exivity instance. The login screen will look something like this:
And by clicking on the Login button, you'll be taken to the Auth0 login screen. Exivity will receive the Auth0 e-mail address and create a new user in the configured user group (see configuration) if no existing user is found.
In order to use OneLogin as an Identity Provider, we need to set up a new application. To do so, navigate to the OneLogin administration, hover over Applications in the navigation bar, and click on Applications:
Click on the Add App button:
In the list of applications, search for "saml" and click on the item SAML Test Connector (IdP w/ attr w/ sign response):
Choose a descriptive name for your application and click the Save button:
Click the Configuration tab:
Refer to the endpoints section in the Single Sign On article how to obtain the endpoints values. Fill in these fields:
You need to add the OneLogin domain for your organisation to the CORS whitelist as well.
Now, we have to copy and paste some values from our OneLogin application into the Exivity instance Single Sign-on settings. In OneLogin, click on the SSO tab:
In a separate browser tab, open the Exivity SAML setting (See SAML configuration) and copy over the following settings:
Now, let's set up the OneLogin certificate in Exivity. Under the label X.509 Certificate, click the View Details link. Copy the X.509 Certificate and paste it in the X-509 certificate field in the Exivity settings.
As the last step, copy and paste this JSON object in the Advanced settings in the Exivity settings:
Now you're ready to use OneLogin as a SAML Identity Provider. Enable Single Sign-On in Exivity by navigating to Administration, Settings and then click on the System tab. Make sure the Single Sign-On option is set to an option including SAML2 Authentication:
OneLogin is now configured and enabled, and you can now use it to log in to your Exivity instance. The login screen will look something like this:
And by clicking on the Login button, you'll be taken to the OneLogin login screen. Exivity will receive the users e-mail address and create a new user in the configured user group (see configuration) if no existing user is found.
Exivity provides a full REST-API which acts as a programmatic interface to each operation supported through the Graphical User Interface (GUI). On top of that, some operations can be exclusively executed through the API (such as file uploads).
A reference guide on all API endpoints and further details about implementation and authentication can be found at https://api.exivity.com.
A simple JavaScript API is provided which enables programmatic access to some features normally controlled by a user in the GUI.
With Exivity it's possible to connect your existing AD/ADFS/AAD user directory so your end-users can benefit from an easy SSO experience.
Currently, Exivity supports the Security Assertion Markup Language (SAML) v2 protocol, supported by a large number of identity providers.
We're currently in the planning stages of developing Exivity SDKs in various languages which would make interfacing with the REST-API very straight-forward and easy to implement.
If you want to learn more, please let us know at dev@exivity.com.
Exivity can act as a SAML Service Provider (SP) which can be connected to a SAML Identity Provider (IdP). Some configuration is required to setup a secure connection.
The SAML configuration can be accessed by navigating to Administration > Settings and then clicking on the SAML tab. On this page, you'll find two sub-tabs:
Configuration: Your IdP endpoints can be entered here, along with details about the certificate used by the IdP.
Endpoints: When registering Exivity with your IdP, you need to provide these Exivity endpoints.
The configuration settings are listed below:
Using the advanced settings editor, even more options are exposed for configurating the integration. Please note that settings should be entered using a valid JSON format. Please consult with your implementation partner first before editing the advanced settings.
To view the full SAML endpoints for your Exivity instance, navigate to Administration > System and then click on the SAML tab and then the Endpoints sub-tab.
Quick guide to setup LDAP access protocol in Exivity
Make sure you are performing the following steps with a Exivity user with enough rights (admin user)
First, go to Administration - Settings - Single sign-on and choose the LDAP tab:
Fill the required Server and Attributes section parameters, and click on UPDATE.
Server section:
Attributes section:
Finally, go to the System tab, in the Core section, set the Single Sign-On parameter to Local and LDAP Authentication and click on UPDATE.
Now you can start login in Exivity using LDAP authentication.
This section only needs to be performed if you have chosen encryption SSL or TLS to authenticate with LDAP. These steps are done in the Exivity server side.
If you don't have a certificate in .pem format you can convert your current certificate with the OpenSSL tool.
Once you have your pem certificate stored in the server hard drive, take a note of its path, and create a system environmental variable LDAPTLS_CACERT . The value of this environmental variable will be the certificate full path.
Finally, restart the Exivity Web Service.
Azure AD setting
Use value
Identifier
Exivity Entity ID / Metadata URL endpoint (see endpoints)
Reply URL
Exivity Assertion Consumer Service endpoint (see endpoints)
Show advanced URL settings
Checked
Sign on URL
Optional, you can enter the URL for the Exivity interface here.
Relay State
Leave empty
User Identifier
Select user.mail
Exivity SAML setting
Use value
Entity ID
SAML Entity ID
SSO URL
SAML Single Sign-On Service URL
SLO URL
Sign-Out URL
X-509 certificate
Download the certificate by clicking the SAML Signing
Certificate - Base64 encoded link. Open the .cer
file
with a text editor and remove the text
-----BEGIN CERTIFICATE-----
,
-----END CERTIFICATE-----
and all line breaks so you
end up with a single-line base64 encoded string.
Exivity SAML setting
Use value
Entity ID
Sometimes called the Issuer or Metadata URL. Example: http://ADFS-URL/adfs/services/trust
SSO URL
The URL of the Single Sign On service endpoint. Sometimes called the SAML 2.0 Endpoint. Example: https://ADFS-URL/adfs/ls
SLO URL
The URL of the Single Logout service endpoint, suffix with ?wa=wsignout1.0
Example: https://ADFS-URL/adfs/ls/?wa=wasignout1.0
X-509 certificate
Base-64 encoded (DER) certificate, enclosed between -----BEGIN CERTIFICATE-----
and -----END CERTIFICATE-----
Advanced settings
{
"security": {
"wantXMLValidation": false
}
}
Field
Value
Allowed Callback URLs
Allowed Logout URLs
Exivity Single Logout Service endpoint (see endpoints)
Field
Value
Application callback URL
Exivity Entity ID / Metadata URL endpoint (see endpoints)
Settings
See below
Exivity SAML setting
Use value
Entity ID
Issuer
SSO URL
Identity Provider Login URL
SLO URL
Identity Provider Login URL, suffix with /logout
X-509 certificate
Download the certificate by clicking the Download Auth0 certificate link.
Open the .pem
file with a text editor and remove
the text-----BEGIN CERTIFICATE-----
, -----END CERTIFICATE-----
and all line breaks so you end up with a single-line base64 encoded string.
Advanced settings
{
"security": {
"wantXMLValidation": false
}
}
Field
Value
Audience
Entity ID / Metadata URL endpoint
Recipient
Assertion Consumer Service endpoint
ACS (Consumer) URL Validator
.*
(or specify a custom RegEx)
ACS (Consumer) URL
Assertion Consumer Service endpoint
Single Logout URL
Single Logout Service endpoint
Exivity configuration value
OneLogin field
Entity ID
Issuer URL
SSO URL
SAML 2.0 Endpoint (HTTP)
SLO URL
SLO Endpoint (HTTP)
Option
Description
Entity ID
Sometimes called the Issuer or Metadata URL.
SSO URL
The URL of the Single Sign On service endpoint. Sometimes called the SAML 2.0 Endpoint.
SLO URL
The URL of the Single Logout service endpoint.
X-509 certificate
Base-64 encoded (DER) certificate: - on a single line - without -----BEGIN CERTIFICATE-----
and -----END CERTIFICATE-----
Default user group
When a new user logs in using SSO, a user will be created in this user group.
Name
Endpoint
Description
Login URL
/v1/auth/saml/login
Initiate SAML login request. Redirects to SAML Identity Provider SSO URL set in the SAML configuration. After a successful authentication (possibly interactive), it will redirect back to this APIs ACS endpoint.
Logout URL
/v1/auth/saml/logout
Initiate SAML login request. Redirects to SAML Identity Provider SLO URL set in the SAML configuration. After the user has been logged out, it will redirect back to this APIs SLS endpoint.
Entity ID / Metadata URL
/v1/auth/saml/metadata
Metadata about the SAML Service Provider instance will be published at this URL.
Assertion Consumer Service
/v1/auth/saml/acs
If the received response from the SAML Identity Provider is valid, redirects to the Exivity dashboard.
Single Logout Service
/v1/auth/saml/sls
If the received response from the SAML Identity Provider is valid, redirects back to the login screen of Exivity.
Parameter
Explanation
Domain controllers
The domain controllers option is an array of servers located on your network that serve Active Directory. You can insert as many servers or as little as you'd like depending on your forest (with the minimum of one of course). Separate multiple servers with a single space.
Port
Depending on your chosen encryption use 389 (unencrypted or TLS) or 686 (SSL)
Timeout
The timeout option allows you to configure the amount of time in seconds that your application waits until a response is received from your LDAP server.
Encryption
Choose your desired encryption, SSL and TLS are supported. If you choose encryption make sure you read the section Setting up your security certificate.
Parameter
Explanation
Base DN
The base distinguished name is the base distinguished name you'd like to perform query operations on. (optional)
Account prefix
The account prefix option is the prefix of your user accounts in LDAP directory. This string is prepended to all authenticating users usernames. (optional)
Account suffix
The account suffix option is the suffix of your user accounts in your LDAP directory. This string is appended to all authenticating users usernames. (optional)
Default user group
When a new user logs in using LDAP, a user will be created in this user group. (recommended)