Azure Active Directory

You can add one (or more) Azure Active Directory systems as Upstream Identity Providers. Doing this will allow your team to sign in with their Active Directory username/password. If you work with more than one corporation, you may add multiple Upstream Identity Providers.

Note: you can consider using the shared ‘Sign in with Microsoft’ Identity provider, which has zero-config. See considerations.

Agilicus Front-End Create Upstream Issuer

The setup is very simple and takes less than 2 minutes to acomplish. There is a ‘stepper’ that walks you through the tasks.

First, open the admin user interface (https://admin.__MYDOMAIN__). Login as your (initial) administrative user. Nagivate to ‘Organisation’/’Authentication Issuer’. From here you may select ‘Add Provider’, adding a new identity provider.

At this stage, you will enter a Stepper which will walk you through the steps graphically. First select Azure Active Directory as the type:

Azure Application Registration

The Stepper will show screen shots of how to configure Azure, they are also here. First, select ‘Azure Active Directory’ in your Azure console:

Now create a new Application. This will be for all logins to the Agilicus platform.

Select a name. This will be shown to the user on the Login select page, we recommend making it related to your organisation. E.g. “My Company Active Directory”. In the Application stepper you are given a “Redirect URI”, paste it here.

You will now be given 3 pieces of information. A ‘Display Name’, an ‘Application (Client) ID’, and a ‘Directory (Tenant) ID’. Enter these in the appropriate spots in the Stepper.

Here you can see where this information is placed in the Agilicus Admin Stepper, from the Azure screen we have:

On the Agilicus Stepper we have:

Now we create a ‘Client Secret’. This is a shared secret between the two systems. Create this in the Azure Portal:

As a description we recommend using the same name as for the Application. If you select an Expiry (e.g. something other than Never) you must remember to update the Admin user interface at a later date.

In the Admin stepper paste the secret you received. You are now done!

Azure Claims

This section is optional. If you wish to synchronise groups, or use UPN as welll as email, you should configure a set of additional claims. Agilicus recommends:

• email — this gives access to the user ’email’ which may differ from the UPN
• onprem_sid — this is used if you will do passthrough authentication (e.g. using SAML with Citrix), or fine-grained access control on a Share
• upn — this gives access to the user principal name
• sid — this can be used to allow per session sign-out
• preferred_username — this controls how the user might interact with the system as a name

(Optional) Azure Groups

You may wish to directly import your Azure groups into Agilicus for role-based access control. To do so, enable the groups claim in Azure.

On your Azure Upstream Identity Issuer, enable the group mapping as below. You may need to use the GUUID and map to names.

Testing and Application Consent

At this stage you may try a login. You can keep the Admin portal logged in and use https://profile.MYDOMAIN to try. You should see a new Sign-In option, which is named as you have above.

The first (and only) time you select this new Sign in option, you will be presented with a question as to whether you consent to the information shared. The Information shared is your Name, and your Email. No permission is being granted to access any Azure or Office 365 information.

You are now complete. All users can now Sign in with their corporate login, no additional passwords to remember.

Advanced Grant Workflow

Identity & Authentication Methods (Authentication Issuer)

The Agilicus platform uses external Identity Providers (called Upstream Identity Providers). There are no passwords stored within the system. Supported standards include OpenID Connect (an extension of OAuth 2.0) and SAML 2.0. In turn, you will configure Authorisation in the Agilicus system. What this means is “who” is provided by a 3rd party, and “what they can do” is controlled by you, the Administrator.

Within the Authentication Issuer you have several configuration options:

1. You can configure the sign-in screen theming with your own logo and colours.
2. You can select from a set of Agilicus-Managed Upstream Identity Providers (Apple, Google, Linkedin)
3. You can add your own Identity Providers (Azure Active Directory, Microsoft ADFS, etc)
4. You can configure multi-factor authentication
5. You can control rules regarding when/how/who can authentication to the system

Concepts

User

A “User” is an identity which has a set of authorisations, a set of permissions. A user may be identified by one or more Identity Providers (e.g. Azure Active Directory, Google, Apple, etc.)

Users’ may be collected into groups, and, groups behave the same as a user for permission purposes. Groups may also aggregate other groups.

Identity Provider

An Identity Provider authenticates a user. It may do this with a password, with biometric, or with any trustworthy means. Agilicus acts as an Identity Provider for your applications.

Upstream Issuer

An Upstream Issuer is an Identity Provider that is federated in to the Identity Provider. This might include Apple, Google, Azure, Okta, Auth0, etc. The Upstream Issuer acts to authenticate a user.

Configuration

See Identity & Authentication Methods.

See Azure Active Directory.

On initial product signup you may be offered the ability to “Sign in with Microsoft (Azure, Skype, …)”. This option is a zero-configuration setup, and will allow you to assign users from any Microsoft certified source. This includes your own Active Directory, but also can include XBox Live, Skype, hotmail, etc.

Once you have signed up, you have a choice. You can continue to use this pre-setup shared Identity Provider. Or, you may configure the system to use your own Azure Active Directory.

The pro/con of each approach are discussed below.

As an administrator, you will be granting access to this shared Microsoft Issuer. The first time you sign in you will see a screen as below.

In it, you are requested to

This screen requests 2 permissions:

1. “Sign you in and read your profile”. This is granting the Agilicus platform to the following information, called ‘profile’ in OpenID terminology (for more information see Section 2.4 “Scope Values” of the OpenID Connect specification).
   • First Name
   • Last Name
   • Email
2. Maintain access to data you have given it access to. This is commonly called a ‘refresh’ token, and it allows the platform to cache access so you can sign in a second time on the same device without re-authenticating.

There is a 3rd box, ‘Consent on behalf of your organisation’. Checking this will ensure that end users are not asked these questions.

You may revoke access any time at https://myapps.microsoft.com/

Consideration: Theme & Branding

If you use the shared Identity provider you can set the theme & branding information on the initial Agilicus screen. However, once the user chooses ‘SIgn in with Microsoft’ there is no option to set branding information. The end user will see a a generic Microsoft screen.

Consideration: Auto Create users

In the event you create and assign your own Azure Active Directory Application for Agilicus you can use ‘auto create’ users. In this model you may choose to auto-trust. “If my Active Directory trusts the user, so will Agilicus”.

Groups

The ‘Group’ concept exists in several locations in Agilicus AnyX. It can apply to users (giving the ability to simplify permissions), to resources (also giving the ability to simplify permissions), and, to the system level (given administrative distinctions).

System Groups

There are 3 system groups used to govern administration:

‘admin’: a global admin, can do any action

‘apps-admin’: can create / update any resource (SSH, Desktop, Share, …)

‘users-admin’: can add/delete users, assign permission to them.

Service Accounts

A service account is a specific subset of permissions assigned to a non-human user. The most common use is the Agilicus Connector.

Service accounts (typically) do not sign in via an OpenID Connect web-based identity-provider. Instead they use an ‘Authentication Document’ which is a cryptographic proof of identity and scopes combined, which is periodically refreshed.

Service accounts behave the same as all other users for the sake of permission assignment.

When you install your Agilicus Connector, a service account is created for it at that time. If you delete the Connector, you can delete the service account for it. WARNING: do not delete the service account if the Connector is still in use (it will stop functioning).

Service accounts show up in the audits as any other user: all actions are audited individually.

Service account’s have a name which is similar to an email address, in the format of:

agent-connector-erx-service-account-kx4mfqwadgxbccz3axyrr9@serviceaccounts.agilicus.com

The email address and authentication document may be downloaded as below.

If you download the authentication document, you will see something as below. This may be used in applications you write that use the Agilicus SDK.

{
  "_builtin_original": {
    "metadata": {
      "created": "2022-05-29T23:27:39.556283Z",
      "id": "j5PLubHV....",
      "updated": "2022-05-29T23:27:39.599237Z"
    },
    "spec": {
      "auth_issuer_url": "https://auth.dbt.agilicus.cloud",
      "org_id": "5kX8JJdQ3CzY66pyAWPN3D",
      "user_id": "GWN9EKQR7U8vv9eYNJdXud"
    },
    "status": {
      "audience": "urn:api:agilicus:tokens",
      "issuer": "urn:agilicus:authentication_documents:j5PLubHV....",
      "key": "-----BEGIN PRIVATE KEY-----\n...t9F\n-----END PRIVATE KEY-----\n"
    }
  },
  "metadata": {
    "created": "2022-05-29T23:27:39.556283Z",
    "id": "j5PLubHVzuq44xDbVEBMfh",
    "updated": "2022-05-29T23:27:39.599237Z"
  },
  "spec": {
    "auth_issuer_url": "https://auth.dbt.agilicus.cloud",
    "org_id": "5kX8JJdQ3CzY66pyAWPN3D",
    "user_id": "GWN9EKQR7U8vv9eYNJdXud"
  },
  "status": {
    "audience": "urn:api:agilicus:tokens",
    "issuer": "urn:agilicus:authentication_documents:j5PLubHVzuq44xDbVEBMfh",
    "key": "-----BEGIN PRIVATE KEY-----\n...bOHt9F\n-----END PRIVATE KEY-----\n"
  }
}

---

Authentication Issuer – Custom Identity

An Identity provider holds the user database, and, authenticates users against it. Agilicus supports any OpenID-Connect based identity provider. This includes Okta, Microsoft, Google, etc.

Most customers will use the ‘Shared Identity’ feature which is zero-touch configuration. However, some will wish to implement custom rules inside their identity provider, requiring creation of a ‘new application registration’.

To add a custom provider, select ‘add provider’

You will see two choice: ‘Azure Active Directory’ (which will give you a guided walk through), or, ‘Other’. In other you will configure a row in a table.

Once you have added the row, you have these columns:

• name — what the user will see on the sign in page
• issuer — the URI (e.g. https://login.microsoftonline.com/TENANTID/v2.0)
• icon — from your theme, e.g. google, microsoft
• client id — as given by your identity provider (e.g. TENANTID)
• secret — as given by your identity provider
• auto-create — if set, users will be created automatically in Agilicus if they can sign in via this upstream identity provider. Do not use with public providers.
• type — Generic (or Microsoft for non-compatible extensions)
• offline consent — if true, ask for consent to do refresh flow (aka offline)
• request user info — if true attempt to fetch additional user info (e.g. group mappings)
• issuer external host — leave blank typically
• username key — blank (or e.g. username, email, etc)
• email key — typically email
• verifies email — if set the upstream provider forces verification of email address
• redirect uri — the redirect URI to your Agilicus-provided authentication federation. Typically https://auth.ca-1.agilicus.ca/callback

You may also use the action-button (3-dots) to configure group mappings, these will import groups from your upstream identity provider automatically

---

Auto-Create Users From Specific Domain With Google Workplace

The Agilicus Managed Upstream Providers option of ‘Google’ allows users to sign in with GMail and Google Workplace (G Suite) with zero-configuration. In some circumstances (for example, to enable the use of auto-create locked to a specific domain) you may wish to create your own Google Identity Provider setup.

To do so, we will use the Google Console, create a Credential, OAUth2, Web application, and from there obtain a client-id and client-secret.

We will then configure the list of acceptable domains which may use it, and cross-configure this information into the Agilicus admin portal.

There is no general requirement to create your own Credentials in Google: do so if you wish finer-grained control by e.g. restricting source domain, or if you have specific audit requirements.

For more information see Google’s “Getting Started With Authentication“.

At this stage, you may wish to enable “Authorized Domains” in your Google Workplace settings.

Users may now sign in to the system via this Identity Provider.

---

Authentication Issuer – Onsite Identity

In some circumstances, a local, on-premise identity provider is the best source available. The Agilicus Connector facilities, providing a bridge between a local machine acting as an authentication proxy, and a proper OpenID Connect web public interface. The user credentials are encrypted end-to-end, from the user’s browser to the backend.

Care must be taken when using Onsite Identity. If the connector facilitating is removed, any user with this as a sole identity source will be unable to sign in.