Skip to content

System Administrators

Getting Started

  1. Go to the Registration Portal.
  2. Complete and submit the form.
  3. Follow the instructions in the confirmation email.

Important

  • Provide the real name of your company or organization, as it will appear in the Afrilas app of your users.
  • You can upload your company logo by logging in to your company dashboard.
  • The identifier dictates the entity or audience SAML assertions are intended for. It makes your environment URL unique and cannot be modified.
  • The value of the user name field corresponds to the account username that is used to log in to your business applications.
  • In order to complete the sign-up process, click on the link in the confirmation email. This link expires after 7 days.

Afrilas Registration!

Accessing the Dashboard

After registration, your will be able to access your company dashboard via a unique URL: https://your_company_identifier.portal.afrilas.com.

Via this dashboard, you can configure and download SAML 2.0 parameters, set up user synchronization sources, create local users, add applications, generate reports and get insights into who is performing what actions.

User Management

Log in to your dashboard to create user sources. Select Users & Groups to perform basic CRUD operations and other actions, such as adding new users and portal administrators.

In most scenarios, users will be part of an Active Directory (AD) or other user database, but they can also be be created manually.

User Sources & API Keys

User sources are user classifications by origin, e.g. Active Directory. When a new user is created or synchronized, the appropriate user source will automatically appear next to the user's identifier in the dashboard's Users & Groups overview.

When creating a new user source, an API key will automatically be generated. This key is required to set up user synchronization.

  1. Select User Sources.
  2. Click on the Create button.
  3. Follow the on-screen instructions to finish creating the user source.

User sources!

User Records

User records can either be created automatically through user synchronization or manually by an Afrilas portal administrator:

  1. Select Users & Groups.
  2. Click on the Create button.
  3. Enter the required information (check the Admin option to create a new administrator).
  4. Click on the Create User button.
  5. Enroll the user.

Adding new users!

Action Description
Create User Press to create a new user or portal administrator.
Details Click to view the account details of a user or to enroll the user.
Enroll Users must be enrolled to allow them to make use of the Afrilas Authenticator app. This can only be done by a portal administrator. Use the Send enrollment email button to send an automated e-mail invitation with step-by-step instructions.
Edit Lets you edit the user profile. Only the user's display name and administrative status can be modified.
Update User Press to save modifications made to the user account.
Delete Delete a user who no longer requires access, e.g. in case the user has left your organization.

Enrolling Users

Users must be enrolled before they can make use of the Afrilas Authenticator app. They can either be enrolled automatically via user synchronization or manually by a portal administrator:

  1. Select Users & Groups.
  2. Click on the Details of the user to be enrolled.
  3. Click on the Enroll or Send enrollment email button.

Activating new users!

Important

When users lose or damage their phone, you can reactivate their account simply by reenrolling the users after they installed the Afrilas Authenticator app on a new device.

User Synchronization

User synchronization is done through a dedicated, on-premise Afrilas User Sync component which supports the following backends and online services:

  • LDAP: Microsoft Active Directory, POSIX & FreeIPA
  • Cloud services: Azure Active Directory

The Afrilas User Sync component uses HTTPS to upload user data to Afrilas. Administrators are therefore required to configure their firewall so traffic towards TCP port 443 is allowed.

Afrilas component!

