• Available authentication methods
• AkiomaUser
• ActiveDirectory
• AzureActiveDirectory
• Security settings
• HybridRealm
• Enable/Disable authentication methods
• Overall architecture
• PASOE (AkiomaUser / AD authentication)
• NodeJS (AD / AzureAD authentication)
• Authentication via Azure AD
• Configuration for config.js (required)
• Cofiguration for azure-config.js (required for Active Directory Authentication)
• Options for the Active Directory configuration file
• Basic setup for AD Authentication
• Configuration for config.js (required)
• Cofiguration for ad-config.js (required for Active Directory Authentication)
• Options for the Active Directory configuration file
• Setup Required for Azure AD Authentication
• Multi-Factor Authentication
• Step-by-Step Guide Providers and Domains
• Setting Up Security Hub
• 1. Configuring the SAML Provider in Security Hub
• Setting Up Azure AD
• 2. Integrating Azure AD SAML with Security Hub
• Additional Security Hub Settings
• 3. Finalizing Configuration in Security Hub

Available authentication methods

AkiomaUser

Front-end - Back-end interaction:

Logic-flow:

Basic HybridRealm authentication. The PASOE validates the provided credentials (username & password) directly, through HybridRealm, using the ISwatAuthenticationService.

In order to use AkiomaUser authentication, in the pasoe-config.xml / OEPAS_config.xml configuration file, the AllowedAuthentication property must contain AkiomaUser:

<AllowedAuthentication>AkiomaUser</AllowedAuthentication>

Note: In case AllowedAuthentication is missing from the config file, the default is AkiomaUser.

ActiveDirectory

Front-end - Back-end interaction:

Logic-flow:

1. The client sends POST request with AD credentials to the "/web/Login/Login.html" access-point on the PASOE (swat-backend).
2. PASOE forwards AD credentials to the "/auth/ad/login" on the NodeJS (node-main).
3. NodeJS handles AD authentication, using passport with passport-ldapauth strategy. Then responds with ssoSessionId & ssoUserId.
4. PASOES passes back to Client the ssoSessionId & ssoUserId.
5. Client logins into PASOE, with ssoUserId & ssoSessionId, through HybridRealm.
6. PASOE HybridRealm handles login using ISwatAuthenticationService, which sends POST request to "/sessions", with ssoSessionId & ssoUserId, on the NodeJS.
7. NodeJs responds back to PASOE with the session's validity.
8. PASOE finalizes authentication process.
9. Client is authenticated.

In order to use ActiveDirectory authentication, the following configuration settings must be present in pasoe-config.xml / OEPAS_config.xml:

• AllowedAuthentication containing "ActiveDirectory" - See AllowedAuthentication.
• ssoAuthenticationURI - node-main access-point for AD authentication - takes username, password
• ssoAuthenticationCheckURI - node-main access-point for checking if a valid SSO session was created, for verifying if the AD authentication was successful.
• ssoAuthenticationSecretKey - OPTIONAL secret key known by PASOE and node-main that is passed in the requests to node-main. Provides additional validation that the requests are done from a trusted source (PASOE).

Example:

	<AllowedAuthentication>ActiveDirectory</AllowedAuthentication>
	<ssoAuthenticationURI>http://localhost:8888/auth/ad/login</ssoAuthenticationURI>
	<ssoAuthenticationCheckURI>http://localhost:8888/sessions</ssoAuthenticationCheckURI>
	<ssoAuthenticationSecretKey>12345678901</ssoAuthenticationSecretKey><!-- OPTIONAL -->

Note: node-main is hidden behind PASOE server from the client's perspective.

AzureActiveDirectory

TBD by Sergiu Morar / Sebastian Lucaciu

Security settings

HybridRealm

Overview

Configuration

In order to use HybridRealm as the authentication provider of spring.security, the following configuration settings must be set:

oeablSecurity.properties

• http.all.authmanager Authentication manager to use, in our case: oerealm
• client.login.model Authentication model to use, in our case: form
• OERealm.UserDetails.realmClass OERealm (HybridRealm) class to use, in our case: Akioma.Security.HybridRealm

Unauthenticated routes

