Azure AD Configuration

For the purpose of this guide:

Starting points

• Simian Portal Authentication and Authorization with Azure AD is based on the Azure AD OAuth2 Client Credentials flow.

  Client Secret and Client Certificate credentials are supported.

  Additional measures may be applied to Azure AD Enterprise Applications such as conditional access. These are strictly Azure AD side settings that are not relevant to the functioninality of Simian Portal and therefore beyond the scope and support of Simian Portal Azure AD configuration.

• The Simian Portal Azure AD Enterprise Application requires the following delegated API Permissions:

  • User.Read
  • Group.Read.All
  • GroupMember.Read.All

  Delegated permission means that a user needs to be signed-in in order for Simian Portal to be able to access Azure AD information.

• For Azure AD Enterprise Application authentication (in general thus not Simian Portal specific) users must be either:

  • Directly assigned to the Azure AD Enterprise Application, or
  • A direct member of a group assigned to the Azure AD Enterprise Application.

• For the configuration of the Azure AD Enterprise Application the following information is required:

  • The External Portal URL of the Simian Portal.
  • A certificate and private key if Simian Portal authentication is to be configured for Client Certificate credentials.

• For the configuration of Simian Portal the following Azure AD information must be collected from Azure AD:

  • Tennant ID
  • Client ID
  • Client Secret, OR Client Certificate Thumbprint
  • Object ID(s) of Portal Parent Group(s)
  • Object ID(s) of Portal Admin Group(s)

Configuring Simian Portal Access in Azure AD

The following sections provide instructions for setting up Azure AD for integration with Simian Portal for authentication and authorization.

Tenant ID

On the Azure Active Directory admin center, go to

Take note of the the Tenant ID and use it to specify either:

• Docker: the SIMIAN_PORTAL_AZURE_AD_TENANT_ID environment variable.
• config.php: the $azure_ad_config['ad_tenant'] variable.

Azure AD Enterprise Application

The first step is to create an Azure AD Enterprise Application. This application is the Azure counterpart of the Simian Portal in PHP.

To define the Azure AD Enterprise Application go to

and specify the name of the application

and click the Create button.

After a few moments, the application overview is opened.

Take note of the Application ID and use it to specify either:

• Docker: the SIMIAN_PORTAL_AZURE_AD_CLIENT_ID environment variable.
• config.php: the $azure_ad_config['client_id'] variable.

Setup Identification

In order for the Simian Portal PHP server to access the authentication service, it needs to identify itself using credentials, which can be either:

• a client secret (less secure)
• a certificate with a private key (more secure)

Please refer to Azure AD documentation for the exact differences.

To setup a credentials, go to

and click the application registration link.

Then, click

to reach the certificates & secrets page.

Client Secret

To identify using a certificate, skip this section.

To configure a client secret, click

fill in the description

and click the Add button. A new secret is added to the list.

Take note of the value (not the Secret ID) immediately after creation, it is shown only once and use it to specify either:

• Docker: the SIMIAN_PORTAL_AZURE_AD_CLIENT_SECRET environment variable.
• config.php: the $azure_ad_config['client_secret'] variable.

The setup for identification using a secret is now complete. Skip the next section.

Certificate and Private Key

To configure identification via a certificate, first obtain or create a certificate with a private key.

There are many ways to create certificates and the preferred method may vary depending on company policies. Check with the responsible department in your organization.

Example (self signed certificate):

(This should work on any Windows system that has Git installed. The equivalent openssl command can be issued on a linux system that has openssl installed.)

"C:\Program Files\Git\usr\bin\openssl.exe" req ^
	-new -newkey rsa:2048 -sha256 -days 365 -nodes -x509 ^
	-keyout portal.key ^
	-out portal.crt

The next step is to upload the certificate. Go to the certificates tab

and click

choose the certificate file to upload and specify a description

and click the Add button. The uploaded certificate is added to the list.

Take note of the thumbprint (note: columns are resizable if it is not fully visible) and use it to specify either:

• Docker: the SIMIAN_PORTAL_AZURE_AD_CERT_THUMBPRINT environment variable.
• config.php: the $azure_ad_config['cert_thumbprint'] variable.