The Afrilas User Sync component is available as a Docker image, a virtual machine or a bare-metal appliance and requires an Afrilas API key for project authorization. Configuration is done through a YAML file.

  1. Pull the Afrilas User Sync component image from Docker Hub:

    docker pull axsguard/afrilas-usersync

  2. Download the docker-compose.yml template or create your own file, then copy & paste the contents of the AAD or the LDAP configuration example. Provide the appropriate values for the environment variables, then save the file.

    AAD Configuration Example. 
        version: "3.0"
    volumes:
      logs: {}
    services:
      afrilas-usersync:
        image: "docker.io/axsguard/afrilas-usersync:latest"
        volumes:
        - logs:/var/log/usersync
        environment:
        - AFRILAS_SOURCE=azure  #backend type
        - AZURE_TENANT_ID=Copy & paste your AAD tenant ID
        - AZURE_APP_ID=Copy & paste the ID assigned by AAD 
        - AZURE_APP_SECRET=Copy & paste the secret assigned by AAD
        - AZURE_GROUP_ID=Copy & paste the group ID assigned by AAD
        - AFRILAS_API_KEY=Copy & paste the Afrilas API key of your user source.
        - AFRILAS_COMPANY_ID=Copy & paste your Afrilas organization identifier.
        - AFRILAS_USER_SOURCE_ID=Copy & paste your Afrilas user source identifier.
    LDAP Configuration Example. 
        version: "3.0"
    volumes:
      logs: {}
    services:
      afrilas-usersync:
        image: "docker.io/axsguard/afrilas-usersync:latest"
        volumes:
        - logs:/var/log/usersync
        environment:
        - AFRILAS_SOURCE=ad  #backend type
        - LDAP_URL=ldaps://ad.afrilas.test.example.com:636
        - LDAP_VERIFY_CA=false
        - LDAP_BIND_DN=CN=Administrator,CN=Users,DC=afrilas,DC=test,DC=example,DC=com
        - LDAP_PASSWORD=***********************************
        - LDAP_SEARCH_BASE=CN=Users,DC=afrilas,DC=test,DC=example,DC=com
        - LDAP_GROUP_DN=CN=afrilas,CN=Users,DC=afrilas,DC=test,DC=example,DC=com
        - AFRILAS_API_KEY=Copy & paste the API key of your user source.
        - AFRILAS_COMPANY_ID=Copy & paste your organization's identifier.
        - AFRILAS_USER_SOURCE_ID=Copy & paste the user source identifier.

  3. Once you are finished configuring your docker-compose.yml file, start the Docker container as follows:

    docker-compose up

    Afrilas User Sync start!

    Note

    Press Ctrl + c to gracefully exit the running container.

Azure Requirements

The Afrilas User Sync component must be registered with the Microsoft identity platform and requires User.ReadAll and GroupMember.ReadAll API permissions to be set in order to access Azure Active Directory.

You can either use a client secret or a client certificate to authenticate the Afrilas User Sync component with the Azure API. Certificates are recommended, because they are considered more secure than client secrets.

The following is an overview of the steps you need to perform in order to register the Afrilas User Sync component with the Microsoft identity platform.

New Registration

  1. Log in to Azure with an administrator account and look up your Tenant ID (Azure Active Directory -> Overview -> Tenant Information). Assign this ID to the AZURE_TENANT_ID variable.

    image!

  2. Register the Afrilas User Sync component (Azure Active Directory -> App registrations -> New registration). Provide a name for the app, e.g. Afrilas User Sync, keeping default settings. Then assign the generated application client ID to the AZURE_APP_ID variable.

    image!

  3. Depending on your authentication preference, generate either a client secret or a client certificate for the Afrilas User Sync Component.

Using a Client Secret

Important

By default, client secrets never expire. It is therefore strongly recommended to configure the secret with an explicit expiration date and time to enforce secret rotation as an additional layer of protection.

  1. Generate a secret for the Afrilas User Sync component (Azure Active Directory -> App registrations -> Afrilas User Sync -> Certificates and Secrets -> New Client secret). Provide a name, e.g. Afrilas User Sync.

    image!

  2. Assign the resulting value to the AZURE_APP_SECRET variable.

  3. Assign the ID of the group containing all your Afrilas users to the AZURE_GROUP_ID variable (Azure Active Directory -> Groups -> click on the appropriate group -> Object Id).

    image!

  4. Set the API permissions for the Afrilas User Sync component.

Using a Client Certificate

  1. Use the following openssl command to generate a client certificate for the Afrilas User Sync component:

    openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes

    Note

    Two files will be generated. The cert.pem file contains your public key and the key.pem file contains your private key.

  2. Upload the cert.pem file to Azure (Azure Active Directory -> App Registration -> Afrilas User Sync -> Certificates and Secrets -> Upload Certificate).

    image!

  3. Assign the value of the certificate thumbprint shown in your AAD dashboard to the AZURE_APP_THUMBPRINT variable.

  4. Assign the contents of the key.pem file to the AZURE_APP_KEY_DATA variable. Ensure to copy & paste all the data on a single line, starting with: -----BEGIN PRIVATE KEY-----.

  5. Assign the ID of the group containing all your Afrilas users to the AZURE_GROUP_ID variable (Azure Active Directory -> Groups -> click on the appropriate group -> Object Id).

    image!

  6. Set the API permissions for the Afrilas User Sync component.

API Permissions

Go to Azure Active Directory -> App registrations -> Afrilas User Sync -> API Permissions -> Add a Permission -> Select the Microsoft Graph -> Delegated permissions.
Ensure the User.ReadAll and GroupMember.ReadAll permissions are granted as shown below. Admin consent for these permissions is also required (see the status column in the image below).