To define routes that do not require authentication, modify the oeablSecurity.csv configuration file and set the desired URIs to permitAll():

Example for LoginWebHandler /web/Login/ routes:

# "url-pattern","<method>","<spring-access-expression>"

# Permit unauthenticated access to /web/Login/**
"/web/Login/**","*","permitAll()"

# Authentication for /web/**
"/web/**","*","hasAnyRole('ROLE_PSCUser')"

# Best practice - deny anything not explicitly granted
"/**","*","denyAll()"

Note: To override access for a specific/sub-route: have the override setting before the parent setting. Example: /web/Login sub-route config overrides /web route config, thus it is set before.

Enable/Disable authentication methods

In order to use the existing AkiomaUser and/or ActiveDirectory authentication/s, the <AllowedAuthentication> property must be present in the pasoe-config.xml / OEPAS_config.xml configuration file.

The AllowedAuthentication property is a comma separated list, containing enabled authentication methods. Default value is "AkiomaUser".

Example:

<AllowedAuthentication>AkiomaUser,ActiveDirectory</AllowedAuthentication>

The property is checked, during the authentication processes, if the current authentication is allowed.

Example for AkiomaUser check:

    METHOD PROTECTED VOID CheckIsAllowedAkiomaUserAuth():
        IF LOOKUP("AkiomaUser", SessionManager:AllowedAuthentication) EQ 0 THEN
            UNDO, THROW NEW Exception("AkiomaUser authentication is disabled!", 1).
    END METHOD.

Overall architecture

PASOE (AkiomaUser / AD authentication)

NodeJS (AD / AzureAD authentication)

Authentication via Azure AD

Configuration for config.js (required)

• copy config.example and rename file to config.js. replace secret with a random generated secret. You can use for example https://randomkeygen.com/

Cofiguration for azure-config.js (required for Active Directory Authentication)

• copy azure-config.example and rename file to azure-config.js. In order to setup your own Azure installation you need to setup the following settings in the azure-config.js file:1. Login to azure under https://portal.azure.com/2. Under App Registrations, register your new application. It will ask you for name, supported accounts and redirect uri Name and supported accounts please setup as per your preferences. Redirect url required is https://login.akiomacloud.de/auth/azure/openid/returnwhere https://login.akiomacloud.de would be the domain running the Node.js server 2. Update the metadata link in azure-config.js with the new tenant information identityMetadata: 'https://login.microsoftonline.com/24981a26-eb7a-4f13-95d4-66827d36dec8/.well-known/openid-configuration' Where '24981a26-eb7a-4f13-95d4-66827d36dec8' is the tenant id (see screenshot) 3. Update the new clientID in the azure-config.js file to match your application clientID. clientID: '87f210d2-d3af-43dd-ba98-07adaff3e791', (see screenshot) 4. Go to the newly registered application settings and generate a new secret key. Use this key in the config file for azure(azure-config.js) clientSecret: 'xxxxx?=xxxxxx_xxxxxx?EQphp_e0[=5' This can be found in the application settings, App Registrations -> select application -> under Certificates & secrets (see screenshot)
Copy

const config = {
    path: '/login',
	clientID: '87f210d2-d3af-43dd-ba98-07adaff3e791',
	resource: '00000002-0000-0000-c000-000000000000',
	clientSecret: 'xxxx?=xxxxxx_xxxxxx?EQphp_e0[=5',
	identityMetadata: 'https://login.microsoftonline.com/24981a26-eb7a-4f13-95d4-66827d36dec8/.well-known/openid-configuration',
	responseType: 'code',
	responseMode: 'form_post',
	redirectUrl: 'https://login.akiomacloud.de/auth/openid/return',
	allowHttpForRedirectUrl: false,
	validateIssuer: false,
	issuer: null,
	passReqToCallback: false,
	loggingLevel: 'error',
	nonceLifetime: null,
	nonceMaxAmount: 5,
	clockSkew: null
};
module.exports = config;







5. After setting up all the required configuration, restart your Node.js server and you are good to go!

Options for the Active Directory configuration file