The matching private key must be specified through either:

• Docker: by means of a volume mapping of the private key file on the host to /var/simian_portal/config/certs/portal.key.
• config.php: the $azure_ad_config['cert_private_key'] variable.

Configure Authentication in the Azure AD Enterprise Application

Go to

and click

and choose to create a Web application

and specify the Redirect URI of the portal, which must match the external url configured in either:

• Docker: the SIMIAN_PORTAL_EXTERNAL_URL environment variable.
• config.php: the $portal['external_url'] variable.

Optionally, you may want to specify the Front-channel logout URL (the external url + /logout). Then, click the Configure button.

Next, in the Advanced Settings, enable Allow public client flows.

Then, click the Save button.

Set the API Permissions

Go to

and choose

followed by

Then, select Group.Read.All, GroupMember.Read.All and User.Read and click the Add permissions button.

Grant consent by clicking

and confirm.

User Groups

User groups can be used to manage which users are granted access to:

• The Simian User Portal
• The Simian Admin Portal
• Individual Simian Apps

In order to determine whether access is granted, the following rules are applied:

Simian Portal Sign in

• To be able to sign in to the Simian Portal the user must be either:
  • Directly assigned to the Azure Application, or
  • A direct members of a Groups assigned to the Azure Application.

Simian Admin portal access

• Users that are (in)direct members of Admin Group(s) configured with either:

  • Docker: the SIMIAN_PORTAL_AZURE_AD_PORTAL_ADMIN_GROUPS environment variable.
  • config.php: the $azure_ad_config['portal_admin_groups'] variable.

  have access to the admin portal.

Simian Application access

• Groups that are direct members of the Portal Parent Group(s) configured with either:

  • Docker: the SIMIAN_PORTAL_AZURE_AD_PORTAL_PARENT_GROUPS environment variable.
  • config.php: the $azure_ad_config['portal_parent_groups'] variable.

  are listed for Simian App access control purposes in the admin portal.

• Users that are (in)direct members of groups configured in the Simian Apps configuration via the Simian Admin Portal have access to the respective Simian Apps.

NOTE: Azure AD Group ObjectID(s) are used for configuration purposes.

Suggested Azure AD set up

Per limitation of Azure AD Enterprose Applications only users directly assigned to the Azure AD Enterprise Application, or users that are a direct member of a group assigned to the Azure AD Enterprise Application can sign in. This causes some level of double book keeping to be necessary.

There are multiple approaches to configure Azure AD Enterprise Applications. Below the suggested approach with its pros and cons is given.

Assign only the Portal Parent Group(s) to Azure Application:

• Advantages:
  • Only add Portal Parent Group to the Azure AD Application once. After that it is not necessary to touch the Azure Application.
  • Portal access is arranged in one place by adding users as direct member to a Portal Parent Group.
  • Portal Parent Group(s) give(s) instant overview of which users can sign in.
  • Access to Simian Apps can be granted through (in)direct membership of user groups.
• Disadvantages:
  • All Simian Portal users must be a direct member of the Portal Parent Group, AND must be (in)direct member of user groups that grant access to Simian Apps.

Assign Portal Parent Group to Azure AD Enterprise Application

1. Configure the Portal Parent Group.
2. Assign the Portal Parent Group to the Azure Application.
3. Add all Portal Users - including Portal Admin Users - to the Portal Parent Group.
4. Add Portal User Groups, to the Portal Parent Group.
5. Add Portal Users to Portal User Groups as desired.
6. Configure the Portal Admin Group.
7. Add Portal Users to Portal Admin Group as desired.
8. Optionally add Portal Admin Group to the Portal Parent Group (The Portal Admin Group can then be assigned to Simian App(s)).

Assign Group(s) to the Azure AD Enterprise Application

Go to

and select the Simian Portal Azure AD Enterprise Application. Then, go to

and click None Selected.

Select the groups that you want to assign (the Portal Parent Group in the suggested Azure AD set up)

and click the Select button. Then, to confirm, click the Assign button. Make sure that the Role assigned is Default Access.