image!

Environment Variables

Important

Only the environment variables listed below can be passed to the Afrilas User Sync component.

User Sync Variables Description Required
AFRILAS_SOURCE The type of backend used for user synchronization. The following values are supported:
  • ad: Microsoft Active Directory
  • posix_ldap: POSIX LDAP
  • freeipa: FreeIPA
  • azure: Azure AD
Note that the backend type affects the default values of the LDAP_SEARCH_FILTER variable. Whether a variable is required or not also depends on the type of backend being defined here.
AFRILAS_API_KEY Copy and paste your Afrilas API key here.
AFRILAS_COMPANY_ID Your company identifier as specified on the Afrilas registration portal, e.g. acmeinc.
AFRILAS_USER_SOURCE_ID The user source identifier as specified under User Sources in the Afrilas portal, e.g. ad.
AFRILAS_VERBOSE Sets the log severity level. Defaults to 0 if unspecified.
  • Set to 0 to log errors only.
  • Set to 1 to log basic information.
  • Set to 2 for verbose logging (troubleshooting and support).
  • Set to 3 if you are a developer.
AFRILAS_LOGFILE Provide a path and filename to write the user synchronization logs to. Defaults to /var/log/usersync/usersync.log. An empty string will disable logging, i.e. "".
AFRILAS_LOG_TO_STDOUT Set to false to stop writing user synchronization logs to STDOUT, a.k.a. standard output, which is the default file descriptor where a Unix process can write output. Defaults to true if undefined.
AFRILAS_TIMEOUT User synchronization will time out after the specified amount of seconds. Defaults to 60 seconds if unspecified.
AFRILAS_INTERVAL The synchronization interval is the period of time to wait between requests for updates from the backend server. This value is expressed in minutes. Defaults to 30 minutes if unspecified.
AFRILAS_TESTRUN Use this variable to test your configuration. Set to true to query the backend server without uploading user data to Afrilas. Set to falsewhen you are ready to upload your user data to production. Defaults to false if unspecified.
AFRILAS_RUNONCE Defaults to false when unspecified. Set to true to sync user data only once, then exit. Set to false otherwise, in which case the configured synchronization interval will be applied.

Important: Setting this variable to true in a production environment will prevent users from being removed automatically, which constitutes a security risk. See the section about automated disenrollment for additional information.
AFRILAS_PROXY Allows you to configure a proxy, e.g. http://proxy.local:3128 or http://user:pass@proxy.example.com.
AFRILAS_NO_PROXY Provide a comma-separated list of domains that should not be proxied, e.g. example.com,login.microsoft.com
Azure-specific Variables Description Required
AZURE_TENANT_ID Copy & paste your Azure Directory Tenant ID. See Azure Active Directory -> Overview -> Tenant Information.
AZURE_APP_ID Copy & paste the application client ID that you registered in Azure. See Azure Active Directory -> App registrations -> Application client ID.
AZURE_APP_SECRET This secret is required by the Afrilas User Sync component to authenticate with Azure Active Directory. Copy & paste your secret from Azure Active Directory -> App Registrations -> click 'Afrilas User sync' app -> Certificates and Secrets -> Client secrets -> Value.

Please note that certificate authentication is preferred. See the variables below for additional information. When using certificate authentication, there is no need to declare the AZURE_APP_SECRET variable.		 Depends on the selected Azure credential type.
AZURE_APP_KEY_DATA Can be used instead of AZURE_APP_SECRET. When using certificate authentication, your private key data should be copied here. Ensure to copy & paste all the data on a single line, starting with:
-----BEGIN PRIVATE KEY-----.

Instead of copying and pasting your private key, you can also provide the location of your private key using the AZURE_APP_KEY_FILE variable below.		 Depends on the selected Azure credential type.
AZURE_APP_KEY_FILE Can be used instead of AZURE_APP_KEY_DATA and should point to the location of your private key, e.g. /tmp/key.pem. The file must be provided via a separate volume. Only required for certificate authentication.
AZURE_APP_THUMBPRINT When using certificate authentication, copy & paste the thumbprint of the app certificate. See Azure Active Directory -> App Registrations -> Certificates & Secrets -> Upload Certificate. Only required for certificate authentication.
AZURE_GROUP_ID Copy & paste the ID of the group containing all your Afrilas users. See Azure Active Directory -> Groups -> click on the appropriate group -> Object Id.
AZURE_EXTRA_PROPERTIES Only required for specific SAML attributes. Office 365 requires the use of an IDPEmail and NameID attribute for each user, e.g.