• path : path for login authentication, '/login' will setup a new http route at 'auth/azure/login' for authentication
• clientID : the clientID key required for the login. This will be automatically placed in the login request as a form paramenter
• resource : your app id uri
• clientSecret : When responseType is not id_token, we have to provide client credential to redeem the authorization code.
• identityMetadata : The metadata endpoint provided by the Microsoft Identity Portal that provides the keys and other important information at runtime.
• responseType : Must be 'code', 'code id_token', 'id_token code' or 'id_token'. For login only flows you can use 'id_token'; if you want access_token, use 'code', 'code id_token' or 'id_token code'.
• responseMode : Must be 'query' or 'form_post'. This is how you get code or id_token back. 'form_post' is recommended for all scenarios.
• redirectUrl : Must be a https url string, unless you set allowHttpForRedirectUrl to true. This is the reply URL registered in AAD for your app. Production environment should always use https for redirectUrl.
• allowHttpForRedirectUrl : Required to set to true if you want to use http url for redirectUrl like http://localhost:3000.
• validateIssuer : Required to set to false if you don't want to validate issuer, default value is true. We validate the iss claim in id_token against user provided issuer values and the issuer value we get from tenant-specific endpoint. If you use common endpoint for identityMetadata and you want to validate issuer, then you have to either provide issuer, or provide the tenant for each login request using tenantIdOrName option in passport.authenticate
• issuer : This can be a string or an array of strings. See validateIssuer for the situation that requires issuer.
• passReqToCallback : Required to set to true if using req as the first paramter in the verify function, default value is false. See section 5.1.1.3 for more details.
• loggingLevel : Logging level. 'info', 'warn' or 'error'.
• nonceLifetime : The lifetime of nonce in session in seconds. The default value is 3600 seconds.
• nonceMaxAmount : The max amount of nonce you want to keep in session or cookies. The default number is 10.
• clockSkew : This value is the clock skew (in seconds) allowed in token validation. It must be a positive integer. The default value is 300 seconds.

In the PASOE config file, the configuration required for setting the generic login screen and azure authentication

eg.

<LoginScreen>loginGenericW</LoginScreen>

For the Authentication in Node.js we also need to provide the URL:

eg.

<ssoAuthenticationURI>https://login.akiomacloud.de/auth</ssoAuthenticationURI>

The allowed authentication for Azure is called AzureActiveDirectory. You can specify one authentication or multiple authentication strategies via a comma delimited list.

eg.

<AllowedAuthentication>AzureActiveDirectory,AkiomaUser</AllowedAuthentication>

Basic setup for AD Authentication

Configuration for config.js (required)

• copy config.example and rename file to config.js. replace secret with a random generated secret. You can use for example https://randomkeygen.com/

Cofiguration for ad-config.js (required for Active Directory Authentication)

• copy ad-config.example and rename file to ad-config.js.
Copy

const config = {
    path: '/login',
    url: 'ldap://de.XXXXX.ch:389',
    bindDN: 'CN=adreader,OU=XXXX,DC=de,DC=XXXXX,DC=ch',
    bindCredentials: 'xsdsdsds',
    searchBase: 'DC=de,DC=XXXXX,DC=ch',
    searchFilter: '(&(sAMAccountName={{username}})(memberOf=CN=XXXX-XXXX,OU=XXXX,DC=de,DC=XXXX,DC=ch))',
    errorMessages: {
      badRequestMessage: 'Missing credentials',
      invalidCredentials: 'Invalid username/password',
      userNotFound: 'Invalid username/password',
      constraintViolation: 'Exceeded password retry limit, account locked',
      invalidLogonHours: 'Not Permitted to login at this time',
      invalidWorkstation: 'Not permited to logon at this workstation',
      passwordExpired: 'Password expired',
      accountDisabled: 'Account disabled',
      accountExpired: 'Account expired',
      passwordMustChange: 'User must reset password',
      accountLockedOut: 'User account locked',
      noSuchObject: 'Bad search base'
    }
  };

  module.exports = config;

Options for the Active Directory configuration file

• path : path for login authentication, '/login' will setup a new http route at 'auth/ad/login' for authentication
• url : LDAP server url
• bindDN : Admin connection DN, e.g. uid=myapp,ou=users,dc=example,dc=org. Optional. If not given at all, admin client is not bound. Giving empty string may result in anonymous bind when allowed.
• bindCredentials : Password for bindDN
• searchBase : The base DN from which to search for users by username. E.g. ou=users,dc=example,dc=org
• searchFilter : LDAP search filter with which to find a user by username, group, e.g. '(&(sAMAccountName={{username}})(memberOf=CN=OSIV-Ivdat,OU=OSIV,DC=de,DC=ivnet,DC=ch))'. Use the literal {{username}} to have the given username interpolated in for the LDAP search.
• errorMessages : Authentication possible error messages options
Copy

 [errorMessages.badRequestMessage] - 'Missing credentials' - Message for missing username/password
 [errorMessages.invalidCredentials] - 'Invalid username/password' - Message for InvalidCredentialsError, NoSuchObjectError, and /no such user/ LDAP errors
 [errorMessages.userNotFound] - 'Invalid username/password' - Message for user not found
 [errorMessages.constraintViolation] - 'Exceeded password retry limit, account locked' - Message when account is locked (or other constraint violation)
 [errorMessages.invalidLogonHours] - 'Not Permitted to login at this time'  - Message for Windows AD invalidLogonHours error
 [errorMessages.invalidWorkstation] - 'Not permited to logon at this workstation' - Message for Windows AD invalidWorkstation error
 [errorMessages.passwordExpired] - 'Password expired' - Message for Windows AD passwordExpired error
 [errorMessages.accountDisabled] - 'Account disabled' - Message for Windows AD accountDisabled error
 [errorMessages.accountExpired] - 'Account expired' - Message for Windows AD accountExpired error
 [errorMessages.passwordMustChange] - 'User must reset password' - Message for Windows AD passwordMustChange error
 [errorMessages.accountLockedOut] - 'User account locked' - Message for Windows AD accountLockedOut error
 [errorMessages.noSuchObject] - 'Bad search base' - Bad search base in LDAP query

Example that use the searchFilter to allow authentication base on sAMAccountName:

 searchFilter: '(&(sAMAccountName={{username}})(memberOf=CN=OSIV-Ivdat,OU=OSIV,DC=de,DC=ivnet,DC=ch))',

Example that uses the searchFilter to allow authentication based on userPricipalName:

searchFilter: '(&(userPrincipalName={{username}})(memberOf=CN=OSIV-Ivdat,OU=OSIV,DC=de,DC=ivnet,DC=ch))',

Example that uses the searchFilter to allow authentication based on userPricipalName or sAMAccountName:

searchFilter: '(&(|(userPrincipalName={{username}})(sAMAccountName={{username}}))(memberOf=CN=OSIV-Ivdat,OU=OSIV,DC=de,DC=ivnet,DC=ch))',

More LDAP Query Examples for AD here

Setup Required for Azure AD Authentication

The required list of required information in order to setup the Azure AD Authentication is as follows:

identityMetadata - metadata link with tenant(directory ID) information, clientID - the application ID clientSecret

This can be setup in the Azure portal as described in this walkthrough:

1. Login to azure under

https://portal.azure.com/

2. Under App Registrations, register your new application. It will ask you for name, supported accounts and redirect uri Name and supported accounts please setup as per your preferences. Redirect url required is

https://login.akiomacloud.de/auth/azure/openid/return

where

https://login.akiomacloud.de

would be the domain running the Node.js server

3. Update the metadata link in azure-config.js with the new tenant information identityMetadata: '

https://login.microsoftonline.com/24981a26-eb7a-4f13-95d4-66827d36dec8/.well-known/openid-configuration

' Where '24981a26-eb7a-4f13-95d4-66827d36dec8' is the tenant id (see screenshot)

4. Update the new clientID in the azure-config.js file to match your application clientID. clientID: '87f210d2-d3af-43dd-ba98-07adaff3e791', (see screenshot)

5. Go to the newly registered application settings and generate a new secret key. Use this key in the config file for azure(azure-config.js)         clientSecret: 'xxxxx?=xxxxxx_xxxxxx?EQphp_e0[=5' This can be found in the application settings, App Registrations -> select application -> under Certificates & secrets (see screenshot)

6. After setting up all the required configuration, restart your Node.js server and you are good to go!