IDPEmail=userPrincipalName,NameID=ImmutableID.
LDAP-specific Variables Description Required
LDAP_URL Required for LDAP backends only. Provide the LDAP URL including the scheme, hostname or address, and port, e.g. ldaps://ad.example.com:636.
LDAP_CA_FILE This file is used for CA verification (LDAPS only). Provide the location of the CA certificate used to sign the certificate of your LDAP server, e.g. /tmp/ca.crt. This file must be provided via a separate volume. If no file is provided, no CA verification is performed.
LDAP_CA_DATA Alternative for the LDAP_CA_FILE variable. Copy and paste your LDAP CA certificate data here. Ensure to copy all the data on a single line, starting with: -----BEGIN CERTIFICATE-----.
LDAP_VERIFY_CA Set to false to disable LDAPS CA verification. This variable is set to true by default. If a CA certificate is not provided, this variable must be set to false.
LDAP_BIND_DN Provide an account with LDAP search and read permissions. Use string-encoded ASN.1 syntax, e.g. cn=afrilas,cn=users,dc=example,dc=com.
LDAP_PASSWORD The password of the LDAP user assigned to the LDAP_BIND_DN variable.
LDAP_SEARCH_BASE The search base denotes the location in the LDAP directory structure where the search for a particular directory object begins, e.g. dc=example,dc=com.
LDAP_GROUP_DN The DN of the group that all Afrilas users must be a member of, e.g. cn=afrilas,dc=example,dc=com.
LDAP_SEARCH_FILTER LDAP filters can be used to further restrict the number of users that are permitted to access Afrilas.

If the AFRILAS_SOURCE variable is set to freeipa or posix_ldap, the following filter is applied by default: (&(objectClass=person)(!(nsaccountlock=TRUE))).

If the AFRILAS_SOURCE variable is set to ad, the default filter only syncs enabled Active Directory users.
LDAP_ATTR_DISPLAYNAME Specify to override the displayname attribute. Defaults to displayName.
LDAP_ATTR_EMAIL Specify to override the email attribute. Defaults to mail.
LDAP_PAGE_SIZE Maximum amount of records your LDAP server will return in one page. Defaults to 1000 if unspecified.
LDAP_EXTRA_PROPERTIES Only needed if the Service Provider requires specific SAML attributes. Use the following format: saml_prop1=ldap_prop1,saml_prop2=ldap_prop2

Authentication Activity

The authentication activity dashboard allows system administrators to monitor user registration and authentication across their organization. By clicking on an identifier in the table, administrators can view individual user details and audit events.

Authentication Activity!

Log item Description
Time Date & time of the last login (UTC).
Identifier The user ID that was supplied via the Afrilas authenticator app.
Source The user source associated with the user ID.
IP Address The IP address associated with the user's authentication device.
Country The geographic location linked to the IP address. The authentication activity dashboard is updated automatically every minute. If a country is not immediately visible after login - as shown in the image above - simply refresh the page after 1 minute.

Important

Afrilas identifiers can be reused after being deleted by a system administrator and are in no way indefinitely linked to an individual.

Example:

  1. User Bob signs in. This event will appear in the authentication activity dashboard.
  2. A system administrator deletes user Bob.
  3. Another system administrator creates a new account for a different individual and reuses the previously deleted identifier (Bob).
  4. The new user (Bob) signs in. This event will appear in the authentication activity dashboard.

Result:

The authentication activity dashboard will show two login entries for user Bob, even though they are different individuals. To avoid duplicate identifier entries in the logs, it is recommended to use a unique identifier for each new user and not to reuse identifiers that were previously deleted.

Customer Settings

Via this page, you can update your customer settings and upload your company logo.

Field Description
Company name The name of your company or organization.
Identifier Dictates the entity or audience the SAML assertion is intended for. The identifier makes your environment URL unique and cannot be modified.
Logo Select and upload your organization's logo. This logo will appear in the user's Afrilas app. Format and size restrictions apply.
PIN timeout Maximum period in minutes before users will be requested to re-enter a PIN number or to provide biometric information as a second authentication factor, e.g. a fingerprint. Setting this parameter to 0 (zero) means that users will be asked for a second factor each time they log in.
Ping time Period, expressed in seconds, after which the Afrilas app must reply to a ping request originating from the authentication server for continuous authentication. Continuous authentication is a method of confirming the identity of users in real time after they are logged in.
  1. Select Settings.
  2. Click on Edit.
  3. Click on Update Customer when finished.

Uploading your company logo!

Service Providers

Log in to your Afrilas dashboard and go to Applications to create a new service provider (SP). Consult the SAML 2.0 documentation of your SP if necessary. Note that you must also configure the SAML integration on the SP side.

Introduction to SAML 2.0

The Security Assertion Markup Language (SAML) is an open standard that allows identity providers (IdP) to pass authorization credentials to service providers (SP).

This means users only need one set of credentials or app to log into many different applications, a.k.a. SSO. For system administrators it is a lot easier to manage one account per user than it is to manage separate accounts for email, CRM software and other applications.

SAML is especially popular with cloud-based service providers, such as Google and Salesforce, but can also be used for any other application that supports it, e.g. a VPN concentrator. Using SAML, an IdP can deliver information about user identities and access privileges to an SP in a secure and standardized manner.

There are three entities in a SAML communication:

Entity Description
User Agent Software that retrieves and presents web content for end users, typically a web browser. All SAML requests and responses pass through the user agent.
IdP Identity Provider (Afrilas). The IdP is the central system which stores and authenticates users. The IdP needs to be configured with the SP’s SAML metadata information.
SP Service Provider. The SP hosts the SAML-enabled application that is being accessed by the user and for which authentication is required, e.g. Google. The SP needs to be configured with the IdP’s SAML metadata information.

SAML entities!

IdP Parameters

IdP Parameter Description
Entity ID This is a globally unique name for a SAML entity and dictates the audience the SAML assertion is intended for. This can be any string of data up to 1024 characters, but usually consists of a name that identifies your organization or company, e.g. acmeinc.idp.afrilas.com.
SingleSignOnService URL The URL where users authenticate. In a SAML 2.0 federation, the single sign-on service URL can be initiated at the identity provider server site or the service provider site.
SingleLogoutService URL IdP URL used to make a SAML logout request to when a user signs out of Afrilas.
x509 Certificate The certificate that is used to verify signatures and establish trust in the exchange of SAML 2.0 messages.

SP Parameters

Parameter Description
Entity ID This is a globally unique name for a SAML entity. This can be any string of data up to 1024 characters, but usually consists of a name that identifies the Service Provider, e.g. google.com.
AssertionConsumerService URL SP URL where Afrilas must send the SAML assertions to.
SingleLogoutService URL URL where Afrilas sends SAML logout requests and responses when a user initiates the logout procedure, e.g. https://www.example.com/SLO
Description Enter a custom description for the SP, e.g. Google Enterprise Services.
Certificate Copy & paste the certificate of the SP. In SP-initiated SAML, the SP digitally signs the request using a private key. When the request is received by Afrilas, the digital signature is verified using the public key in the SP's certificate.
Attributes Name Format Select the appropriate format. The format indicates how to interpret the attribute name and corresponds to the <saml:Attribute NameFormat=""> element in the SAML assertion.
NameID Format The SP and Afrilas exchange information about subjects. Subjects are identified through a name identifier in a given format so that the SP can easily identify a subject based on its format. With the transient format, the subject NameID is generated randomly for temporary use. The SP accepts this value as temporary.
NameID Attribute The name of the attribute which should be used as the the NameID value when the NameID Format option is set to either emailAddress or persistent. This attribute must be present in the set of attributes exported to the SP (in the attributes array).

Authentication Flows

SAML relies on the user agent to broker the authentication flow. The flow to be followed depends on where the user makes the initial request.

There are 2 flows: the Identity Provider Initiated or IdP-initiated flow, which is not yet supported by Afrilas, and the Service Provider Initiated or SP-initiated flow, which is typically triggered when end users try to access a protected resource or sign in directly on the Service Provider side.

In the SP-initiated flow, illustrated below, the web browser will redirect the user to the IdP with a SAML authentication request.

The user will be requested to authenticate with the IdP. If authentication is successful, the IdP will return an encoded SAML response to the browser. This SAML response contains a SAML assertion which tells the service provider who the user is.

The browser sends this response to the SP for verification. If the verification is successful, the user will be granted access to the protected resource.

SP-Initiated SSO Flow!

SAML 2.0 Checklist

  1. Retrieve your SP SAML 2.0 metadata and use it to configure Afrilas.
  2. Retrieve your Afrilas SAML 2.0 metadata and use it to configure the SP.
  3. Create or sync your (test) users on Afrilas and ensure they are enrolled.