Multi-Factor Authentication

Set up multi-factor authentication for a user:

• Sign in to Azure portal as an Administrator
• Go to Azure Active Directory then users
• Select multi-factor authentication tab
• Enable “multi-factor auth status” for the desired user

More informations can be found here: https://docs.microsoft.com/en-us/azure/active-directory/authentication/howto-mfa-userstates

Set up your account on Microsoft Authenticator:

• Download and install the app on your phone: https://www.microsoft.com/en-us/account/authenticator
• Go to additional security verification.https://aka.ms/mfasetup
• Select mobile app, choose your desired method and set up

More informations can be found here: https://docs.microsoft.com/en-us/azure/active-directory/user-help/user-help-auth-app-add-work-school-account

Step-by-Step Guide Providers and Domains

A domain is the word after the @ sign of a login address (for example, eddy@domain) SecurityHub uses this domain to find the appropriate service provider. The domain is unique amongst providers. If the name of the provider is a single word, then you can also use the name in the domain field.

Once the provider is found, the tenant of the provider is then retrieved. The tenant record has the pasoe domain to be used in the back-end pasoe app.

So, for example, provider AA has domain XX, with tenant YY which has a pasoe domain of "master", logging in as jls@XX finds provider AA, which belongs to tenant YY , which then creates a user in pasoe called “jls@master” The domain name in a provider is really only used by user/password providers, as SAML / OIDC providers use third-party authentication providers and the username is not provided in SecurityHub

Setting Up Security Hub

1. Configuring the SAML Provider in Security Hub

1. Log in to Security Hub with admin privileges.
2. In the Providers menu, select SAML.
3. Click New.
4. Enter Build.One.AzureAD as the service name, add a description, and choose the tenant the provider belongs to.
5. Ignore the Login URL and Provider Certificate fields (these will be entered in a later step).
6. Click Save.
7. Select the newly created provider and click the Edit button.
8. Copy the ProviderId (the code under the provider title).
9. Click Cancel.

Setting Up Azure AD

2. Integrating Azure AD SAML with Security Hub

1. Sign in to the Azure portal using a work or school account, or a personal Microsoft account.
2. In the left navigation pane, select the Azure Active Directory service.
3. Navigate to Enterprise Applications and then select All Applications.
4. To add a new application, select New application.
5. In the Add from the gallery section, type Azure AD SAML Toolkit in the search box.
6. Select Azure AD SAML Toolkit from the results panel and then add the app. Wait a few seconds while the app is added to your tenant.
7. Select Properties.
8. Choose the Assignment Required option according to your requirements:
• If this option is set to Yes, users and other apps or services must first be assigned this application before being able to access it.
• If this option is set to No, all users will be able to sign in, and other apps and services will be able to obtain an access token to this service.
9. Select Single Sign On.
10. Select SAML.
11. Click Edit in the Basic SAML Configuration panel.
12. Enter an Entity ID. This must be unique across all apps in Azure AD (Call it: b1-saml).
13. Enter a Reply URL. This should be the URL of the SecurityHub instance to be used for login, appended with /v1/auth/saml/azure/callback/<ProviderId>.
14. Enter a Sign-On URL. This should be the URL of the SecurityHub instance to be used for login, appended with /v1/auth/saml/azure/<ProviderId>.
15. Click Save.
16. Close the saml app and re-open it. Because the SAML Signing certificate needs a refresh.
17. In the SAML Signing Certificate section, download the certificate (base64).
18. In the Set up SecurityHub section, copy the Login URL.

Additional Security Hub Settings

3. Finalizing Configuration in Security Hub

1. Select the previously created SAML provider and click Edit.
2. Paste the Login URL from Azure into the Login URL field.
3. Open the downloaded certificate from Azure and paste the contents into the Public certificate field.
4. Click Save.
5. Stop the stack for your Build.One instance
6. Change the attribute ALLOWED_AUTHENTICATION from Secureable,secureableoidc to Secureable,secHubDynamicProvider
7. Start the stack again
8. Log out from B1
9. A SAML option should now appear on the login screen.

Done! Your Security Hub instance should now be configured with Azure AD SAML.

Back to Documentation

Back to Home Page